Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
HTML
<style>
.wiki-content ul { 
list-style-type: none; 
}
</style>

...

borderColor#000000
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#000000
borderStylesolid
titleIntroduction

Updated January 31, 2020

Use this guide to work with the SecureAuth

...

IdP 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 IdP realm

...

to securely direct end users through unique logins and interfaces without leaving the application.

...

borderColor#444544
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#444544
borderStylesolid
titlePrerequisites


...

Prerequisites

  1. Have access to the application code.

...

  1. Have an on-premises Active Directory (AD) with which SecureAuth IdP can integrate.

    UI Text Box
    titleNote
    typeinfo
     The Multi-Data Store option is not compatible with the Identity Management APIs

...

  1. Create a

...

  1. new realm or access an existing realm

...

  1. where the Identity Management APIs are enabled.

...


  1. You can include the API in any realm with any

...

  1. post authentication event as long as you integrate the appropriate directory

...

  1. and configure the appropriate settings

...

  1. .

...

  1. 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

...

  1. .

    The GET /user and update /user functions can work with non-AD integrations.
Panel
borderColor#008388
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#008388
borderStylesolid
titleTable of Contents

1. SecureAuth IdP Web Admin Steps

2. Configure Authorization Header & Response Header

3. Endpoints

...

Panel
borderColor#145570
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#145570
borderStylesolid
titleSecureAuth IdP Web Admin Configuration Steps
Panel
borderColor#126591
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#126591
borderStylesolid
titleAPI
Panel
borderColor#007fb2
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#007fb2
borderStylesolid
titleAPI Key
Section
Column
width50%

Image Removed

Column

 

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

Panel
borderColor#007fb2
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#007fb2
borderStylesolid
titleAPI Permissions
Section
Column
width50%

Image Removed

Column

 

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

UI Text Box
typewarning

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

...

UI Text Box
typeinfo

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

...

borderColor#145570
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#145570
borderStylesolid
titleConfigure /users Endpoints

...


...

Workflow

The following workflow guides you through the different SecureAuth IdP 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 SecureAuth IdP Web Admin configuration steps setup.
  2. Configure the Authorization Header & Response Header for all GET and POST requests.
  3. Configure /users endpoints and configure group association endpoints for users and groups.


...

SecureAuth IdP Web Admin configuration steps
Anchor
WAS
WAS

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 IdP realm API tab.

API Key section

  1. In the API tab, go to the API Key section.
  2. Check Enable API for this realm.
    Image Added
  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 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. 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.
    Image Added
  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 IdP API to connect to User properties.

    Image Added
    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 reset option, 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.


Excerpt

Configure request header 
Anchor
AH
AH

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 header for GET and POST requests using the steps below.

Authorization request header
Anchor
Authorization
Authorization

A. Build a string based on the request:

A1. METHOD (GET) or METHOD (POST)

A2. DATE/TIME

Header typesIdP versionString requirements
Datev9.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

UI Expand
titleGET request example
Code Block
languagetext
Step A
    GET
    Wed, 08 Apr 2015 21:37:33.123 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /secureauth2/api/v1/users/jsmith/factors

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

Step B
	Non-printable bytes are produced in this step
 
Step C
    F5yqdLDJddUYOlrpBlOJBh/YCUIMVCsWejuhiCrqMmw=

Step D
    1b700d2e7b7b4abfa1950c865e23e81a:F5yqdLDJddUYOlrpBlOJBh/YCUIMVCsWejuhiCrqMmw=

Step E
    MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOnorVGNYNG4vbFlsTmNvNjRpQkRENVJKaHFiZ0h0UGYwaEQ4d1d4bTgvWVk9

Step F
    Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOnorVGNYNG4vbFlsTmNvNjRpQkRENVJKaHFiZ0h0UGYwaEQ4d1d4bTgvWVk9

End Result:
    Method: GET, 
    RequestUri: 'https://secureauth.company.com/secureauth2/api/v1/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
    }
