<style>
.wiki-content ul { 
list-style-type: none; 
}
</style>

...

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.

...

...

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
   title Note type info
   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.

...

...

...

...

...

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.

    ApplicationID:Base64EncodedHMACSHA256Hash

    Basic Step5Value

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
    }

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
    }

{
  "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.",
}

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

• answer written to the SecureAuth IdP data store

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.

...

{   

  "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

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.

...

{
  "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."

}