Skip to main content

Admin API Guide

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

44834088.png

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

Warning

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 types

IdP version

String requirements

Date

v9.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–orhttps://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

For POST endpoint:

1. Build a string based on the request

a. METHOD (POST)

b. DATE/TIME

Header types

IdP version

String requirements

Date

v9.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– orhttps://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

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.

Notice

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

In this section: