PingAM 7.5.0

Authenticate endpoint parameters

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.

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://openam.example.com:8443/openam/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:

  • TransactionConditionAdvice. Requires the unique ID of a transaction token. For example:

    <Advices>
  <AttributeValuePair>
    <Attribute name="TransactionConditionAdvice"/>
    <Value>9dae2c80-fe7a-4a36-b57b-4fb1271b0687</Value>
  </AttributeValuePair>
</Advices>

    For more information, refer to Transactional authorization.

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

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

  • AuthSchemeConditionAdvice. Requires the name of an authentication module. For example:

    <Advices>
  <AttributeValuePair>
    <Attribute name="AuthSchemeConditionAdvice"/>
    <Value>DataStoreModule</Value>
  </AttributeValuePair>
</Advices>

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

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

  • 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>
level

When the authIndexType is level, the authIndexValue sets the minimum authentication level an authentication service must satisfy to log in the user.

For example, to log into AM using an authentication service that provides a minimum authentication level of 10, you could use the following:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=level&authIndexValue=10'
This mechanism is supported for authentication chains only.
module

Specifies that the value of the authIndexValue parameter is the name of the authentication module AM must use to log in the user.

For example, to log into AM using the built-in DataStore authentication module, you could use the following:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=module&authIndexValue=DataStore'
For security reasons, you should disable module-based authentication. For more information, refer to Secure realms.
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://openam.example.com:8443/openam/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 or chain 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://openam.example.com:8443/openam/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.

user

When the authIndexType is user, the authIndexValue must be a valid user ID. AM authenticates the user against the authentication chain configured in the User Authentication Configuration field of that user’s profile.

Authentication fails if the User Authentication Configuration field is empty for the user.

For example, for user bjensen to log into AM using the chain specified in their user profile, you could use the following:

$ curl \
--request POST \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?authIndexType=user&authIndexValue=bjensen'
This mechanism is supported for authentication chains only.

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: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate?noSession=true'
{
    "message":"Authentication Successful",
    "successUrl":"/openam/console",
    "realm":"/"
}

Required: No.