Cisco Unity Connection Provisioning Interface (CUPI) API -- Authentication and Authorization

From DocWiki

Revision as of 09:04, 4 September 2013 by Subabhat (Talk | contribs)
Jump to: navigation, search

Links to Other API pages: Cisco_Unity_Connection_APIs

CUPI Guide Contents
API Overview
Index of All CUPI Documentation


Contents


About CUPI Authentication and Authorization

CUPI uses the same authentication and authorization scheme that the administration console uses. This means that the objects an administrator has access to when authenticated are determined by the roles to which the administrator is assigned. 

CUPI authenticates by using standard HTTPS and Basic authentication, so that credentials can be passed by using typical mechanisms to send username and password via HTTP headers.


Authentication Rules API

In Cisco Unity Connection, the authentication rules govern user passwords, PINs, and account lockouts for all user accounts. You use the authentication rules to secure how users access Unity Connection by phone, and how users access Cisco Unity Connection Administration and the Cisco Personal Communications Assistant (Cisco PCA).

For example, an authentication rule determines:

  • The number of failed sign-in attempts that are allowed before an account is locked.
  • The number of minutes an account remains locked before it is reset.
  • Whether a locked account must be unlocked manually by an administrator
  • The minimum length allowed for passwords and PINs.
  • The number of days before a password or PIN expires.

Administrator can use this API to create/update/delete/fetch the authentication rules. You can update various attributes of authentication rule using this API.


Listing the Authentication Rules

The following is an example of the GET request that fetch the list of authentication rules:

GET https://<connection-server>/vmrest/authenticationrules

The following is the response from the above *GET* request and the actual response will depend upon the information given by you:

<AuthenticationRules total="2">
<AuthenticationRule>
<URI>/vmrest/authenticationrules/4ceee1ae-8935-43d2-9d59-fafeb3533a91</URI>
<ObjectId>4ceee1ae-8935-43d2-9d59-fafeb3533a91</ObjectId>
<HackResetTime>30</HackResetTime>
<LocationObjectId>c50a4765-d55a-4c88-b961-45f1b9b481c5</LocationObjectId>
<LocationURI>/vmrest/locations/connectionlocations/c50a4765-d55a-4c88-b961-45f1b9b481c5</LocationURI>
<LockoutDuration>30</LockoutDuration>
<MaxDays>120</MaxDays>
<MaxHacks>7</MaxHacks>
<MinLength>8</MinLength>
<PrevCredCount>5</PrevCredCount>
<TrivialCredChecking>true</TrivialCredChecking>
<DisplayName>Recommended Web Application Authentication Rule</DisplayName>
<MinDuration>1440</MinDuration>
<ExpiryWarningDays>15</ExpiryWarningDays>
</AuthenticationRule>
<AuthenticationRule>
<URI>/vmrest/authenticationrules/f0575a72-afaa-43f1-bb3b-ae9382a9bfaa</URI>
<ObjectId>f0575a72-afaa-43f1-bb3b-ae9382a9bfaa</ObjectId>
<HackResetTime>30</HackResetTime>
<LocationObjectId>c50a4765-d55a-4c88-b961-45f1b9b481c5</LocationObjectId>
<LocationURI>/vmrest/locations/connectionlocations/c50a4765-d55a-4c88-b961-45f1b9b481c5</LocationURI>
<LockoutDuration>30</LockoutDuration>
<MaxDays>180</MaxDays>
<MaxHacks>3</MaxHacks>
<MinLength>6</MinLength>
<PrevCredCount>5</PrevCredCount>
<TrivialCredChecking>true</TrivialCredChecking>
<DisplayName>Recommended Voice Mail Authentication Rule</DisplayName>
<MinDuration>1440</MinDuration>
<ExpiryWarningDays>15</ExpiryWarningDays>
</AuthenticationRule>
</AuthenticationRules>
Response Code: 200

JSON Example

To get the details of all authentication rules (GET) using JSON, do the following:

GET https://<connection-server>/vmrest/authenticationrules
Accept: application /json
Connection: keep-alive

The following is the response from the above *GET* request and the actual response will depend upon the information given by you:

