Cisco Unity Connection Provisioning Interface (CUPI) API -- Authentication and Authorization
From DocWiki
| Line 277: | Line 277: | ||
| String | | String | ||
| States the authentication rule URI | | States the authentication rule URI | ||
| - | |||
|- | |- | ||
| ObjectID | | ObjectID | ||
| Line 283: | Line 282: | ||
| String(36) | | String(36) | ||
| States the object ID of authentication rule | | States the object ID of authentication rule | ||
| - | |||
|- | |- | ||
| HackResetTime | | HackResetTime | ||
| Line 291: | Line 289: | ||
The value of the HackResetTime field should be in the range of 1-120 minutes. | The value of the HackResetTime field should be in the range of 1-120 minutes. | ||
Default Value: 30 minutes | Default Value: 30 minutes | ||
| - | |||
|- | |- | ||
| locationobjectid | | locationobjectid | ||
| Line 298: | Line 295: | ||
| The unique identifier of the Location object to which this credential policy belongs. | | 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. | The default value is the delivery location for this virtual machine system. | ||
| - | |||
|- | |- | ||
| locationURI | | locationURI | ||
| Line 304: | Line 300: | ||
| Strings | | Strings | ||
| Specifies the URI of locations | | Specifies the URI of locations | ||
| - | |||
|- | |- | ||
| LockoutDuration | | LockoutDuration | ||
| Line 312: | Line 307: | ||
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. | 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 | Default Value: 30 minutes | ||
| - | |||
|- | |- | ||
| MaxDays | | MaxDays | ||
| Line 321: | Line 315: | ||
The default value is 120 days when creating a credential policy associated with user accounts that have administrative access and privileges. | 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. | 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 | | MaxHacks | ||
| Line 329: | Line 322: | ||
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. | 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 | Default Value: 3 number | ||
| - | |||
|- | |- | ||
| MinLength | | MinLength | ||
| Line 337: | Line 329: | ||
A value of "0" means a blank credentials, that is no password or PIN is allowed. | A value of "0" means a blank credentials, that is no password or PIN is allowed. | ||
Default Value: 8 characters | Default Value: 8 characters | ||
| - | |||
|- | |- | ||
| PrevCredCount | | PrevCredCount | ||
| Line 346: | Line 337: | ||
Note: If blank credentials are allowed, then this field is ignored. | Note: If blank credentials are allowed, then this field is ignored. | ||
Default Value: 8 number | Default Value: 8 number | ||
| - | |||
|- | |- | ||
| TrivialCredChecking | | TrivialCredChecking | ||
| Line 373: | Line 363: | ||
*PIN cannot be an ascending or descending group of digits (for example, "012345" or "987654"). | *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). | *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 | | DisplayName | ||
| Line 379: | Line 368: | ||
| String(64) | | 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. | | 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 | | MinDuration | ||
| Line 388: | Line 376: | ||
Default Value: 1440 minutes. | 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. | Note: The minimum duration between credential changes is specified in minutes while the expiry warning days is expressed in terms of days. | ||
| - | |||
|- | |- | ||
| ExpiryWarningDays | | ExpiryWarningDays | ||
Revision as of 04:06, 9 September 2013
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:
If enabled, Unity Connection will verify that the credential meets the criteria as specified by the type of credential: Password (GUI):
PIN (TUI):
|
| 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 |
