Rate this page

Data Types and Message Format

The Data Governance Broker’s Auth API uses the data types and message format specified by the SCIM 2.0 schema standard, RFC 7643. If you’ve used the Broker’s SCIM client API, then the Auth API schema will be familiar to you.

Data types

Auth API attributes are typed. The following data types are used:

Data type Description
string A JSON string.
boolean A JSON boolean value. May have either of the literal values true or false.
decimal A JSON floating-point number.
integer A JSON integer number.
dateTime A JSON string representing a timestamp. DateTime values are always encoded as an xsd:dateTime value, as specified by XML Schema, section 3.3.7.
binary A JSON string representing a binary value. Binary values are always base64-encoded.
reference A JSON string representing a reference to another resource. A reference is always a URI representing a flow.
complex A JSON object. A complex attribute is a composition of sub-attributes; these sub-attributes may have any data type except for “complex”.

An attribute may also be a multi-valued array. All members of a multi-valued attribute must be of the same data type.

Message format

An Auth API message is always represented as a JSON object.

A message type is identified by the schema URN listed in its schemas attribute and the value of its meta.resourceType attribute. The schema URN defines the set of attributes available in the message; this is called the core schema. So-called extension schemas representing identity authenticators may be mixed in to the message; these are always namespaced under the identity authenticator’s schema URN.

Consider this example message:

{
  "schemas": [
    "urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest"
  ],
  "meta": {
    "resourceType": "login",
    "location": "https://example.com/authentication/login/ARH5F9B..."
  },
  "followUp": {
    "type": "authorize",
    "$ref": "https://example.com/oauth/authorize/ARH5F9B..."
  },
  "sessionIdentityResource": {
    "name.formatted": "Ferris Fremont",
    "userName": "ferris.fremont"
  },
  "success": true,
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "urn:pingidentity:scim:api:messages:2.0:RecaptchaAuthenticationRequest": {
    "recaptchaKey": "6LcX9CETAAAAADpuPrcVuDMZGi6ux6_Of2eRyq6g",
    "status": "ready"
  },
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "username": "ferris.fremont",
    "passwordExpiring": false,
    "usernameRecovery": {
      "type": "Username Recovery",
      "$ref": "https://example.com/authentication/account/Username%20Recovery/ARH5F9B..."
    },
    "passwordRecovery": {
      "type": "Password Recovery",
      "$ref": "https://example.com/authentication/account/Password%20Recovery/ARH5F9B..."
    },
    "status": "success"
  },
  "urn:pingidentity:scim:api:messages:2.0:ExternalIdentityAuthenticationRequest": {
    "providers": [
      {
        "name": "Facebook",
        "description": "Log in with your Facebook account",
        "type": "facebook"
      }
    ],
    "status": "ready"
  },
  "urn:pingidentity:scim:api:messages:2.0:RegistrationAuthenticationRequest": {
    "registrableAttributes": [
      "emails[type eq \"home\"].value",
      "name",
      "password",
      "phoneNumbers[type eq \"mobile\"].value",
      "userName"
    ],
    "passwordRequirements": [],
    "status": "ready"
  }
}

This resource uses the following core schema:

  • urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest

But it also includes multiple extension schemas:

  • urn:pingidentity:scim:api:messages:2.0:RecaptchaAuthenticationRequest
  • urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest
  • urn:pingidentity:scim:api:messages:2.0:ExternalIdentityAuthenticationRequest
  • urn:pingidentity:scim:api:messages:2.0:RegistrationAuthenticationRequest

This should be read as: This is an authentication message for the login flow. The login flow supports username/password authentication, external identity provider authentication, registration, and reCAPTCHA.

Common attributes

In addition to core schema and extension schema attributes, all Auth API messages of any type may have certain common attributes.

Common attribute Description
meta A complex read-only attribute containing resource metadata. Its sub-attributes are described in the following table.
Meta sub-attribute Description
resourceType The message type.
location A URI representing the current authentication flow state.