Implementing REST – Fischer Identity Support Center

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
email	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] 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 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