UI Expand
titlePOST request example
Code Block
languagetext
Step A
    POST
    Wed, 08 Apr 2015 21:27:30.123 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /secureauth2/api/v1/auth
    {"user_id":"jsmith","type":"user_id"}

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

Step B
	Non-printable bytes are produced in this step
 
Step C
    D6nkepAEtk/M+cpkyWQ/hZMXZxPJ32L++5ZZa6+pB8U=

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

Step E
    MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkQ2bmtlcEFFdGsvTStjcGt5V1EvaFpNWFp4UEozMkwrKzVaWmE2K3BCOFU9

Step F
    Basic MWI3MDBkMmUtN2I3Yi00YWJmLWExOTUtMGM4NjVlMjNlODFhOkQ2bmtlcEFFdGsvTStjcGt5V1EvaFpNWFp4UEozMkwrKzVaWmE2K3BCOFU9

End Result:
    Method: POST
    RequestUri: 'https://secureauth.company.com/secureauth2/api/v1/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 response examples

UI Expand
titleAuthorization Header non-validation responses
typetip

When an Authorization header cannot be validated, one of the following responses is 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 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 IdP 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 IdP 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 IdP 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 IdP v.1 or later response).

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

    c. CONTENT (JSON Parameters from the SecureAuth IdP response). 
  2. Create an HMAC SHA256 hash of step 2 using the Application Key (from SecureAuth IdP 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 IdP 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
Anchor
XsaExtDate
XsaExtDate

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.

UI Expand
titleX-SA-Ext-Date header example
Code Block
var dateMillis = request.Headers.Date.Value.UtcDateTime.ToString("ddd, dd MMM yyyy HH:mm:ss.fff G\\MT");
                request.Headers.Add("X-SA-Ext-Date", dateMillis);    
                request.Headers.Remove("Date");
                var httpMethod = request.Method.Method;
                string uri = request.RequestUri.AbsolutePath;
                string content = null;
                if (request.Content != null)
                {
                    content = request.Content.ReadAsStringAsync().Result;
                }
                result = (string.IsNullOrEmpty(content)) ?
                    string.Join("\n", httpMethod
dateMillis, appId, uri) :
                    string.Join("\n", httpMethod, dateMillis, appId, uri, content);

Configure /users endpoints
Anchor
usersEndpoints
usersEndpoints

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

GET Endpoint
  • answer written to the SecureAuth IdP data store
UI Expand
titleDefinitions

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)
  • fields
  • email1-4: The user's email address(es) (Email 1, Email 2, Email 3, Email 4) entered in SecureAuth IdP Property / directory
field(s)
  • fields
  • 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)
  • fields
  • ExtProperty1-##: Information from the user's additional property
field(s)
  • fields populated in SecureAuth IdP Property / directory
field(s)
  • fields

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
Anchor
userGETuserGET
Panel
borderColor#126591
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#126591
borderStylesolid
title

GET endpoint 
Anchor
userGET
userGET

The /users GET endpoint retrieves a list of end

...

user profile properties

...

. SecureAuth IdP 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 EndpointExample

/users/{userId}

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

...

jdoe
Configuration Notes
UI Expand
titleWeb 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.
UI Expand
titleSuccessful GET Retrieval Information
Successful GET Retrieval

GET retrieval is successful in the following situations:

  • The retrieval includes a collection of
usergroups to which
  • 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
– e.g.
  • , 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.
Maximum
  • 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
UI Expand
titleDefinitions

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
UI Expand
titleResponse 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
below

PUT / POST endpoints 
Anchor
userPUTPOST
userPUTPOST

...

The /users PUT / POST endpoints add, update, or delete end

...

user profile properties

...

SecureAuth IdP updates the user's profile

...

by using the username in the endpoint URL.

PUT / POST EndpointExample

/users/{userId}

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

...

jdoe 
UI Expand
titleNotes
  • Extended properties cannot be updated
  • The userId is included in the URL, so therefore is not a part of the request
Maximum
  • 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
Body Response ExamplesPOST Endpoints
UI Expand
titleMessage
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."
}
Anchor
userPOSTuserPOST
Panel
borderColor#126591
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#126591
borderStylesolid
title
}

