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.

Prerequisites

1. Have access to the application code

2. Have an on-premises Active Directory with which SecureAuth IdP 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 in which the Identity Management APIs are enabled

The API can be included in any realm with any Post Authentication event as long as the appropriate directory is integrated and the appropriate settings are configured

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

An Active Directory integration is required for SecureAuth IdP to pull user profile information during the login process

Note, however, the GET /user and update /user functions can work with non-AD integrations.

SecureAuth IdP Web Admin Configuration Steps
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 are required in the 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 change

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

Configure /users Endpoints

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

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

The /users GET endpoint retrieves a list of end-user profile properties – SecureAuth IdP accesses and retrieves 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

GET EndpointExample

/users/{userId}

https://secureauth.company.com/secureauth2/api/v1/users/jbeam
Web Admin Configuration Notes

WebAdmin 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

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
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
Response Examples
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

The /users PUT / POST endpoints add, update, or delete end-user profile properties – SecureAuth IdP updates the user's profile using the username in the endpoint URL

PUT / POST EndpointExample

/users/{userId}

https://secureauth.company.com/secureauth2/api/v1/users/jbeam
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 Body and Response Examples
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

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

POST EndpointExample

/users/

https://secureauth.company.com/secureauth2/api/v1/users/
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 Body and Response Examples
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

The /users POST resetpwd endpoint performs an administrative password reset for the end-user – SecureAuth IdP accesses the end-user's profile, resets the user's password and provides a new one using the username in the endpoint URL

POST EndpointExample

/users/{userId}/resetpwd

https://secureauth.company.com/secureauth2/api/v1/users/jbeam/resetpwd
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 Body and Responses
Message BodySuccess Response Failed Response
{
   "password": "M@g1cHappens"
}
{
"status": "success"  
"message": "Password was reset"
}
{
   "status": "failed"
   "message": ""
}

User Self-Service Change Password

The /users POST changepwd endpoint performs a password reset for the end-user – SecureAuth IdP accesses the end-user's profile and lets the end-user change that password, using the username in the endpoint URL

POST EndpointExample

/users/{userId}/changepwd

https://secureauth.company.com/secureauth2/api/v1/users/jbeam/changepwd
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
Message Body and Response Examples
Messsage BodySuccess Response Failed Response
{
   "currentPassword": "M@g1cHappens",
   "newPassword": "D3fault321"
}
{
"status": "success"     
"message": "Password was changed"
}
{
   "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 since all parameters for this request are present in the call URL

POST EndpointExample

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

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

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

Response Examples
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

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 which lists each userID that failed – userIDs not listed in the failure response successfully POSTed

POST EndpointExample

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

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

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

Message Body and Response Examples
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

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

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

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

POST EndpointExample

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

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

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

Response Examples
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

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 which lists each groupID that failed – groupIDs not listed in the failure response successfully POSTed

POST EndpointExample

/users/{userId}/groups

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

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

Message Body and Response Examples
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."
}

Server Error

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

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