Documentation

Introduction

Use this guide to work with SecureAuth IdP's Identity Management APIs to leverage end-user profiles from the LDAP server, add and update profiles, and modify attributes in profiles. These tools enable administrator management of end-users (and limited end-user self-management via KBA) programmatically from the website, without the need to build connections directly to the data store.

API Identity Management tools can be used along with Authentication API features configured on the SecureAuth IdP realm, so that end-users can be securely directed through unique logins and interfaces without leaving the application.

NOTE: This API guide is specifically for using Identity Management tools in SecureAuth IdP 9.0+; refer to Authentication API Guide for all other API configuration, including Behavioral Biometrics.

Refer to Authentication API 8.2 Configuration Guide for version 8.2 functionality.

Prerequisites

1. Have access to the application code.

2. Have an on-premises directory with which SecureAuth IdP can integrate.

Note

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

3. Create a New Realm or access an existing realm in which the Identity Management APIs will be enabled.

The API can be included in any realm with any Post Authentication event as long as the appropriate directory is integrated, the registration methods are enabled for 2-Factor Authentication use, adaptive authentication settings are in place, and device fingerprinting configurations are completed (if using all features).

4. Configure the Data tab in the SecureAuth IdP Web Admin.

A directory integration is required for SecureAuth IdP to pull user profile information during the login process.

SecureAuth IdP Web Admin
API
API Key

 

1. Check Enable API for this realm in the API Key section

2. Click Generate Credentials to create a new Application ID and Application Key

The Application ID and Application Key are unique per realm

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

These values will be required in the HTTP Header configuration steps below

API Permissions

 

4. 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 / or clearing property values in the user profile

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

Use case scenario: The end-user requests a new password because the current one has been forgotten

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

Used in conjunction with the Administrator initiated password reset option, the end-user enters the password sent by the administrator (the current password), and then enters a new password

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

Click Save once the configurations have been completed and before leaving the API page to avoid losing changes

HTTP Header

To authenticate against the API, an HTTP basic authorization header and Content-Type header are required.

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

2. Create an Authorization Header for all requests by following the steps below

Authorization Header

For GET endpoint:

1. Build a string based on the request

  • METHOD (GET)
  • DATE/TIME
  • APPLICATION ID (from SecureAuth IdP Web Admin)
  • PATH (API endpoint, e.g. /secureauth2/api/v1/users/{userID} )

2. Create an HMAC SHA256 hash of step 1 using the Application Key (from SecureAuth IdP Web Admin)

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

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

ApplicationID:Base64EncodedHMACSHA256Hash

5. Encode the value from step 4 in Base64

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

Basic Step5Value
 

GET Request Example
Step 1
    GET
    Wed, 08 Apr 2015 21:37:33 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /secureauth2/api/v1/users/jbeam/factors

End Result: "GET\nWed, 08 Apr 2015 21:37:33 GMT\n1b700d2e7b7b4abfa1950c865e23e81a\n/secureauth2/api/v1/users/jbeam"

Step 3
    F5yqdLDJddUYOlrpBlOJBh/YCUIMVCsWejuhiCrqMmw=

Step 4
    1b700d2e7b7b4abfa1950c865e23e81a:F5yqdLDJddUYOlrpBlOJBh/YCUIMVCsWejuhiCrqMmw=

Step 5
    MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOnorVGNYNG4vbFlsTmNvNjRpQkRENVJKaHFiZ0h0UGYwaEQ4d1d4bTgvWVk9

Step 6
    Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOnorVGNYNG4vbFlsTmNvNjRpQkRENVJKaHFiZ0h0UGYwaEQ4d1d4bTgvWVk9

End Result:
    Method: GET, 
    RequestUri: 'https://secureauth.company.com/secureauth2/api/v1/users/jbeam', 
    Version: 1.1, 
    Headers: {
        Connection: Keep-Alive  
        Date: Wed, 08 Apr 2015 21:37:33 GMT  
        Authorization: Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkY1eXFkTERKZGRVWU9scnBCbE9KQmgvWUNVSU1WQ3NXZWp1aGlDcnFNbXc9  
        Host: secureauth.company.com  
        Content-Length: 0
    }

For POST / PUT endpoint:

1. Build a string based on the request

  • METHOD (POST / PUT)
  • DATE/TIME
  • APPLICATION ID (from SecureAuth IdP Web Admin)
  • PATH (API endpoint, e.g. /secureauth2/api/v1/auth )
  • CONTENT (JSON Parameters)

2. Create an HMAC SHA256 hash of step 1 using the Application Key (from SecureAuth IdP Web Admin)

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

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

ApplicationID:Base64EncodedHMAC256Hash

5. Encode the value from step 4 in Base64

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

