PingAM 8.0.0

Authenticate endpoints

To authenticate to AM using REST, send an HTTP POST request to the json/authenticate endpoint. Specify the realm hierarchy, starting at the Top Level Realm and prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/customers/realms/europe.

/json/authenticate

The following list describes the json/authenticate endpoint parameters:

authIndexType

The authIndexType specifies the type of authentication the user will perform. Always use this parameter in conjunction with the authIndexValue to provide additional information about how the user is authenticating.

If not specified, AM authenticates the user against the default authentication service configured for the realm.

The authIndexType can be one of the following:

composite_advice

When the authIndexType is composite_advice, the authIndexValue must be a URL-encoded composite advice string.

Use the composite_advice type to indicate which authentication services to use when logging in a user.

This example indicates that the user should authenticate with an authentication level of at least 10:

$ curl -G \
--request POST \
--header "Content-Type: application/json" \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
--data-urlencode 'authIndexType=composite_advice' \
--data-urlencode 'authIndexValue=<Advices>
    <AttributeValuePair>
        <Attribute name="AuthLevelConditionAdvice"/>
        <Value>10</Value>
    </AttributeValuePair>
</Advices>' \
'https://am.example.com:8443/am/json/realms/root/authenticate'
This curl command URL-encodes the XML values. The --get option appends them as query string parameters to the URL.

Possible options for Advices are:

  • AuthenticateToServiceConditionAdvice. Requires the name of an authentication tree. For example:

    <Advices>
  <AttributeValuePair>
    <Attribute name="AuthenticateToServiceConditionAdvice"/>
    <Value>myExampleTree</Value>
  </AttributeValuePair>
</Advices>

  • AuthenticateToRealmConditionAdvice. Requires the name of a realm. For example:

    [/mnt/scratch/workspaces/workspace/am-docs-release_8.0.x/target/asciidoc/modules/ROOT/attachments/programlistings/login-advices.bash:#AuthenticateToRealmConditionAdvice]

  • AuthLevelConditionAdvice. Requires an authentication level.

    For example:

    <Advices>
  <AttributeValuePair>
    <Attribute name="AuthLevelConditionAdvice"/>
    <Value>10</Value>
  </AttributeValuePair>
</Advices>

  • AuthenticateToTreeConditionAdvice. Requires the name of an authentication tree. For example:

    <Advices>
  <AttributeValuePair>
    <Attribute name="AuthenticateToTreeConditionAdvice"/>
    <Value>PersistentCookieTree</Value>
  </AttributeValuePair>
</Advices>

You can specify multiple advice conditions and combine them. For example:

<Advices>
  <AttributeValuePair>
    <Attribute name="AuthenticateToServiceConditionAdvice"/>
    <Value>ldapService</Value>
  </AttributeValuePair>
  <AttributeValuePair>
    <Attribute name="AuthenticateToServiceConditionAdvice"/>
    <Value>Example</Value>
  </AttributeValuePair>
  <AttributeValuePair>
    <Attribute name="AuthLevelConditionAdvice"/>
    <Value>10</Value>
  </AttributeValuePair>
</Advices>
resource

When the authIndexType is resource, the authIndexValue must be a URL protected by an AM policy.

For example, to log into AM using a policy matching the https://www.example.com resource, you could use the following:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate?authIndexType=resource&authIndexValue=https%3A%2F%2Fwww.example.com'

Note that the resource must be URL-encoded. Authentication will fail if no policy matches the resource.

service

When the authIndexType is service, the authIndexValue is the tree AM must use to authenticate the user.

For example, to authenticate using the Login authentication tree, you could use the following:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate?authIndexType=service&authIndexValue=Login'

If authIndexType=service and no authIndexValue is specified, the default service is used. This is similar to no authIndexType being set.

transaction

When the authIndexType is transaction, the authIndexValue must be the unique ID of a transaction token.

Learn more in Transactional authorization.

If there are several authentication services that satisfy the authentication requirements, AM presents them as a choice callback to the user. Return the required callbacks to AM to authenticate.

Required: No.

authIndexValue

This parameter sets a value for the specific authIndexType.

Required: Yes, when using the authIndexType parameter.

noSession

When set to true, this parameter specifies that AM should not return a session when authenticating a user.

For example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
--header "X-OpenAM-Username: bjensen" \
--header "X-OpenAM-Password: Ch4ng31t" \
'https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate?noSession=true'
{
    "message":"Authentication Successful",
    "successUrl":"/am/console",
    "realm":"/"
}

Required: No.

/json/authenticate/backchannel

Lets a third-party federation service initiate and monitor a backchannel authentication flow.

/authenticate/backchannel/initialize

Initiates a backchannel authentication request. This endpoint has no additional parameters.

You must access this endpoint with an OAuth 2.0 token that has the back_channel_authentication scope. The token must have been granted by the same AM instance specified in the redirect URI.

The request body can include the following parameters:

type (string, mandatory)

The authentication type. Currently, only service is supported.

value (string, mandatory)

The name of the AM authentication tree to direct the user or agent to.

subject (object, optional)

The subject of the authentication:

type (string, mandatory)

The subject type: user or agent.

name (string, mandatory)

The subject name.

data (object, optional)

Data to add to the initial authentication journey state, as key-value pairs. For example:

"type": "service",
"value": "Login"

Restricted fields: realm and authLevel.

trackingId (string, optional)

A tracking ID to add to the audit logs for this authentication flow. If provided, AM logs this ID in addition to its own audit tracking ID. This lets a federation service track the flow of backchannel authentication requests through AM using their own tracking IDs.

The custom tracking ID must be a string of 36 characters or less and can include only the following characters:

A-Z a-z 0-9 - and _

Example 
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1, protocol=2.0" \
--header "Authorization: Bearer FnpG1lU0fUooJFY-82sq3UiAnGA" \
--data '{
  "type": "service",
  "value": "Login",
  "subject": {
    "type": "user",
    "name": "bjensen"
  },
  "trackingId": "Y5tyzQi9cGVJjy2L"
}',
"https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate/backchannel/initialize"
{
  "transaction": "b3070138-cd73-4ef2-bd58-812602d7b757",
  "redirectUri": "https://am.example.com:8443/am/UI/Login?realm=/alpha&authIndexType=transaction&authIndexValue=b3070138-cd73-4ef2-bd58-812602d7b757"
}

