Authentication Endpoint

The end user only interacts with the OAuth 2.0/OpenID Connect server via the authentication endpoint. The endpoint establishes the identity of the end user – the authentication method is defined by a authentication policy during client registration.

Copy

The endpoint is exposed at the following URL (and can be obtained from the server discovery endpoint):

https://[base-server-url]/{tenant}/authn/login [POST]/[GET]

Authentication Request

The client sends a request to the authentication endpoint to authenticate an end user or obtain an access token. In the request, the required parameters are added (as query parameters) to the authentication endpoint URL:

Copy

Sample request

POST https://[base-server-url]/{tenant}/authn/login HTTP/1.1
 
 response_type=code
 &scope=openid email
 &client_id=123
 &state=af0ifjsldkj
 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

Refer to OpenID Connect Core 1.0 for the complete specification.

Note: HID Approve™ Authentication during the OAuth Code Flow:

The login page of the ActivID AS server authentication endpoint can be configured to use HID Approve push-based authentication.

The logon notification messages sent to HID Approve now use the OpenID client name, allowing end users to identify the OpenID client application requesting the logon approval.

For example, if the OpenID client name is “MyApplicationName”, then the message on HID Approve notification will be “Please validate your logon request to MyApplicationName”.

Previously, the messages used the channel code (for example, CH_SSP).

Authentication Response

If the authentication is successful, the ActivID AS server will reply with an HTTP redirect (302) pointing to the callback URI specified in the redirect_uri parameter, appending the response parameters, as defined in the OpenID Connect Core specification – section 3.1.2.5 to the redirect_uri.

Copy

Sample response of successful authentication redirect:

HTTP/1.1 302 Found
Location: https://client.example.org/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj

Error Responses

Error responses follow the OpenID Connect Core specification – section 3.1.2.6.

Code	Label	Possible Errors
400	BAD REQUEST	invalid_request unsupported_response_type invalid_scope

Copy

Sample error response (for reasons other than an invalid client_id or redirect_uri)

HTTP/1.1 302 Found
Location: https://client.example.org/cb?error=invalid_request&error_description=Unsupported%20response_type%20value&state=af0ifjsldkj

Request Parameters

The minimal mandatory request parameters are:

Parameter	Description
`response_type`	Defines the authorization processing flow, specifying the endpoints used and which parameters should be returned. Must be set to code (as the ActivID AS server does not the support the implicit or hybrid flow)
`response_mode`	Defines how ActivID AS delivers the authentication result (tokens) to the client Possible values are: query fragment
`client_id`	OpenID Connect client identifier
`redirect_uris`	Redirection URI to which the response will be sent, which must match one that has been registered during client registration
`scope`	List of the requested scopes (space-separated) Must include at least the "openid" scope. See also Enabling OpenID Connect Claims and Prompting User for Consent.
`[login_hint]`	Allows the client application to specify the end user to authenticate The user identifier is passed to the Authentication Portal so that the end user does not need to enter their user ID. If this parameter is present, the username field is prefilled and grayed-out in the IdP login page. Otherwise, the username field is empty and needs to be populated by the user.
`[code_challenge]`	Opaque value, used by PKCE Note: Use of this parameter is required for public clients and recommended for confidential clients. See also Leveraging Proof Key for Code Exchange (PKCE) in the Authorization Code Grant Flow and Configuring OpenID Connect Support of Public Clients.
`[max_age]`	If this parameter is sent in the authentication request (authentication endpoint), the IdP will check if a recent authenticated HTTP session (same browser and same JSESSIONID in cookies) exists and if the session age is LESS than max_age: If there is no existing session, the user is prompted to authenticate. If a session exists and it is the within the max_age, the user is not prompted to authenticate again and the IdP retrieves the authenticated session stored in the HTTP session. If a session exists but it is has exceeded the max_age, the user is prompted to re-authenticate. The user is also prompted to re-authenticate if a recent authenticated HTTP session exists but: The scope requested has changed (consent signed or not). The client_id requested has changed. The previous authenticated session is invalid (timeout/logout/revoked). The previous authenticated session is from a different HTTP session (attack or HTTP session timeout). For further information, refer to the OpenID Connect Core specification - section 3.1.2.1.
`id_token_hint`	If this parameter is sent in the authentication request (authentication endpoint), the IdP will check if there is a valid authenticated session (where the session's id_token is the value of id_token_hint): If there is no existing session, either the user is prompted to authenticate or a login_required error will be returned if prompt=none. If a session exists, the user is not prompted to authenticate again and the IdP retrieves the authenticated session.