Skip to main content

 Services

Web services from /about to /webhooks

authenticate

/authenticate [GET]

Description

Handles user authentication by creating and terminating users session.

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

Action
loginSign in to PageSeeder with authentication code only
logoutSign out of PageSeeder
codeRequest an authentication code for Single-Sign On (SSO)

You must use the /authenticate POST to submit the credentials. The login action without an autho_code parameter returns an HTTP 405 error when using GET.

All authentication events, whether they are successful or not, are recorded in the access logs.

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.

During the code request, the client app exchanges an ID token for an authentication code. The authentication code is then used by the browser to receive the Cookie containing the PageSeeder session ID. 

Parameters

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

Sign in with code

NameDescriptionRequiredTypeDefault
actionSet to loginyesstring
client_idThe client IDyesstring
auth_codeThe authentication code to sign inyesstring

Sign out

NameDescriptionRequiredTypeDefault
actionSet to logoutyesstring

No other parameter is required, but the service uses the session cookie to determine which session to end. If the cookie isn't included in the request, this action has no effect.

Code request

NameDescriptionRequiredTypeDefault
actionSet to codeyesstring
client_idThe client IDyesstring
id_tokenThe ID token to sign inyesstring
scopeScope for authentication codenostring""

During the code request, the client app effectively exchanges an ID token for an authentication code.

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.

ActionConditionStatus
loginCredentials are correct and no errorsuccess 
code Credentials are correct and no errorauth_code
logoutAnylogout 
AnyCredentials are incorrect or any other errorfailed

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]" }

Authentication codes are credentials and must be protected adequately.

Error handling

HTTP status codeError condition
400The specified action parameter is invalid
405Attempting to sign in with action login and no auth_code.

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" }
Created on , last edited on