/authenticate/backchannel/info

Provides information on the status of a backchannel authentication flow. This endpoint has no additional parameters.

The request body must include the following parameter:

transaction (string, mandatory)

The ID of the transaction associated with the authentication tree being queried.

Example 
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1, protocol=2.0" \
--header "Authorization: Bearer B158QzJzokTTwhAF6DshB0XQ0Rg" \
--data '{
    "transaction": "b3070138-cd73-4ef2-bd58-812602d7b757"
}' \
"https://am.example.com:8443/am/json/realms/root/realms/alpha/authenticate/backchannel/info"
{
  "state": "CREATED",
  "result": "UNKNOWN",
  "auditTrackingIds": [
    "82d76902-7d18-41ea-9ae6-05643b05d018-166108"
  ],
  "type": "service",
  "value": "Login",
  "subject": {
    "type": "user",
    "name": "bjensen"
  }
}

The response of a request to this endpoint includes the following properties:

state (string)

The state of the authentication journey. Possible values include:

  • CREATED

  • IN_PROGRESS

  • COMPLETED

result (string)

The result of the authentication. Possible values include:

  • UNKNOWN

  • APPROVED

  • DENIED

auditTrackingIds (array)

An array of IDs that can be used to link requests that are part of the same flow.

type (string)

The type of authentication that was performed. Currently, only service is supported.

value (string)

The name of the authentication journey that was performed.

subject (object)

The subject of the authentication.

type (string)

The subject type of the subject. Possible values are user and agent.

name (string)

The name of the subject.

sessionProperties (object)

Additional information about the user’s session, if one was created successfully. You can use the Set Session Properties node to add properties to a session in a journey. You must configure a Session Property Whitelist Service for the realm to allow these properties to be published.