Authenticate endpoint parameters

To authenticate to Advanced Identity Cloud using REST, send an HTTP POST request to the json/authenticate endpoint. Specify the realm hierarchy, starting at the root; for example, /realms/root/realms/alpha.

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, PingOne Advanced Identity Cloud authenticates the user against the default journey 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 through the myExampleJourney:

$ curl --get \
--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="AuthenticateToServiceConditionAdvice"/>
        <Value>myExampleJourney</Value>
      </AttributeValuePair>
</Advices>' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/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 journey. For example:

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

AuthenticateToTreeConditionAdvice. Also requires the name of an authentication journey. For example:

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

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

<Advices>
  <AttributeValuePair>
    <Attribute name="AuthenticateToRealmConditionAdvice"/>
    <Value>alpha</Value>
  </AttributeValuePair>
</Advices>

You can specify multiple advice conditions. For example:

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

resource

When the authIndexType is resource, the authIndexValue must be a URL protected by an PingOne Advanced Identity Cloud policy.

For example, to log into PingOne Advanced Identity Cloud 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://<tenant-env-fqdn>/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 journey PingOne Advanced Identity Cloud must use to authenticate the user.

For example, to authenticate using the built-in login authentication journey, you could use the following:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/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.

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

Required: No.

transaction

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

Learn more in Authorize one-time access with transactional authz.

`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 PingOne Advanced Identity Cloud 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: Secret12!" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate?noSession=true'
{
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

Required: No.