Basic Step5Value
 

POST Request Example
Step 1
    POST
    Wed, 08 Apr 2015 21:27:30 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /secureauth2/api/v1/auth
    {"user_id":"jbeam","type":"user_id"}

End Result: "POST\nWed, 08 Apr 2015 21:27:30 GMT\n1b700d2e7b7b4abfa1950c865e23e81a\n/secureauth2/api/v1/auth\n{"user_id":"jbeam","type":"user_id"}"

Step 3
    D6nkepAEtk/M+cpkyWQ/hZMXZxPJ32L++5ZZa6+pB8U=

Step 4
    1b700d2e7b7b4abfa1950c865e23e81a:D6nkepAEtk/M+cpkyWQ/hZMXZxPJ32L++5ZZa6+pB8U=

Step 5
    MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkQ2bmtlcEFFdGsvTStjcGt5V1EvaFpNWFp4UEozMkwrKzVaWmE2K3BCOFU9

Step 6
    Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkQ2bmtlcEFFdGsvTStjcGt5V1EvaFpNWFp4UEozMkwrKzVaWmE2K3BCOFU9

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

When an Authorization Header cannot be validated, one of the following responses will be returned:

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

3. (OPTIONAL) If utilizing the Email 2-Factor Authentication method and a different language than US English, create an Accept-Language header to generate the Email OTP messages in the preferred language

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

Information about /users Endpoints and Group Association Endpoints are documented in the sections below

/users Endpoints

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 IdP Property / directory field
  • lastName: The user's Last Name entered in the SecureAuth IdP Property / directory field
  • phone1-4: The user's phone number(s) (Phone 1, Phone 2, Phone 3, Phone 4) entered in SecureAuth IdP Property / directory field(s)
  • email1-4: The user's email address(es) (Email 1, Email 2, Email 3, Email 4) entered in SecureAuth IdP Property / directory field(s)
  • pinHash: The user's PIN number saved in the SecureAuth IdP Property / directory field
  • auxId1-10: The user's auxiliary ID content (Aux ID 1 - Aux ID 10) populated in the SecureAuth IdP Property / directory field(s)
  • ExtProperty1-##: Information from the user's additional property field(s) populated in SecureAuth IdP Property / directory field(s)

knowledgeBase:

  • kbq1-6: The user's knowledge-based questions and answers (1 - 6) written to the SecureAuth IdP data store
  • helpDeskKb: The user's Help Desk knowledge-based question and answer written to the SecureAuth IdP data store
GET Endpoint

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/users/{userId}

For example: https://secureauth.company.com/secureauth2/api/v1/users/jbeam

The /users GET endpoint retrieves a list of end-user profile properties. SecureAuth IdP can access and retrieve the user's profile via the username in the endpoint URL

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

Notes

WebAdmin Configuration

  • The isWritable flag is configured in the WebAdmin Data tab

Successful GET Retrieval

  • The retrieval includes a collection of usergroups to which a user belongs (LDAP only)
  • Groups are retrieved with the FQDN (LDAP only)
  • For the end-user profile, attribute metadata is included – e.g. 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
  • Maximum number of properties that can be retrieved for each of the following attributes
    • "phone" = 4
    • "email" = 4
    • "auxId" = 10
    • "ExtProperty"# = 1 or more
    • knowledgeBase "kbq" = 6

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

Definitions

groups:

  • CN=commonName,OU=organizationalUnitName,DC=domainComponent,DC=local: End-user Distinguished Name string
    e.g. 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 Failed Response / Error
{   
  "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": ""
}
{
  "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
See Server Error information below
PUT / POST Endpoints

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/users/{userId}

For example: https://secureauth.company.com/secureauth2/api/v1/users/jbeam

The /users PUT / POST endpoints add, update, or delete end-user profile properties. By utilizing the username in the endpoint URL, SecureAuth IdP can update the user's profile.

Notes

  • Extended properties cannot be updated
  • The userId is included in the URL, so therefore is not a part of the request
  • Maximum number of properties that can be included in the message body for each of the following attributes
    • "phone" = 4
    • "email" = 4
    • "auxId" = 10
    • knowledgeBase "kbq" = 6
Message BodySuccess ResponseFailed ResponseError Response
{
  "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"
    }
  }
}
{
   "status": "success"
   "message": ""
}
{
   "status": "failed"
   "message": "Invalid username."
}
{
   "status": "error"
   "message": "Not_Found" 
}
{   
   "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."
}
POST Endpoints
Create New User

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/users/

For example: https://secureauth.company.com/secureauth2/api/v1/users/

The /users POST user endpoint creates the new end-user profile. No username is specified in the endpoint URL.