{
"@total":"2"
"AuthenticationRule":[
{
"URI":"/vmrest/authenticationrules/7b282b66-73b1-4989-9d94-3d105b6ef5e8"
"ObjectId":"7b282b66-73b1-4989-9d94-3d105b6ef5e8"
"HackResetTime":"30"
"LocationObjectId":"830e1a2d-8e90-459f-88f7-700497ba975c"
"LocationURI":"/vmrest/locations/connectionlocations/830e1a2d-8e90-459f-88f7-700497ba975c"
"LockoutDuration":"30"
"MaxDays":"120"
"MaxHacks":"7"
"MinLength":"8"
"PrevCredCount":"5"
"TrivialCredChecking":"false"
"DisplayName":"Recommended Web Application Authentication Rule"
"MinDuration":"1440"
"ExpiryWarningDays":"15"
}
{
"URI":"/vmrest/authenticationrules/cd86d247-df90-435b-9df6-d94c027bbb20"
"ObjectId":"cd86d247-df90-435b-9df6-d94c027bbb20"
"HackResetTime":"30"
"LocationObjectId":"830e1a2d-8e90-459f-88f7-700497ba975c"
"LocationURI":"/vmrest/locations/connectionlocations/830e1a2d-8e90-459f-88f7-700497ba975c"
"LockoutDuration":"30"
"MaxDays":"180"
"MaxHacks":"3"
"MinLength":"6"
"PrevCredCount":"5"
"TrivialCredChecking":"true"
"DisplayName":"Recommended Voice Mail Authentication Rule"
"MinDuration":"1440"
"ExpiryWarningDays":"15"
}
]
}
Response Code: 200


Viewing the Specific Authentication Rule

The following is an example of the GET request that lists the details of specific authentication rule represented by the provided value of authentication rule ID:

GET https://<connection-server>/vmrest/authenticationrules/<authenticationrule-objectid>

The following is the response from the above *GET* request and the actual response will depend upon the information given by you:

<AuthenticationRule>
<URI>/vmrest/authenticationrules/b3d033be-1b1c-4624-96d3-9860867d3a34</URI>
<ObjectId>b3d033be-1b1c-4624-96d3-9860867d3a34</ObjectId>
<HackResetTime>30</HackResetTime>
<LocationObjectId>c50a4765-d55a-4c88-b961-45f1b9b481c5</LocationObjectId>
<LocationURI>/vmrest/locations/connectionlocations/c50a4765-d55a-4c88-b961-45f1b9b481c5</LocationURI>
<LockoutDuration>1440</LockoutDuration>
<MaxDays>180</MaxDays>
<MaxHacks>3</MaxHacks>
<MinLength>8</MinLength>
<PrevCredCount>12</PrevCredCount>
<TrivialCredChecking>true</TrivialCredChecking>
<DisplayName>Texoma2</DisplayName>
<MinDuration>0</MinDuration>
<ExpiryWarningDays>15</ExpiryWarningDays>
</AuthenticationRule>
Response Code: 200

JSON Example

To view the details of an individual authentication rule (GET) using JSON, do the following:

GET https://<connection-server>/vmrest/authenticationrules/<authenticationrule-objectid>
Accept: application/json
Connection: keep-alive

The following is the response from the above *GET* request and the actual response will depend upon the information given by you:

{
"URI":"/vmrest/authenticationrules/7b282b66-73b1-4989-9d94-3d105b6ef5e8"
"ObjectId":"7b282b66-73b1-4989-9d94-3d105b6ef5e8"
"HackResetTime":"30"
"LocationObjectId":"830e1a2d-8e90-459f-88f7-700497ba975c"
"LocationURI":"/vmrest/locations/connectionlocations/830e1a2d-8e90-459f-88f7-700497ba975c"
"LockoutDuration":"30"
"MaxDays":"120"
"MaxHacks":"7"
"MinLength":"8"
"PrevCredCount":"5"
"TrivialCredChecking":"false"
"DisplayName":"Recommended Web Application Authentication Rule"
"MinDuration":"1440"
"ExpiryWarningDays":"15"
}
Response Code: 200


Creating a New Authentication Rule

The following is an example of POST request that can be used to create a new authentication rule.

POST https://<connection-server>/vmrest/authenticationrules
<AuthenticationRule>
<DisplayName>Texoma1</DisplayName>
</AuthenticationRule>

The response of the above POST command will be:

Response Code: 201
/vmrest/authenticationrules/<authenticationrule-objectid>

JSON Example

To create new authentication rules (POST):

POST https://<connection-server>/vmrest/authenticationrules
Accept: application/json
Content-Type: application/json
Connection: keep-alive
{
"DisplayName": "Texoma 1"
}

The following is the response from the above *POST* request and the actual response will depend upon the information given by you:

Response Code: 201
/vmrest/authenticationrules/<authenticationrule-objectid>


Updating the Authentication Rule

The following is an example of the PUT request that can be used to modify the authentication rule:

PUT https://<connection-server>/vmrest/authenticationrules/<authenticationrule-objectid>
<AuthenticationRule>
<MinLength>12</MinLength>
<LockoutDuration>140</LockoutDuration>
</AuthenticationRule>
Response Code: 204

JSON Example To update display name of authentication rule:

PUT https://<connection-server>/vmrest/authenticationrules/<authenticationrule-objectid>
Accept: application/json
Content-Type: application/json
Connection: keep-alive
{ 
"DisplayName": "Texoma_123"
}

The following is the response from the above *PUT* request and the actual response will depend upon the information given by you:

Response Code: 204


Delete the Authentication Rule

This request can be used to delete an authentication rule.

