Documentation

Introduction

SecureAuth's Admin API lets administrators configure SecureAuth IdP realms without using the Web Admin interface.

Using various GET, POST, and PATCH endpoint calls, admins can create new realms, customize client-side pages, integrate directories, dictate workflows, set Adaptive Authentication policies, enable multi-factor authentication methods, generate API credentials and settings, configure SAML / WS-Federation assertions, and enable logging.

Refer to the specific endpoint guides at the bottom of this page for more information on the possible configurations.

Prerequisites
  • Access to SecureAuth IdP v9.1 or later Web Admin (required for Enablement Step below).
  • Access to application code that calls the API endpoints.
SecureAuth IdP Enablement Steps

 

1. Log on the SecureAuth IdP Web Admin and enter the Admin Realm (SecureAuth0)

2. In the API tab, under API Key, check Enable API for this realm

3. Click Generate Credentials and copy the Application ID and Application Key from the page to use in the application's code and headers to create communication with SecureAuth IdP

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. https://secureauth.company.com/api/v1/realms/{realmID} for SecureAuth IdP v9.1
or https://secureauth.company.com/api/v2/realms/{realmID} for SecureAuth IdP v9.2+

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
    /api/v1/realms/26

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

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/api/v1/realms/26', 
    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 or later
Step 1
    GET
    Wed, 08 Apr 2015 21:37:33.123 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /api/v2/realms/26

End Result: "GET\nWed, 08 Apr 2015 21:37:33.123 GMT\n1b700d2e7b7b4abfa1950c865e23e81a\n/api/v2/realms/26"

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/api/v2/realms/26', 
    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. https://secureauth.company.com/api/v1/realms/{realmID} for SecureAuth IdP v9.1
– or https://secureauth.company.com/api/v2/realms/{realmID} for SecureAuth IdP v9.2+

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
    /api/v1/realms/26/logsettings
    {
	 	"logInstanceId": "SecureAuth26",
		"enableAuditSyslog": true,
		"enableAuditEventLog": true, ...
		"syslogSetting": {
		   	"server": "",
			"port": 514,
			"rfcSpec": "None",
			"privateEnterpriseNumber": 1234
		},
		"logDatabaseConnectionString": "<CONNECTION STRING>"
	}

End Result: "POST\nWed, 08 Apr 2015 21:27:30 GMT\n1b700d2e7b7b4abfa1950c865e23e81a\n/api/v1/realms/26/logsettings\n{"logInstanceId": "SecureAuth26"," "enableAuditSyslog": true, "enableAuditEventLog": true, ... "syslogSetting": { "server": "", "port": 514, "rfcSpec": "None", "privateEnterpriseNumber": 1234 }, "logDatabaseConnectionString": "<CONNECTION STRING>"}"

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/api/v1/realms/26/logsettings'
    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 or later
Step 1
    POST
    Wed, 08 Apr 2015 21:27:30.123 GMT
    1b700d2e7b7b4abfa1950c865e23e81a
    /api/v2/realms/26/logsettings
    {
	 	"logInstanceId": "SecureAuth26",
		"enableAuditSyslog": true,
		"enableAuditEventLog": true, ...
		"syslogSetting": {
		   	"server": "",
			"port": 514,
			"rfcSpec": "None",
			"privateEnterpriseNumber": 1234
		},
		"logDatabaseConnectionString": "<CONNECTION STRING>"
	}

End Result: "POST\nWed, 08 Apr 2015 21:27:30 GMT\n1b700d2e7b7b4abfa1950c865e23e81a\n/api/v2/realms/26/logsettings\n{"logInstanceId": "SecureAuth26"," "enableAuditSyslog": true, "enableAuditEventLog": true, ... "syslogSetting": { "server": "", "port": 514, "rfcSpec": "None", "privateEnterpriseNumber": 1234 }, "logDatabaseConnectionString": "<CONNECTION STRING>"}"

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/api/v2/realms/26/logsettings'
    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 Admin API Endpoints

  • No labels