Skip to main content

Identity Management API guide

Updated April 12, 2022

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 Advanced Settings (formerly Classic Experience) realm to securely direct end users through unique logins and interfaces without leaving the application.

Note

Download the SecureAuth Identity Management API Postman Collection from the Product Downloads page so you can start using the API quickly, without the UI.

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. Select the Enable API for this realm check box.

    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.

    Note

    The API key looks like it comprises 64 random 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, and these values are required in the Header configuration steps you will perform later.

  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, select the Enable Authentication API check box.

    api_permissions.png

  6. Select at least one Identity Management tool to include in the API:

    User management - add / update / retrieve users and their properties

    Select 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 select User Management. This setting enables the SecureAuth Identity Platform API to connect to User properties.

    Administrator initiated password reset

    Select to let an administrator send the end user a new password requested by using an application.

    User self-service password change

    Select to let the end user input both the current password and a new password.

    User & group association (LDAP)

    Select to enable associations between existing users and groups within the LDAP data store.

    api_permissions_radius.png

  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

  1. Create a string with the following request parameters:

    • METHOD (GET) or METHOD (POST)

    • DATE/TIME

      Select one of the following header types:

      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

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

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

    For example,

    "GET\Wed, 08 Apr 2015 21:37:33.123 GMT\n1b700d2e7b7b4abfa1950c865e23e81a\n/secureauth2/api/v2/users/jsmith/factors"

  2. Create an HMAC SHA256 hash 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.

    //Non-printable bytes are produced in this step

  3. Encode the HMAC SHA256 hash in Base64.

    For example,

    F5yqdLDJddUYOlrpBlOJBh/YCUIMVCsWejuhiCrqMmw=

  4. Concatenate the "Application ID", ":", and the "Base64 encoded HMAC SHA256 hash":

    {ApplicationID:Base64EncodedHMACSHA256Hash}

    For example,

    1b700d2e7b7b4abfa1950c865e23e81a:F5yqdLDJddUYOlrpBlOJBh/YCUIMVCsWejuhiCrqMmw=

  5. Encode the value from step 4 in Base64.

    For example,

    MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOnorVGNYNG4vbFlsTmNvNjRpQkRENVJKaHFiZ0h0UGYwaEQ4d1d4bTgvWVk9

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

        Basic Step5Value

    For example,

    Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOnorVGNYNG4vbFlsTmNvNjRpQkRENVJKaHFiZ0h0UGYwaEQ4d1d4bTgvWVk9

Note

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.

Authorization header GET request example

Method: GET, 
    RequestUri: 'https://secureauth.company.com/secureauth2/api/v2/users/jsmith/factors', 
    Version: 1.1, 
    Headers: {
        Connection: Keep-Alive  
        X-SA-Ext-Date: Wed, 08 Apr 2015 21:37:33.123 GMT  
        Authorization: Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkY1eXFkTERKZGRVWU9scnBCbE9KQmgvWUNVSU1WQ3NXZWp1aGlDcnFNbXc9  
        Host: secureauth.company.com  
        Content-Length: 0
    }

Authorization header POST request example

Method: POST
    RequestUri: 'https://secureauth.company.com/secureauth2/api/v2/auth'
    Version: 1.1
    Headers: {
        Connection: Keep-Alive  
        X-SA-Ext-Date: Wed, 08 Apr 2015 21:27:30.123 GMT  
        Authorization: Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkQ2bmtlcEFFdGsvTStjcGt5V1EvaFpNWFp4UEozMkwrKzVaWmE2K3BCOFU9  
        Expect: 100-continue  
        Host: secureauth.company.com  
        Content-Length: 36  
        Content-Type: application/json; charset=utf-8
    }

Authorization header non-validation responses

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

{
  "status": "invalid",
  "message": "Missing authentication header.",
}
{
  "status": "invalid",
  "message": "Clock skew of message is outside threshold.",
}
{
  "status": "invalid",
  "message": "Authentication header value is empty.",
}
{
  "status": "invalid",
  "message": "Authentication header value's format should be 'appId:hash'.",
}
{
  "status": "invalid",
  "message": "Unknown authentication scheme.",
}
{
  "status": "invalid",
  "message": "AppId is unknown.",
}
{
  "status": "invalid",
  "message": "Authentication header has been seen before.",
}
{
  "status": "invalid",
  "message": "Invalid credentials.",
}

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. Create a string with the following request parameters from the original request data in the Configure request header section above:

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

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

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

  2. Create an HMAC SHA256 hash 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 2 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

Definitions

status

The status of userId provided (found, not_found, invalid, etc.); will always be in response

message

Additional information regarding the status; will always be in response

userId

The user ID provided; will always be in response, whether successful or not

properties:

The list of available user Profile Properties

firstName

The user's First Name entered in the SecureAuth Identity Platform Property / directory field

lastName

The user's Last Name entered in the SecureAuth Identity Platform Property / directory field

phone 1-4

The user's phone number(s) (Phone 1, Phone 2, Phone 3, Phone 4) entered in SecureAuth Identity Platform Property / directory fields

email 1-4

