authenticate

Description

Handles user authentication by creating and terminating users session.

The action parameter and sign-in method determines the authentication process.

Use this service to implement Single Sign-On (SSO).

The session timeout is configurable with the sessionTimeout global property.

Sign in with password

This sign-in method lets the user sign in using their username or email address, and their password. This is the default method and is available to all users unless their email domain is flagged as external only in the identity configuration.

The “remember me” option, sets a encrypted cookie on the client so that the user does not have to sign in again. Signing out destroys the cookie and requires the user to sign in again.

Sign in with code

This sign-in method lets a trusted third-party app sign in on behalf of the user using an authentication code. This code is a One-Time-Password (OTP) and can only be acquired using the code action using this service.

This method is only available to users who have an email address and the email domain is listed in the identity configuration.

Sign in with token

This sign-in method lets a trusted third-party app sign in the user directly using an ID token issued by a registered external identity provider.

This method is only available to users who have an email address and the email domain is listed in the identity configuration.

Sign out

The logout action is always successful regardless of whether the user is authenticated or not. If the user is authenticated:

• The session is invalidated and destroyed.
• The “remember me” cookie is deleted.

Code request

Use this action to acquire a single use authentication code to use as part of a Single Sign On (SSO) authentication flow.

To get an authentication code, the following conditions must be met:

• A valid ID token is provided using the id_token parameter.
• The iss and aud claims in the ID match an external ID provider in the external identity config.
• The domain of email address from the ID token matches an authorised email domain in the external identity config.
• A registered client ID is provided using the client_id parameter.
• The email in the ID token matches an existing user account.

When successful, a one-time-use authorization code is returned in the response and can be used for sign in with action=login.

Parameters

The set of parameters to use depends on the action parameter and sign-in method used.

Sign in with password

Both the username and password are limited to 100 characters.

Sign in with code

Sign in with token

Sign out

Code request

Permission

This is a public service: anyone can use this service.

This service supports CORS.

Response

The XML response returned is always:

<authenticate status="[status]"
             [email="somebody@example.com"]
             [code="qwertyuiopasdfghjklzxcvbnm"]/>

The following is a summary of the response statuses based on the action and sign-in method.

Successful sign-in

When the action parameter is login, the sign-in is successful. The sign-in method does not affect the response and returns:

<authenticate status="success"/>

or

{ "status": "success" }

This response also includes the session Cookie.

Locked account

When the action parameter is loginand the sign-in method is password but the account is locked due to repeated sign-in failures, this service responds with:

<authenticate status="locked"/>

or

{ "status": "locked" }

Unactivated account

When the action parameter is login and the sign-in method is password but the account has not been activated by the user, this service responds with the status activation_required and includes the email address of the user to be used for account activation. This is to let the user or client app know that the user must activate their account and occurs even if the submitted user credentials are valid.

For example:

<authenticate status="activation_required" email="somebody@example.org"/>

or

{ 
  "status": "activation_required",
  "email":"somebody@example.org"
}

External only

When the action parameter is loginand the sign-in method is password but the domain of the email address used for sign-in is configured to be external only in the identity config, this service responds with the status external_only. This is to let the user or client app know that the user cannot sign-in directly via PageSeeder and occurs even if the submitted user credentials are valid.

For example:

<authenticate status="external_only"/>

or

{ "status": "external_only" }

Sign out

When the action parameter is logout, the response is always:

<authenticate status="logout"/>

or

{ "status": "logout" }

Code

When the action parameter is code and the response is successful:

<authenticate status="auth_code" code="[one-time-auth-code]" />

or 

{ "status": "auth_code", "code": "[one-time-auth-code]" }

Error handling

For security reasons, this service does not disclose the reason for failure. It returns the following response with HTTP 200 status code:

<authenticate status="failed"/>

Or if JSON was requested:

{ "status": "failed" }