DELETE: https://<connection-server>/vmrest/ authenticationrules/<authenticationrule-objectid>
Response Code: 204


JSON Example To delete authentication rule with a valid object id:

DELETE https://<connection-server>/vmrest/authenticationrules/<authenticationrule-objectid>
Accept: application/json
Connection: keep-alive
Response Code: 204


Explanation of Data Fields

Parameter Operations Datatype Comments
URI Read Only String States the authentication rule URI
ObjectID Read Only String(36) States the object ID of authentication rule
HackResetTime Read/Write Integer The length of time (in minutes) after which if no failed logon attempts occur, the count of failed logon attempts is cleared.

The value of the HackResetTime field should be in the range of 1-120 minutes. Default Value: 30 minutes

locationobjectid Read Only String(36) The unique identifier of the Location object to which this credential policy belongs.

The default value is the delivery location for this virtual machine system.

locationURI Read Only Strings Specifies the URI of locations
LockoutDuration Read/Write Integer The length of time (in minutes) that a user who is locked out must wait until they can attempt to access the system again with this credential.

The value should be in the range of 0-1440 minutes. A value of "0" means the user is locked out until the credential/account is unlocked by an administrator. Default Value: 30 minutes

MaxDays Read/Write Integer The maximum number of days before the credential must be changed.

The default value is 180 days when creating a credential policy associated with user accounts that do NOT have administrative access or privileges (i.e., normal user account with voice mail subscription). The default value is 120 days when creating a credential policy associated with user accounts that have administrative access and privileges. The value of the MaxDays field should be in the range of 0-3563 days. A value of "0" means the credential will never expire.

MaxHacks Read/Write Integer The maximum number of failed logon attempts (hacks) before action is taken. If number of invalid attempts increase this limit, account will lockout.

The value of this field should be in the range of 0-100. A value of "0" means an unlimited number of logon attempts (i.e., no lockout) are allowed. Default Value: 3 number

MinLength Read/Write Integer The minimum number of characters or digits (PIN) required for the password. The value of this field should be in the range 1-64.

A value of "0" means a blank credentials, that is no password or PIN is allowed. Default Value: 8 characters

PrevCredCount Read/Write Integer Stores the specified number of previous credentials for a user and compares a new credential with them. The new password shall not match with the old ones given in the history.

The value of this field should be in the range of 0-25. Note: If blank credentials are allowed, then this field is ignored. Default Value: 8 number

TrivialCredChecking Read/Write Boolean A flag indicating whether Cisco Unity Connection should check against trivial credentials for extra security.

Default value: true Possible values can be:

  • false : Checking for trivial credentials is disabled
  • true : Checking for trivial credentials is enabled

If enabled, Unity Connection will verify that the credential meets the criteria as specified by the type of credential: Password (GUI):

  • The password must contain at least three of the following four characters: an uppercase character, a lowercase character, a number, or a symbol.
  • The password cannot contain the user alias or its reverse.
  • The password cannot contain the primary extension or any alternate extensions.
  • A character cannot be used more than three times consecutively (for example, !Cooool).
  • The characters cannot all be consecutive, in ascending or descending order (for example, abcdef or fedcba).

PIN (TUI):

  • PIN cannot match the numeric representation of the first or last name of the user.
  • PIN cannot contain the primary extension or alternate extensions of the user.
  • PIN cannot contain the reverse of the primary extension or alternate extensions of the user.
  • PIN cannot contain groups of repeated digits, such as "408408" or "123123."
  • PIN cannot contain only two different digits, such as "121212."
  • A digit cannot be used more than two times consecutively (for example, "28883").
  • PIN cannot be an ascending or descending group of digits (for example, "012345" or "987654").
  • PIN cannot contain a group of numbers that are dialed in a straight line on the keypad when the group of digits equals the minimum credential length that is allowed (for example, if 3 digits is allowed, the user could not use "123," "456," or "789" as a PIN).
DisplayName Read/Write String(64) The unique text name (example, "Administrator Password Policy") of the credential policy to be used when displaying entries in the administrative console, e.g. Cisco Unity Connection Administration.
MinDuration Read/Write Integer The minimum number of minutes that must pass from the time of the last change before the credential can be changed.

The range of this field can vary from 0 to 129600 minutes. A value of "0" means that there are no restrictions on how often the user can change the credential. Default Value: 1440 minutes. Note: The minimum duration between credential changes is specified in minutes while the expiry warning days is expressed in terms of days.

ExpiryWarningDays Read/Write Integer The number of days prior to the expiration of a credential when Unity Connection begins prompting a user to change their credential upon logon, until the change is made. The ExpiryWarningDays field should be set lesser than the MaxDays field as the warning must occur before expiration.

A value of "0" means that a user will not be prompted to change their credential prior to its expiration. Default Value: 15 days

Rating: 1.0/5 (3 votes cast)

Personal tools