Identity Management API guide

Updated May 8, 2020

Use this guide to work with the SecureAuth® Identity Platform Identity Management APIs to leverage end user profiles from the configured data store, add and update profiles, and modify attributes in profiles. These tools enable administrators to manage end users programmatically from the website, without building connections directly to the data store.

A use case example is where an administrator uses the Identity Management APIs to access the data store for a self-service portal where end users can reset forgotten passwords, change expired passwords, and change knowledge-based answers and PINs.

Use API Identity Management tools with Authentication API features configured on the SecureAuth Identity Platform Classic Experience realm to securely direct end users through unique logins and interfaces without leaving the application.

Prerequisites

  1. Have access to the application code.

  2. Have an on-premises Active Directory (AD) with which the Identity Platform can integrate.

    The Multi-Data Store option is not compatible with the Identity Management APIs.

  3. Create a new realm or access an existing realm where the Identity Management APIs are enabled.

    You can include the API in any realm with any post authentication event as long as you integrate the appropriate directory and configure the appropriate settings.

  4. Configure the Data tab in the SecureAuth Identity Platform Web Admin.

    The GET /user and update/user functions can work with non-AD integrations.

Workflow

The following workflow guides you through the different SecureAuth Identity Platform pieces necessary to configure the Identity Management APIs. Use the steps as a check list or move through the sections that follow in sequential order.

  1. Complete the Identity Platform Web Admin configuration steps.

  2. Configure the authorization header and response header for all GET and POST requests.

  3. Configure /users endpoints and configure group association endpoints for users and groups.

Configure Identity Platform Web Admin

Only API steps are required; all other Web Admin steps are optional and should be performed based on the features you want to implement.

Make the changes to the following sections in the appropriate SecureAuth Identity Platform realm API tab.

  1. In the API tab, go to the API Key section.

  2. Check Enable API for this realm.

    60555645.png
  3. Click Generate Credentials to create a new Application ID and Application Key. The Application ID and Application Key are unique for each realm.

    The API key looks like it comprises 64random characters, but it actually comprises 32 two-character base-16 hexadecimal values. This is important when using the API key to produce the HMAC hash. These values are required in the Header configuration steps you will perform later.

    This is important to note when using the API key to produce the HMAC hash.

  4. Click Select & Copy to copy the contents from the fields.

    These values are required in the Header configuration steps you will perform later.

  5. In the API Permissions section, check Enable Authentication API.

    api_permissions.png
  6. Check at least one Identity Management tool to include in the API.

    User management - add / update / retrieve users and their properties: Use this tool to add new user profiles, and to retrieve and update existing user profiles. Updating a user profile includes setting and clearing property values in the user profile.

    If your team is using SecureAuth RADIUS 2.4.15 or later, you must check User Management. This setting enables the SecureAuth Identity Platform API to connect to User properties.

    api_permissions_radius.png

    Administrator initiated password reset: Use this tool to let an administrator send the end user a new password requested by using an application.

    Use case: End users request a new password because they have forgotten the current one.

    User self-service password change: Use this tool to let the end user input both the current password and a new password

    Use case: With the Administrator initiated password resetoption, end users enter the password sent by the administrator (the current password), and then enter a new password to perform the reset.

    User & group association (LDAP): Use this tool to enable associations between existing users and groups within the LDAP data store.

  7. Save the configuration.

Configure request header

Authentication against an API requires a configured HTTP basic authorization header and Content-Type header.

1. Add a Content-Type header with a value of application/json

2. Create an authorization request header for GET and POST requests using the steps below.

Authorization request header

A. Build a string based on the request:

A1. METHOD (GET) or METHOD (POST)

A2. DATE/TIME

Header types

IdP version

String requirements

Date

v9.1+

second-precision timestamp

X-SA-Date (custom)

v9.1+

second-precision timestamp

X-SA-Ext-Date (custom)

v9.2+

millisecond-precision timestamp

A3. APPLICATION ID (from the Identity Platform Web Admin – API Key section).

A4. PATH (API endpoint). For example: /secureauth2/api/v3/users/{userID}

B. Create an HMAC SHA256 hash of step 3 using the Application Key (from the Identity Platform Web Admin – API Key section).

This step is executed by calling the HMAC and producing the hash value.

C. Encode the HMAC SHA256 hash from step 3 in Base64.

D. Concatenate the "Application ID", ":", and the "Base64 encoded HMAC SHA256 hash" from step 3:

    ApplicationID:Base64EncodedHMACSHA256Hash

E. Encode the value from step 4 in Base64.

F. Concatenate "Basic" and the "Value of Step 5":

    Basic Step5Value
Authorization header GET / POST request examples
Authorization header non-validation response examples

When an authorization header cannot be validated, one of the following responses is returned.

3. OPTIONAL: If using the Email two-factor authentication method and a language other than US English, create an Accept-Language header to generate the Email OTP messages in the preferred language.

If the no Accept-Language header is present, then the Email OTP messages default to US English.

Configure response header

SecureAuth's API includes security hashing that ensures the integrity of the information being sent in all of the endpoints' responses from the appliance to the application.

Through a hashing algorithm, SecureAuth Identity Platform delivers a signature that can be validated by the application to ensure that no data manipulation has occurred prior to the application consuming the data.

Before sending the response to the application (initiated by the endpoint request), SecureAuth Identity Platform creates the signature and includes it in the response header (prepended by X-SA-SIGNATURE:). The application can then validate the response by hashing the date or time and content from the consumed response and the Application ID with the Application Key and compare the new hashed value with the X-SA-SIGNATURE value. The Application ID and Application Key are generated in SecureAuth Identity Platform and connect the appliance with the application for each endpoint transaction.

Application response header

