Rate this page

Login Flow

Schema URN
urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest

The Login authentication flow establishes the identity of the end user attempting to authenticate and creates a session.

This flow is always executed at least once per session. Depending on the server’s configuration and policy settings, it may not always be required for subsequent authentication requests using the same session.

Field Type Provided? Description
schemas array always The SCIM schema of the flow. Always has the value urn:pingidentity:scim:api:messages:2.0:AuthenticationRequest.
meta complex always Will always contain a resourceType sub-attribute with the value login. Will always contain a location sub-attribute with the current flow URI.
followUp complex always An object indicating the authorization endpoint URI to be retrieved when this flow is complete. Will always contain a type sub-attribute and a $ref sub-attribute; the latter is the URI to be retrieved.
sessionIdentityResource object If an end user is already logged in, the sub-attributes of this object are attribute values of the user that may be displayed by the auth UI. Examples might include the end user’s username, full name, or icon. The attributes included here are determined by the Session Resource Attribute property of the Broker’s Authentication Service configuration.
success boolean Will be present with a value of true if the flow’s enforcement criteria have been satisfied.

In addition to the fields above, objects representing any identity authenticators associated with the Login flow in the Broker configuration will be listed in a Login flow message.

Here is an example Login flow 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": "Horselover Fat",
    "userName": "horselover"
  },
  "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": {
    "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": "ready"
  },
  "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": [
      {
        "type": "length",
        "description": "The password must contain at least 6 characters.",
        "minPasswordLength": "6"
      }
    ],
    "status": "ready"
  }
}

Example: Username/password authentication

In this example, the auth UI submits a username/password authentication request by providing the username and password fields of the Username Password identity authenticator and submitting the request with a PUT.

{
  "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": "Horselover Fat",
    "userName": "horselover"
  },
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "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": "ready",
    "username": "horselover.fat",
    "password": "password"
  }
}

If the request succeeds and no other authenticators are required by the Login flow, then the flow’s success flag will be set to true.

{
  "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": "Horselover Fat",
    "userName": "horselover"
  },
  "client": {
    "name": "Example OAuth2 Client",
    "description": "This is the external application that initiated the authentication process."
  },
  "success": true,
  "urn:pingidentity:scim:api:messages:2.0:UsernamePasswordAuthenticationRequest": {
    "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"
  }
}

At this point, the auth UI should make a GET request of the followup URI to proceed to the next flow.