authenticate

Description

Handles user authentication by creating and terminating users session.

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

Sign in with code

The 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 with this service using the code action.

This method is only available to users who have an email address with 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 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 code

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="[success|failed|logout|auth_code]"
             [code="qwertyuiopasdfghjklzxcvbnm"]/>

The following is a summary of the response statuses based on the action parameter.

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.

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="failure"/>

Or if JSON was requested:

{ "status": "failure" }