Documentation

Introduction

SecureAuth's Authentication API embeds the SecureAuth IdP functionality into a custom application, enabling flexible workflow configurations and user interfaces.

Using a RESTful API encrypted over SSL, SecureAuth IdP

  • can validate
    • user IDs
    • passwords
    • PINs
    • soft tokens
    • Push-to-Accept responses
    • knowledge-based answers
  • can generate One-time Passwords (OTPs) delivered via
    • phone call
    • SMS message
    • email message
    • help desk
    • Push / Push-to-Accept Notification
  • can analyze a user's access attempt through SecureAuth's
    • Device / Browser Fingerprinting
    • Adaptive Authentication
    • Behavioral Biometric profile
  • can evaluate IP address risk through threat intelligence data
  • can prevent end-users from logging on a realm

Each SecureAuth IdP realm can host its own uniquely configured Authentication API, enabling various workflows and registration methods.

By simply integrating an application with SecureAuth's Authentication API, enabling Multi-Factor Authentication mechanisms, and configuring Adaptive Authentication, customers can securely direct users through unique logins and interfaces without leaving the application.

NOTE: This Authentication API Guide is specifically for SecureAuth IdP v9.1 or later

Information about using Identity Management API tools can be found in the Identity Management API Guide

Information about configuring the Login for Windows API endpoint can be found in the Login for Endpoints Configuration Guide

Prerequisites

1. Have access to the application code

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

3. Create a New Realm or access an existing realm on SecureAuth IdP v9.1 or later in which the Authentication API will be enabled

The API can be included in any realm with any Post Authentication event as long as the appropriate directory is integrated and the necessary features are configured, based on the endpoints being used.

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

A directory integration is required for the Authentication API, but SecureAuth's Web Service (Multi-Data Store) option is not supported

The Behavioral Biometrics feature only supports LDAP directory integrations, while other Authentication API features support most directory type integrations

Ensure the Multi-Factor Methods Profile Properties (e.g. Phone 1, Email 1, etc.) are accurately mapped to directory attributes to enable Multi-Factor Authentication workflows

SecureAuth IdP Web Admin Configuration Steps

NOTE: Only API section steps are required; all other Web Admin steps are optional and should be performed based on the features to be implemented

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

In appearance, the API key looks like it is comprised of 64 random characters, but it is actually is comprised of 32 two-character base-16 hexadecimal values

This is important to note when using the API key to produce the HMAC hash

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 Enable Authentication API in the API Permissions section

Click Save once the configuration is complete and before leaving the API page to avoid losing changes

Configure Request 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, based on whether SecureAuth IdP v9.1 or SecureAuth IdP v9.2 or later is running

Authorization Header

For GET endpoint:

1. Build a string based on the request

a. METHOD (GET)

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

c. APPLICATION ID (from SecureAuth IdP Web Admin)

d. 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)

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. 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 for SecureAuth IdP v9.1
Step 1
    GET
    Wed, 08 Apr 2015 21:37:33 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /secureauth2/api/v1/users/jsmith/factors

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

Step 2
	Non-printable bytes are produced in this step
 
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/jsmith/factors', 
    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
    }
GET Request Example for SecureAuth IdP v9.2+
Step 1
    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 2
	Non-printable bytes are produced in this step
 
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/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
    }

For POST endpoint:

1. Build a string based on the request

a. METHOD (POST)

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

c. APPLICATION ID (from SecureAuth IdP Web Admin)

d. PATH (API endpoint) – e.g. /secureauth2/api/v1/users/{userID}

e. CONTENT (JSON parameters)

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

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. 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 for SecureAuth IdP v9.1
Step 1
    POST
    Wed, 08 Apr 2015 21:27:30 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /secureauth2/api/v1/auth
    {"user_id":"jsmith","type":"user_id"}

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

Step 2
	Non-printable bytes are produced in this step
 
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
    }
POST Request Example for SecureAuth IdP v9.2+
Step 1
    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 2
	Non-printable bytes are produced in this step
 
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  
        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": "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

Configure Response Header

SecureAuth's API includes a security hashing enhancement 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 / 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

If, after hashing the data, the value matches (exactly) 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.

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+ response)

b. APPLICATION ID (from SecureAuth IdP Web Admin)

c. CONTENT (JSON Parameters from the SecureAuth IdP response)

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

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

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

Sample X-SA-Ext-Date Code
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 Endpoints

Configure the endpoint(s) for the selected feature

FeatureEndpointMethod(s)Function(s)
Profile Validation /authPOSTValidate end-user information and generate OTPs for authentication
/auth/{REF_ID}GETCheck status of Push-to-Accept responses
Multi-Factor Authentication /users/{username}/factorsGETAccess end-user profile and respond with Multi-Factor Authentication selections
Multi-Factor Throttling Authentication /users/{username}/throttleGETRetrieve current count of Multi-Factor Authentication attempts for given username
/users/{username}/throttlePUTReset count of Multi-Factor Authentication attempts to 0
Phone Profiling Service Authentication /numberprofilePOSTRetrieve phone profile record from data provider / directory which includes carrier information
/numberprofilePUTUpdate the directory to reflect change in phone profile record
Device / Browser Fingerprinting Authentication /dfp/jsGETRetrieve JavaScript reference required to generate fingerprints
/dfp/validatePOSTCompare presented fingerprint with those stored in end-user profile
/dfp/confirmPOSTCreate / update fingerprint in end-user profile in directory
Adaptive Authentication /adaptauthPOSTAnalyze end-user profile, group, IP address, country, geo-velocity, and risks detected by threat intelligence data
/accesshistoryPOSTCreate end-user access history for geo-velocity calculations
IP Evaluation /ipevalPOSTEvaluate an IP address for risk factors based on threat intelligence data
Behavioral Biometrics Authentication /behavebio/jsGETRetrieve JavaScript reference required to gather and analyze end-user behavioral biometric profile
/behavebioPOSTCollect and create end-user behavioral biometric profile for analyzing proflle account info subsequently posted
/behavebioPUTReset end-user profile to enable retraining