In the application's code, the following is required to validate the response header's signature.

  1. Build a string based on the request.

    a. X-SA-DATE for a second-precision timestamp (from the SecureAuth Identity Platform v.1 or later response).

    b. APPLICATION ID (from SecureAuth Identity Platform Web Admin – API Key section).

    c. CONTENT (JSON Parameters from the SecureAuth Identity Platform response).

  2. Create an HMAC SHA256 hash of step 2 using the Application Key (from SecureAuth Identity Platform Web Admin – API Key section).

    This step is executed by calling the HMAC and producing the hash value.

  3. Encode the HMAC SHA256 hash from step 3 in Base64.

  4. Compare the HMAC SHA256 hash from step 3 to the X-SA-SIGNATURE value in the SecureAuth response header.

  5. Consume the response based on the comparison result.

After hashing the data, if the value exactly matches the signature provided in the SecureAuth Identity Platform response header, then the data has not been compromised. If the value does not match the response signature, then the data has been modified.

Optional: Configure X-SA-Ext-Date header

The string section for DATE/TIME can be configured to use either the second-precision UTC time or the millisecond-precision format DateTime.

If using the millisecond-precision, the date string must be included in the X-SA-Ext-Date header.

Configure /users endpoints

The following endpoints are prepended with the URL, https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v2

GET endpoint

The /users GET endpoint retrieves a list of end user profile properties. SecureAuth Identity Platform accesses and retrieves the user's profile from the username in the endpoint URL.

As a GET endpoint, there is no body, so JSON parameters are not required in the message body.

GET Endpoint

Example

/users/{userId}

https://secureauth.company.com/secureauth2/api/v2/users/jdoe

PUT / POST endpoints

The /users PUT / POST endpoints add, update, or delete end user profile properties. SecureAuth Identity Platform updates the user's profile by using the username in the endpoint URL.

PUT / POST Endpoint

Example

/users/{userId}

https://secureauth.company.com/secureauth2/api/v2/users/jdoe

POST endpoints

Use the POST endpoints to create an end-user profile, perform an administrative password reset for the end user, and enable end users to change their password when necessary.

Create user

The /users POST user endpoint creates the new end user profile, so a username is not specified in the endpoint URL

POST Endpoint

Example

/users/

https://secureauth.company.com/secureauth2/api/v2/users/

Reset user password

The/users POST resetpwd endpoint performs an administrative password reset for the end user. SecureAuth Identity Platform accesses the end user's profile, resets the user's password, and provides a new password by using the username in the endpoint URL.

Note

The following POST endpoint calls SecureAuth API v2 in the example path. SecureAuth API v2 ignores the userAccountControl status, which enables the API to reset a user password.

  • To use v2 with SecureAuth IdP v9.3.x, you must install Hotfix 9.3.0-15 or later.

  • To use v2 with the SecureAuth® Identity Platform v19.07.xx, you must install Hotfix 19.07.01-8 or later.

If you require the SecureAuth API to block userAccountControl restrictions, continue to call v1. (userAccountControl ensures that certain account statuses are handled appropriately in transactions between LDAP providers and SecureAuth Identity Platform.)

POST Endpoint

Example

/users/{userId}/resetpwd

https://secureauth.company.com/secureauth2/api/v2/users/jdoe/resetpwd

User self-service change password

The /users POST changepwd endpoint performs a password reset for the end user. SecureAuth Identity Platform accesses the end user's profile and lets the end user change that password by using the username in the endpoint URL.

POST Endpoint

Example

/users/{userId}/changepwd

https://secureauth.company.com/secureauth2/api/v2/users/jdoe/changepwd

Configure group association endpoints

Admins can use POST messages to associate users with groups and vice-versa.

Types of associations to the /users or /groups endpoint include the following:

  • Single user to single group

  • Single user to multiple groups

  • Single group to single user

  • Single group to multiple users

Single user to single group

This operation associates a single user in the data store with a single group in the data store.

No message body is required because all parameters for this request are present in the call URL.

POST Endpoint

Example

/users/{userId}/groups/{groupID to associate}

https://secureauth.company.com/secureauth2/api/v2/users/jdoe/groups/admins

Result: userID "jdoe" is associated with the groupID "admins"

Single group to multiple users

This operation associates a list of multiple users with a specified group.

For multiple users, supply the list of users in the POST message body, not the URL.

If any of the userIDs fail to POST, a failure response is generated that lists each userID that failed. userIDs not listed in the failure response successfully POSTed.

POST Endpoint

Example

/users/{userId}/groups/{groupId}/users

https://secureauth.company.com/secureauth2/api/v2/groups/Sharepoint%20Visitors/users

Result: group "Sharepoint Visitors" is associated with the list of users specified in the message body

Single group to single user

This operation associates a group in the data store with a single user in the data store; the operation is functionally equivalent to the Single user to single group operation.

No message body is required because all parameters for this request are present in the call URL.

POST Endpoint

Example

/groups/{groupID}/users/{userID to associate}

https://secureauth.company.com/secureauth2/api/v2/groups/admins/users/jdoe

Result: groupID "admins" is associated with userID "jdoe"

Single user to multiple groups

This operation associates a single user with multiple groups at the same time.

For multiple groups, supply the list of groups in the POST message body, not the URL.

If any of the groupIDs fail to POST, a failure response is generated that lists each groupID that failed. groupIDs not listed in the failure response successfully POSTed.

POST Endpoint

Example

/users/{userId}/groups

https://secureauth.company.com/secureauth2/api/v2/users/jdoe/groups

Result: user "jdoe" is associated with a list of groups specified in the message body

Server error

Note

A server error returns the following response:

{
  "status": "server_error",
  "message": "<Exception message describing the issue.>",
}
HTTP Status 500