The user's email address(es) (Email 1, Email 2, Email 3, Email 4) entered in SecureAuth Identity Platform Property / directory fields

pinHash

The user's PIN number saved in the SecureAuth Identity Platform Property / directory field

auxId1-10

The user's auxiliary ID content (Aux ID 1 - Aux ID 10) populated in the SecureAuth Identity Platform Property / directory fields

ExtProperty1-##

Information from the user's additional property fields populated in SecureAuth Identity Platform Property / directory fields

knowledgebase
kbq1-6

The user's knowledge-based questions and answers (1 - 6) written to the SecureAuth Identity Platform data store

helpDeskKb

The user's Help Desk knowledge-based question and answer written to the SecureAuth Identity Platform data store

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

Web Admin configuration notes

Web Admin configuration:

  • The isWritable flag is configured in the WebAdmin Data tab.

Profile data edits:

  • Profile data that responds to the GET request can be updated in the WebAdmin.

  • To clear an attribute from the profile, include the schema name and an empty string.

Successful GET retrieval information

GET retrieval is successful in the following situations:

  • The retrieval includes a collection of usergroups that a user belongs to (LDAP only).

  • Groups are retrieved with the FQDN (LDAP only).

  • For the end user profile, attribute metadata is included, for example, display name, schema name, and whether or not the attribute is writable.

  • If the end user does not have data in an attribute, the attribute will not appear in the profile list, even if it is mapped in the WebAdmin.

  • The maximum number of properties that can be retrieved for each of the following attributes are:

    • "phone" = 4

    • "email" = 4

    • "auxId" = 10

    • "ExtProperty"# = 1 or more

    • knowledgeBase "kbq" = 6

Definitions

groups

CN=commonName,OU=organizationalUnitName,DC=domainComponent,DC=local: End user Distinguished Name string

For example, CN=SharePoint Developers,OU=jdoe,DC=dev,DC=local

accessHistories
userAgent

End user client software identifier

ipAddress

End user client IP address

timestamp

Time the request was made

authState

Request authorization status

Success response examples

{
  "userId": "jdoe",
  "properties": {
    "firstName": {
      "value": "John",
      "isWritable": "true"
    },
    "lastName": {
      "value": "Doe",
      "isWritable": "true"
    },
    "phone1": {      
      "value": "123-456-7890",
      "isWritable": "true"
    },
    "phone2": {
      "value": "234-567-8910",
      "isWritable": "true"
    },
    "email1": {
      "value": "jdoe@dev.local",    
      "isWritable": "true"
    },
    "email2": {
      "value": "jdoe@gmail.com",
      "isWritable": "true"
    },
    "pinHash": {
      "value": "1234",
      "isWritable": "true"
    },
    "auxId1": {
      "value": "123 Anywhere Drive",
      "isWritable": "true"
    },
    "auxId2": {
      "value": "Suite #100",
      "isWritable": "true"
    },
    "ExtProperty1": {
      "displayName": "New Property",
      "value": "John",
      "isWritable": "false"
    }
  },
  "knowledgeBase": {
    "kbq1": {
      "question": "What is your favorite color?",
      "answer": "red"     
    },   
    "kbq2": {
      "question": "What was your favorite childhood game?",
      "answer": "hide and seek"
    },
    "helpDeskKb": {
      "question": "What city were you born in?",
      "answer": "Alexandria"
    }
  },
  "groups": [
    "CN=SharePoint Developers,OU=jdoe,DC=dev,DC=local",
    "CN=SharePoint RnD,OU=jdoe,DC=admin,DC=local"
  ],
  "accessHistories": [
    {
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4)",
      "ipAddress": "192.168.1.2",
      "timeStamp": "2016-04-12T22:14:19.928868Z",
      "authState": "Success"
    }
  ],
  "status": "found",
  "message": ""
}

Failed / error response examples

{
  "status": "not_found",
  "message": "User Id was not found"
}
HTTP Status 404
{
  "status": "invalid_group",
  "message": "User Id is not associated with a valid group."
}
HTTP Status 200
{
  "status": "disabled",
  "message": "Account is disabled."
}
HTTP Status 200
{
  "status": "lock_out",
  "message": "Account is locked out."
}
HTTP Status 200
{
  "status": "password_expired",
  "message": "Password is expired."
}
HTTP Status 200

Note

See Server Error information below.

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

Notes

  • Extended properties cannot be updated.

  • The userId is included in the URL, so is not a part of the request.

  • The maximum number of properties that can be included in the message body for each of the following attributes is:

    • "phone" = 4

    • "email" = 4

    • "auxId" = 10

    • knowledgeBase "kbq" = 6

Message body example

{
  "properties": {
    "firstName": "John",
    "lastName": "Doe",
    "phone1": "123-456-7890",
    "phone2": "234-567-8910",
    "email1": "jdoe@dev.local",
    "email2": "jdoe@gmail.com",
    "pinHash": "1234",
    "auxId1": "123 Anywhere Drive"
    "auxId2": "Suite #100"
  },
  "knowledgeBase": {
    "kbq1": {
      "question": "What is your favorite color?",
      "answer": "red"
    },
    "kbq2": {
      "question": "What was your favorite childhood game?",
      "answer": "hide and seek"
    },
    "helpDeskKb": {
      "question": "What city were you born in?",
      "answer": "Alexandria"
    }
  }
}

