Skip to main content

 Services

Web services from /about to /webhooks

authenticate

/authenticate [POST]

Description

Handles user authentication by creating and terminating users session.

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

ActionProcess
loginSign in to PageSeeder (with password, authentication code or ID token) by authenticating a member and creating a session.
logoutSign out of PageSeeder by terminating the user session.
codeRequest an authentication code to sign in with code.

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

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

The session timeout is configurable with the sessionTimeout global property.

If your app does not require a session, you do not need to use this service. Use access tokens instead with OAuth authorization code flow.

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.

The account is locked when there are multiple consecutive failed sign-in attempts.

For the same reasons that OAuth 2.0 Security Best Current Practice  disallows the password grant entirely, we don’t recommend that you let your users enter their credentials outside PageSeeder as it is considered bad practice. The only case where it is acceptable is when users are never exposed to PageSeeder and only manage their credentials through your app.

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.

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 password

NameDescriptionRequiredTypeDefault
actionSet to loginyesstring
login-usernameThe username or email of the user yesstring
login-passwordThe password of the useryesstring
rememberWhether to remember this sign innobooleanfalse

Both the username and password are limited to 100 characters.

Sign in with code

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

Sign in with token

NameDescriptionRequiredTypeDefault
actionSet to loginyesstring
id_tokenThe ID token 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 terminate. 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="[status]"
             [email="somebody@example.com"]
             [code="qwertyuiopasdfghjklzxcvbnm"]/>

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

ActionSign-methodConditionStatus
loginPasswordUser account is lockedlocked
loginPasswordUser account requires activationactivation_required 
loginPasswordEmail domain configured as external onlyexternal_only 
loginAnyCredentials are correct and no errorsuccess 
code TokenCredentials are correct and no errorauth_code
logoutAnyAnylogout 
AnyAnyCredentials 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.

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

For security reasons, this service does not indicate how long an account is locked for or how many unsuccessful sign-ins caused the account to be locked. Administrators can unlock a user account from the Account profile page of the user in the system administration.

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

Authentication codes are credentials and must be protected adequately.

Error handling

HTTP status codeError condition
400The specified action parameter is invalid.

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