Notes

  • The request is the same as the one used for update user profile, though a user ID and password can also be specified
  • "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
  • Maximum number of properties that can be included in the message body for each of the following attributes
    • "phone" = 4
    • "email" = 4
    • "auxId" = 10
    • knowledgeBase "kbq" = 6
Message BodySuccess Response Failed ResponseError Response
{
  "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"
    }
  }
}
{
   "status": "success"
   "message": ""
}
{
   "status": "failed"
   "message": "Invalid username."
}
{
   "status": "error"
   "message": "Not_Found" 
}
{
   "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."
}
 
Reset User Password

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/users/{userId}/resetpwd

For example: https://secureauth.company.com/secureauth2/api/v1/users/jbeam/resetpwd

The /users POST resetpwd endpoint performs an administrative password reset for the end-user. By utilizing the username in the endpoint URL, SecureAuth IdP can access the end-user's profile, reset the user's password and provide a new one.

Notes

  • The current password does not need to be provided by the administrator
  • A failed response references the contextuser_changepwd1-4 fields in the Web Admin for verbiage
    • 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 BodySuccess Response Failed Response
{
   "password": "M@g1cHappens"
}
{
"status": "success"  
"message": "Password was reset"
}
{
   "status": "failed"
   "message": ""
}
User Self-Service Change Password

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/users/{userId}/changepwd

For example: https://secureauth.company.com/secureauth2/api/v1/users/jbeam/changepwd

The /users POST changepwd endpoint performs a password reset for the end-user. By utilizing the username in the endpoint URL, SecureAuth IdP can access the end-user's profile, and let the end-user change that password.

Notes

  • The end-user must provide the existing password in order to change the password
  • A failed response references the contextuser_changepwd1-4 fields in the Web Admin for verbiage
    • 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
Messsage BodySuccess Response Failed Response
{
   "currentPassword": "M@g1cHappens",
   "newPassword": "D3fault321"
}
{
"status": "success"     
"message": "Password was changed"
}
{
   "status": "failed"
   "message": ""
}

Group Association Endpoints

Admins can use POST messages to associate users with groups, and vice-versa. There are 4 available methods of doing so, all of which use the POST verb to the /users or /groups endpoint. Associations can be made as:

  1. Single user to single group
  2. Single user to multiple groups
  3. Single group to single user
  4. Single group to multiple users
Single User to Single Group

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/users/{userId}/groups/{groupID to associate}

For example: https://secureauth.company.com/secureauth2/api/v1/users/jbeam/groups/admins

Result: Associates the userID "jbeam" with the groupID "admins"

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

All the parameters for this request are present in the URL of the call, therefore no message body is required.

Success ResponseFailure Response
{
   "status": "success"
  "message": ""
 
{
   "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

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/groups/{groupId}/users

For example: https://secureauth.company.com/secureauth2/api/v1/groups/Sharepoint%20Visitors/users

Result: Associates the group "Sharepoint Visitors" with a list of users in the specified in the message body

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 will be generated which lists each userID that failed. Any userIDs not listed in the failure response were successfully POSTed.

Message BodySuccess ResponseFailure Response
{
"userIds" : [
"jbeam",
"jdaniels",
"rmartin",
"psmirnoff",
]
}
{
   "status": "success"
  "message": ""
{
"failures": {
"Sharepoint Visitors": [
"rmartin",
"psmirnoff"
]
},
"status": "failed",
"message": "There were 2 association errors."
}
Single Group to Single User

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/groups/{groupID}/users/{userID to associate}

For example: https://secureauth.company.com/secureauth2/api/v1/groups/admins/users/jbeam

Result: Associates the groupID "admins" with userID "jbeam"

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

All the parameters for this request are present in the URL of the call, therefore no message body is required.

This operation is functionally equivalent to the Single User to Single Group operation above.

Success ResponseFailure Response
{
  "status": "success"
  "message": ""
 
{
   "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

Endpoint: https://SecureAuthIdPFQDN/SecureAuthIdPRealm/api/v1/users/{userId}/groups

For example: https://secureauth.company.com/secureauth2/api/v1/users/jbeam/groups

Result: Associates the user "jbeam" with a list of groups specified in the message body.

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 will be generated which lists each groupID that failed. Any groupIDs not listed in the failure response were successfully POSTed.

Message BodySuccess ResponseFailure Response
{
"groupNames" : [
"SharePoint Visitors",
"SharePoint Developers"
]
}
{
  "status": "success"
  "message": ""
{
"failures": {
"jbeam": [
"SharePoint Visitors",
"SharePoint Developers"
]
},
"status": "failed",
"message": "There were 2 association errors."
}

If a server error is encountered, the following response is returned:

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