Success response example

{
   "status": "success"
   "message": ""
}

Failed response example

{
   "status": "failed"
   "message": "Invalid username."
}
{   
   "status": "failed"
    "message": "Invalid password." 
}
{
   "status": "failed"
   "message": "Invalid email." 
}
{
   "status": "failed"
   "message": "Provider error."
}
{
   "status": "failed"
   "message": "Duplicate username." 
}
{
   "status": "failed"
   "message": "Duplicate email."
}
{
   "status": "failed"
   "message": "Unknown error."
}

Error response example

{
   "status": "error"
   "message": "Not_Found" 
}

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/

Notes

  • The request is the same as the one used for update user profile, although you can specify a user ID and password.

  • "Provider error" indicates a failure from the data provider.

  • The user is created at the root of the connection string (LDAP only).

  • To use a specific location for the user profile, the path to the correct OU must be specified in the Connection String on the Data tab.

  • The maximum number of properties that can be included in the message body for each of the following attributes are:

    • "phone" = 4

    • "email" = 4

    • "auxId" = 10

    • knowledgeBase "kbq" = 6

Message body example

{
  "userId": "jdoe",
  "password": "93$q!SAT",
  "properties": {
    "firstName": "John",
    "lastName": "Doe",
    "phone1": "123-456-7890",
    "phone2": "234-567-8910",
    "email1": "jdoe@dev.local",
    "email2": "jdoe@gmail.com",
    "pinHash": "1234",
    "auxId1": "123 Anywhere Drive",
    "auxId2": "Suite #100"
  },
  "knowledgeBase": {
    "kbq1": {
      "question": "What is your favorite color?",
      "answer": "red"
    },
    "kbq2": {
      "question": "What was your favorite childhood game?",
      "answer": "hide and seek"
    },
    "helpDeskKb": {
      "question": "What city were you born in?",
      "answer": "Alexandria"
    }
  }
}

Success response example

{
   "status": "success"
   "message": ""
}

Failed response example

{
   "status": "failed"
   "message": "Invalid username."
}
{
   "status": "failed"
    "message": "Invalid password." 
}
{
   "status": "failed"
   "message": "Invalid email." 
}
{
   "status": "failed"
   "message": "Provider error."
}
{
   "status": "failed"
   "message": "Duplicate username." 
}
{
   "status": "failed"
   "message": "Duplicate email."
}
{
   "status": "failed"
   "message": "Unknown error."
}

Error response example

{
   "status": "error"
   "message": "Not_Found" 
}

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

Notes

  • The current password does not need to be provided by the administrator.

  • A failed response references the text set up in the contextuser_changepwd 1-4 fields in the Web Admin.

    • The administrator can edit the text for these fields in the Verbiage Editor in the Web Admin.

    • To access the Verbiage Editor, open the Overview tab and click the Content and Localization link.

Message body example

{
   "password": "M@g1cHappens"
}

Success response example

{
   "status": "success"   
   "message": "Password was reset" 
}

Failed response example

{
   "status": "failed"
   "message": ""
}

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

Notes

  • The end user must provide the existing password to change the password.

  • A failed response references the text set up in the contextuser_changepwd1-4 fields in the Web Admin.

    • The administrator can edit the text for these fields in the Verbiage Editor in the Web Admin.

    • To access the Verbiage Editor, open the Overview tab and click the Content and Localization link.

Message body example

{
   "currentPassword": "M@g1cHappens",
   "newPassword": "D3fault321"
}

Success response example

{
   "status": "success"      
   "message": "Password was changed" 
}

Failed response example

{
   "status": "failed"
   "message": ""
}

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 Endpoint1

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"

Success response example

{
    "status": "success"
    "message": ""
}

Failure response example

{
    "status": "failure"
    "message": "Failed to add user to group."
} 
{
    "status": "failure"
    "message": "Group actions are not supported with the current configuration."
}

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

Message body example

{
    "userIds" : [
        "jdoe",
        "jsmith",
        "kmartin",
        "pjohnson",
    ]
}

Success response example

{
    "status": "success"
    "message": ""
}

Failure response example

{
  "failures": {
    "Sharepoint Visitors": [
      "kmartin",
      "pjohnson"
    ]
  },
  "status": "failed",
  "message": "There were 2 association errors." 
}

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"

Success response example

{
    "status": "success"
    "message": "" 
}

Failure response examples

{
    "status": "failure"
    "message": "Failed to add user to group."
} 
{
    "status": "failure"
    "message": "Group actions are not supported with the current configuration."
}

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

Message body example

{
   "groupNames" : [
       "SharePoint Visitors",
       "SharePoint Developers"
   ]
}

Success response example

{
    "status": "success"
    "message": ""
}

Failure response example

{
  "failures": {
    "jdoe": [
      "SharePoint Visitors",
      "SharePoint Developers"
    ]
  },
  "status": "failed",
  "message": "There were 2 association errors." 
}

Server error

Note

A server error returns the following response:

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