Authentication and Authorization
REST does not specify a particular authentication or authorization model and therefore allow implementers to pick their own. The IdM Suite uses OAuth2 for authentication and Security Policies (PSA) for authorization.
A secret key shared between the REST client application/portal (hereafter referred to as “client”) and the Identity Server must be established and configured prior to authentication. Additionally, the UserId attribute value for that organization along with a client-id (unique three character organizational code) must be supplied during the authentication call.
This is the URI for authentication: POST /rest/oauth2/access
Prerequisites
Users on whose behalf the REST calls are made must have the identity license/bit in their profile.
Note: Users with their identity account locked and disabled cannot authenticate and use REST services. The PBWUSERID of the user is used as the unique identifier to locate the user in the identity database store.
Configuration properties in the Admin UI must be configured prior to using REST services in Identity. These are the properties available from the Admin UI->Configuration->Configuration Function Menu item ->Modify Configuration for->REST (Representational State Transfer):
- Default number of REST Items Returned Per Request - The default number of list items returned if it is not specified in the REST request. The value should be between 1 and "Maximum REST Items Per Request" property.
- Enable REST service - Enable or Disable access to REST (Representational state transfer) services from a REST client.
- Maximum REST Items Returned Per Request - The maximum number of list items returned for a REST request. The value should be between 1 and 300. If the number of items requested by a REST client exceeds this limit, the value specified here will be used as the item count to return.
- OAuth Secret Key - Secret Key used to verify REST clients during authentication.
- OAuth Session Timeout - Time period in minutes after which the REST client token is invalidated. Value range: 1 to 1440.
- Require HTTPS for REST requests - If this is True, REST clients must submit requests over a secure channel using HTTPS.
Step-by-step guide
1. The first step to invoke a rest end point is to obtain an access_token
end point : /rest/oauth2/access, method POST
Parameters:
| client_id | Required (e.g., FSC). The organization code of the client. |
|---|---|
| client_secret | Required. The secret key that the client should send in the request. This key must be mutually agreed upon and configured in the Identity Admin UI under Configuration->REST->OAuth Secret Key. This key must be protected and never transmitted over an insecure network. |
| redirect_uri | Optional. The redirection URL where the response needs to be sent. This will be ignored since it is not applicable for Identity. |
| scope | Required. The UserId attribute value of the user. This property is configured via the Identity Admin UI under Configuration->Identity Server. |
| response_type | Optional, the default is token. The requested response: an access token (token), an authorization code (code), or both (code token). Currently, the only option supported is token. |
Return Data:
| access_token | An OAuth 2.0 access token. Only returned if the user is identified in the server. The access token represents a REST client’s authorization ticket for accessing Identity REST services. The access token must be passed in with each REST call (except for the authentication service itself). |
|---|---|
| expires_in | This value is the number of milliseconds since 1 January 1970 00:00:00 UTC when the token will expire. |
| scope | The space delimited features the authenticated user can access. |
| error | An error code string returned if there was an authorization error. |
| error_description | A human-readable error message providing additional error information, returned along with the error. |
This is a sample request URL:
POST /rest/oauth2/access HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
scope=[email]&client_id=[ORG_CODE]&client_secret=[some_value]&response_type=token&redirect_uri=[some_value_not_used]
This is a sample response URL:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"expires_in":3600,
"scope":"some value"
}
2. Use the access token obtained from step one in the individual REST end points detailed below.
User
The user end points return user information by the URIs listed below.
List of URIs for User Resource
| URI | HTTP Method | HTTP Header Parameters Required | Query Parameters Supported | Resultant Data |
|---|---|---|---|---|
| /user | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
featureName: “manageOtherProfiles”representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of users that the authenticated user qualifies to perform OBO actions for. The feature provided should be an OBO feature for which the user has permission. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. |
| /user.xml | GET | Authorization: [access_token] |
featureName: “manageOtherProfiles” representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of users in XML that the authenticated user qualifies to perform OBO actions for. |
| GET | Authorization: [access_token] |
featureName: “manageOtherProfiles” representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of users in JSON that the authenticated user qualifies to perform OBO actions for. | |
| /user/{ID} | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
featureName: “profile”, “manageOtherProfiles” representation: [“minimal” or “full”] |
User attributes of a user whose PBWUSERID is supplied in the URI path. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the profile feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. |
| /user/{ID}.xml | GET | Authorization: [access_token] | featureName: “profile”, “manageOtherProfiles” representation: [“minimal” or “full”] |
Returns the user attributes of a user in XML whose PBWUSERID is supplied in the URI path. |
| /user/{ID}.json | GET | Authorization: [access_token] | featureName: “profile”, “manageOtherProfiles” representation: [“minimal” or “full”] |
Returns the user attributes of a user in JSON whose PBWUSERID is supplied in the URI path. |
Searchable Attributes
| Filter Parameter | SCIM Attribute | Product Attribute | Comments |
|---|---|---|---|
| givenName | givenName | Person-Firstname | |
| familyName | familyName | Person-Lastname | |
| formatted | formatted | Person-Fullname | |
| emails.value | Employee-Email1 | There can be multiple attributes with these names, but only those attributes with “primary” set to true for search are considered. For example, email can be of type ‘work’ and ‘home’, but search will go against ‘work’ since ‘primary’ is set true there. | |
| streetAddress | addresses.streetAddress | Location-Street | |
| locality | addresses.locality | Location-City | |
| region | addresses.region | Location-State | |
| postalCode | addresses.postalCode | Location-PostalCode | |
| phoneNumber | phoneNumbers.value | Employee-Phone | |
| userType | userType | Employee-Type | |
| title | title | Job-Title | |
| externalId | externalId | Person-SourceProfileID |
Account
The account end points return account information for a user by the URIs listed below.
List of URIs for Account Resource
| URI | HTTP Method | HTTP Header Parameters Required | Query Parameters Supported | Resultant Data |
|---|---|---|---|---|
| /account | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of accounts in JSON or XML format. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, it will return a list of the target user’s accounts. |
| /account.xml | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of accounts in XML format. If the target User ID is specified, it will return a list of the target user’s accounts. |
| /account.json | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of accounts in JSON format. If the target User ID is specified, it will return a list of the target user’s accounts. |
| /account/{ID} | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of an account in JSON or XML format. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, it will return details of the target user’s account. |
| /account/{ID}.xml | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of an account in XML format. If the target User ID is specified, it will return details of the target user’s account. |
| /account/{ID}.json | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of an account in JSON format. If the target User ID is specified, it will return details of the target user’s account. |
| /account/validate | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Validate all accounts of the authenticated user. If the target User ID is specified, it will validate all accounts of the target user. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature, must have permission to perform validateAccounts action and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The return status will be based on the HTTP header Accept parameter. Default media type is JSON. |
| /account/{ID}/validate | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Validate authenticated user’s given account. If the target User ID is specified, it will validate the given account of the target user. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature, must have permission to perform validateAccounts action and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The return status will be based on the HTTP header Accept parameter. Default media type is JSON. |
Search and sort are allowed on these Account attributes:
- id
- accountId
- accountUserName
- accountEnabled
- accountLocked
- lastLoginDate
- passwordChangeDate
- passwordChangeStatus
- passwordModifiedBy
System
The system end points return system information that a user has accounts on by the URIs listed below.
List of URIs for System Resource
| URI | HTTP Method | HTTP Header Parameters Required | Query Parameters Supported | Resultant Data |
|---|---|---|---|---|
| /system | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] |
List of systems in JSON or XML format. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, it will return a list of the target user’s systems. |
| /system.xml | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of systems in XML format. If the target User ID is specified, it will return a list of the target user’s systems. |
| /system.json | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of systems in JSON format. If the target User ID is specified, it will return a list of the target user’s systems. |
| /system/{ID} | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of a system in JSON or XML format. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, it will return details of the target user’s system. |
| /system/{ID}.xml | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of a system in XML format. If the target User ID is specified, it will return details of the target user’s system. |
| /system/{ID}.json | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of a system in JSON format. If the target User ID is specified, it will return details of the target user’s system. |
Search and Sort are supported for these System attributes:
- id
- displayName
Group
The group end points return group information associated with the connected systems that a user has accounts on by the URIs listed below.
List of URIs for Group Resource
| URI | HTTP Method | HTTP Header Parameters Required | Query Parameters Supported | Resultant Data |
|---|---|---|---|---|
| /group | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of groups in JSON or XML format. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, it will return a list of the target user’s groups. |
| /group.xml | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of groups in XML format. If the target User ID is specified, it will return a list of the target user’s groups. |
| /group.json | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of groups in JSON format. If the target User ID is specified, it will return a list of the target user’s groups. |
| /group/{ID} | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of a group in JSON or XML format. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, it will return details of the target user’s group. |
| /group/{ID}.xml | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of a group in XML format. If the target User ID is specified, it will return details of the target user’s group. |
| /group/{ID}.json | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of a group in JSON format. If the target User ID is specified, it will return details of the target user’s group. |
Search and sort are allowed on these Group attributes:
- id
- displayName
Password Policy
Password Policy represents a password policy in the IdM Suite. One password policy can be associated with multiple systems/groups. Therefore, this object is represented as an array of password policies. The URIs below return Password Policy information.
List of URIs for Password Policy Resource
| URI | HTTP Method | HTTP Header Parameters Required | Query Parameters Supported | Resultant Data |
|---|---|---|---|---|
| /pwdPolicy | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of password policies in JSON or XML format. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, it will return a list of the target user’s password policies. |
| /pwdPolicy.xml | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of password policies in XML format. If the target User ID is specified, it will return a list of the target user’s password policies. |
| /pwdPolicy.json | GET | Authorization: [access_token] | targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] pageNumber: [start index of the list] pageSize: [number of entries to be returned] sortBy: [sort field] sortOrder: [true for “asc” and false for ”desc”] |
List of password policies in JSON format. If the target User ID is specified, it will return a list of the target user’s password policies |
| /pwdPolicy/{ID} | GET | Authorization: [access_token] Accept: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] representation: [“minimal” or “full”] |
Details of a password policy in JSON or XML format. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, it will return details of the target user’s password policy. |
| /pwdPolicy/{ID}.xml | GET | Authorization: [access_token] | Details of a password policy in XML format. If the target User ID is specified, it will return details of the target user’s password policy. |
|
| /pwdPolicy/{ID}.json | GET | Authorization: [access_token] | Details of a password policy in JSON format. If the target User ID is specified, it will return details of the target user’s password policy. |
Search and sort are allowed on these Password Policy attributes:
- id
- displayName
Password Reset
Password Reset represents a password reset action in the IdM Suite. The system/group information is fetched using the IDs of the accounts where the password is being reset. The URIs below return Password Reset information.
List of URIs for Password Reset
| URI | HTTP Method | HTTP Body | HTTP Header Parameters Required | Query Parameters Supported | Resultant Data |
|---|---|---|---|---|---|
| /pwdReset | POST | String representation of JSON or XML password reset object. | Authorization: [access_token] Accept: [“application/json” or “application/xml”] content-type: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] | Reset password for the given accounts and return the status to the client. If the authenticated user is the same as the user represented by the PBWUSERID, the authenticated user should have permission for the managePasswords feature, or if they are different, the authenticated user must have permission for the manageOtherProfiles feature, must have permission to perform resetPasswords action and the user represented by the PBWUSERID should be a user who can be managed by the authenticated user. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. If the target User ID is specified, this will reset password for that user. |
| /pwdReset.xml | POST | String representation of JSON or XML password reset object. | Authorization: [authtoken] content-type: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] | Reset password for the given accounts and return the status to the client in XML format. If the target User ID is specified, this will reset password for that user. |
| /pwdReset.json | POST | String representation of JSON or XML password reset object. | Authorization: [authtoken] content-type: [“application/json” or “application/xml”] |
targetUserId: [pbwUserId of the user in OBO scenario] | Reset password for the given accounts and return the status to the client in JSON format. If the target User ID is specified, this will reset password for that user. |
Feature
Qualified REST features for the authenticated user and the actions allowed for a particular REST feature (if any) are returned by the following URIs.
List of URIs for Feature
| URI | HTTP Method | HTTP Header Parameters Required | Query Parameters Supported | Resultant Data |
|---|---|---|---|---|
| /feature | GET | Authorization:[access_token ] Accept: [ “application/json” or “application/xml” ] |
representation: [ “minimal” or “full” ] | List of REST features qualified for the authenticated user in JSON or XML format. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON.List of REST features qualified for the authenticated user in JSON or XML format. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. |
| /feature.json | GET | Authorization:[access_token ] |
representation: [ “minimal” or “full” ] | List of REST features qualified for the authenticated user in JSON format. |
| /feature.xml | GET | Authorization:[access_token ] | representation: [ “minimal” or “full” ] | List of REST features qualified for the authenticated user in XML format. |
| /feature/[featureName] | GET | Authorization:[access_token ] Accept: [ “application/json” or “application/xml” ] |
List of actions that can be performed for the given feature in JSON or XML format. The output media type will be based on the HTTP header Accept parameter. Default media type is JSON. | |
| /feature/[featureName].json | GET | Authorization:[access_token ] | List of actions that can be performed for the given feature in JSON format. | |
| /feature/[featureName].xml | GET | Authorization:[access_token ] | List of actions that can be performed for the given feature in XML format. |
Session
This is used for Self-Service session cleanup to remove the Self-Service session for the user that would normally persist in a SSO/federated environment.
URI for Session
| URI | HTTP Method | HTTP Body | HTTP Header Parameters Required | Query Parameters Supported | Resultant Data |
|---|---|---|---|---|---|
| /session/logout | POST | valid authToken | Authorization:[access_token] | None. Use Http status codes to confirm the status |