Authenticate Endpoint Parameters

To authenticate to AM using REST, make an HTTP POST request to the json/authenticate endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. 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 supported parameters:

authIndexType

Specifies the type of authentication the user will perform. Always use in conjunction with the authIndexValue parameter to provide additional information about the way the user is authenticating.

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

The authIndexType parameter supports the following types:

  • composite_advice

    Specifies that the value of the authIndexValue parameter is a URL-encoded composite advice string.

    Use composite_advice when you want to give AM hints of which authentication services to use when logging in a user. For example, use an authentication module that provides an authentication level of 10 or higher: 

    $ 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="AuthLevelConditionAdvice"/>
        <Value>10</Value>
    </AttributeValuePair>
</Advices>' \
'https://openam.example.com:8443/openam/json/realms/root/authenticate'

    The previous curl command URL-encodes the XML values, and the -G parameter appends them as query string parameters to the URL.

    Note

    This example applies to authentication chains only.

    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, see 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

    Specifies that the value of the authIndexValue parameter is 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/authenticate?authIndexType=level&authIndexValue=10'

  • 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/authenticate?authIndexType=module&authIndexValue=DataStore'

    You should disable module-based authentication for security reasons. For more information, see Securing Realms

  • resource

    Specifies that the value of the authIndexValue parameter is a URL protected by an AM policy.

    For example, to log into AM using a policy matching the http://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/authenticate?authIndexType=resource&authIndexValue=http%3A%2F%2Fwww.example.com'

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

  • service

    Specifies that the value of the authIndexValue parameter is the name of an authentication tree or authentication chain AM must use to log in the user.

    For example, to log in to AM using the built-in ldapService authentication chain, 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/authenticate?authIndexType=service&authIndexValue=ldapService'

  • user

    Specifies that the value of the authIndexValue parameter is a valid user ID. AM will then authenticate the user against the chain configured in the User Authentication Configuration field of that user's profile.

    For example, for the user demo 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/authenticate?authIndexType=user&authIndexValue=demo'

    Authentication will fail if the User Authentication Configuration field is empty for the user.

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

Required: No.

authIndexValue

Specifies the value of the authIndexType parameter.

Required: Yes, when using the authIndexType parameter.

noSession

When set to true, 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/authenticate?noSession=true'
{
    "message":"Authentication Successful",
    "successUrl":"/openam/console",
    "realm":"/"
}

Required: No.

Read a different version of :