POST endpoints 
Anchor

...

userPOST

...

borderColor#007fb2
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#007fb2
borderStylesolid
titleCreate New User

userPOST

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 
Anchor
userCreate
userCreate

The /users POST user endpoint creates the new end

...

user profile

...

, so a username is not specified in the endpoint URL

POST EndpointExample

/users/

https://secureauth.company.com/secureauth2/api/v1/users/
UI Expand
titleNotes
  • The request is the same as the one used for update user profile,
though
  • although you can specify 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
  • 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
Body Response Examples
UI Expand
titleMessage
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 
Anchor
userReset
userReset

...

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

...

password by using the username in the endpoint URL.

POST EndpointExample

/users/{userId}/resetpwd

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

...

jdoe/resetpwd
UI Expand
titleNotes
  • The current password does not need to be provided by the administrator.
  • A failed response references the text set up in 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.
Body Responses
UI Expand
titleMessage
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 
Anchor
userSelfService
userSelfService

...

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

...

by using the username in the endpoint URL.

POST EndpointExample

/users/{userId}/changepwd

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

...

jdoe/changepwd
UI Expand
titleNotes
  • The end
-
  • user must provide the existing password
in order
  • to change the password.
  • A failed response references the text set up in 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.
Body Response Examples
UI Expand
titleMessage
body and
response examples

...

Panel
borderColor#145570
titleColorwhite
borderWidth1
titleBGColor#135570
titleConfigure Group Association Endpoints
Messsage BodySuccess Response Failed Response
{
   "currentPassword": "M@g1cHappens",
   "newPassword": "D3fault321"
}
{
"status": "success"     
"message": "Password was changed"
}
{
   "status": "failed"
   "message": ""
}

...


}


...

Configure group association endpoints
Anchor
groupAssnEndpoints
groupAssnEndpoints

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 
Anchor
singleUserSingleGroup
singleUserSingleGroup

...

...

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 EndpointExample

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

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

...

jdoe/groups/admins

Result: userID "

...

jdoe" is associated with the groupID "admins"

ExamplesSingle Group to Multiple Users
UI Expand
titleResponse
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."
}
Anchor
singleGroupMultiUserssingleGroupMultiUsers
Panel
borderColor#126591
titleColorwhite
borderWidth1
titleBGColor#116490
title

Single group to multiple users 
Anchor
singleGroupMultiUsers
singleGroupMultiUsers

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

Body Response Examples
UI Expand
titleMessage
body and
response examples
Message BodySuccess ResponseFailure Response
{
"userIds" : [
"
jbeam
jdoe",
"
jdaniels
jsmith",
"
rmartin
kmartin",
"
psmirnoff
pjohnson",
]
}
{
   "status": "success"
  "message": ""
{
"failures": {
"Sharepoint Visitors": [
"
rmartin
kmartin",
"
psmirnoff
pjohnson"
]
},
"status": "failed",
"message": "There were 2 association errors."
}

Single group to single user 
Anchor
singleGroupSingleUser
singleGroupSingleUser

...

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 EndpointExample

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

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

...

jdoe 

Result: groupID "admins" is associated with userID "

...

jdoe"

Examples#116490
UI Expand
titleResponse
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."
}
Anchor
singleUserMultiGroupssingleUserMultiGroups
Panel
borderColor#126591
titleColorwhite
borderWidth1
titleBGColor
title

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 EndpointExample

/users/{userId}/groups

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

...

jdoe/groups

Result: user "

...

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

Body Response Examples
UI Expand
titleMessage
body and
response examples
Message BodySuccess ResponseFailure Response
{
"groupNames" : [
"SharePoint Visitors",
"SharePoint Developers"
]
}
{
  "status": "success"
  "message": ""
{
"failures": {
"
jbeam
jdoe": [
"SharePoint Visitors",
"SharePoint Developers"
]
},
"status": "failed",
"message": "There were 2 association errors."
}


...

Server error 
Anchor

...

Error

...

...

Error

Info
If a

A server error

is encountered,

returns the following response

is returned

:

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