Auth Service

The Paylogic Auth Service is a Single Sign-On platform where a user can log in. Once logged in on the SSO, a user is logged in in all applications that implement the SSO.

Basic login flow

Send a user to the SSO, which will send an authenticated user back to your application.

Send a user’s browser to the SSO at https://auth.paylogic.com/authorize with the following required query parameters: client_id, redirect_uri and response_type. The full URL looks something like https://auth.paylogic.com/authorize?client_id=myclientid&redirect_uri=https%3A%2F%2Fuser.example.org%2Fuser%2F&response_type=token%20id_token. Paylogic will issue a client_id value which is usually a short, lowercase version of your organisation’s name.

If the user is already logged in on the SSO, we immediately redirect the user back to the value specified in redirect_uri with a fresh ID token and/or Access token. The access token can be used for direct communication with the Cognito API. Example redirect_uri with tokens: https://account.example.org/#id_token=...&access_token=...&token_type=Bearer&expires_in=3600.

If the user is not logged in on the SSO, we ask the user to log in or sign up. Once the user has signed up and/or logged in, we send the user back to your application as described in step 2 of this list.

Paylogic will need a list of allowed redirect_uri’s, e.g. [https://example.org/*, https://demo.example.org/user/*]. The path component of each redirect URI can contain wildcards using the * character.

Get a logged in user from the Auth Service

When a user logs in to the Auth Service the user will be logged in for 30 days. The user stays logged in for 30 days. Tokens passed by the Auth Service to client applications are valid for one hour.

If a user is logged out in your application, either because the user never logged in to your app or because the token expired, you can log in the user without any user interaction. Send the user to https://auth.paylogic.com/authorize and use the same parameters as step 1 of Basic login flow, but with prompt=none in the request parameters.

If the user is logged in on the SSO, the user is redirected back to your application with a fresh ID token and/or Access token.

If the user is no longer logged in on the SSO, the user is redirected back to your application with an error=interaction_required query parameter, meaning there’s interaction required from the user because they’re not logged in.

Supported OpenID parameters for the authorization endpoint

We implement a subset of OpenID. The OpenID spec on authorization can be found at https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint.

Parameters not listed in the table below are currently not supported by Paylogic.

Parameter	Example	Default	Supported values
client_id	myclientid	—	Value issed by Paylogic
redirect_uri	https://example.org/	—	URLs whitelisted in our administration
response_type	id_token token	—	token, id_token, or both separated with a space
prompt	login	login	login or none
state	—	—	Any string value
response_mode	fragment	fragment	fragment or query
ui_locales	en	en	de, en, fr or nl

Logging out

Send a user to the logout page at https://auth.paylogic.com/logout with required query parameters: client_id and redirect_uri and optional parameter state. This results in a URl looking like https://auth.paylogic.com/logout?client_id=myclientid&redirect_uri=https%3A%2F%2Faccount.example.org%2F.

Paylogic will log out the user on the SSO, and from the Cognito domain in case the user logged in with an external provider.

You should also log out the user locally in your own application by removing local id and/or access tokens in cookies or other storage.

You can verify that a user is logged out by checking the userinfo endpoint on the Cognito domain with the user’s access token, in which case the endpoint will respond with a 401 error.

Communication with the Cognito API

Once you have a valid Access token for a user, you can communicate directly with Cognito, for example to fetch or update user details.

You can find the full documentation for Cognito here.

Cognito has SDK’s for all popular programming languages, like Python, Go, PHP and JavaScript.

Authorization using Proof Key for Code Exchange

Security can be improved via Proof Key for Code Exchange mechanism, which is explained in this article.

First, a code_identifier must be generated, which is described here. Note that the code_verifier should be between 43 and 128 characters long.

Secondly, the process can be initiated by requesting https://auth.paylogic.com/authorize with the following query parameters:

Parameter	Example	Default	Supported values
client_id	myclientid	—	Value issed by Paylogic
redirect_uri	https://example.org/	—	URLs whitelisted in our administration
response_type	code	—	code
state	—	—	Any string value
response_mode	fragment	fragment	fragment or query
code_challenge	_	_	See this link on how to generate the code_challenge based on the code_verifier.
code_challenge_method	S256	—	S256

When requested successfully, the endpoint will respond with a 302 FOUND response, based on the redirect_uri with an additional code query param. This code will stay valid for one minute.

The obtained code must be used to obtain the tokens by requesting https://auth.paylogic.com/token with the following query parameters (See documentation here):

Parameter	Example	Default	Supported values
grant_type	authorization_code	—	authorization_code
code_verifier	—	—	The key that was generated in the first step.
code	—	—	The value obtained in the query param when requesting https://auth.paylogic.com/authorize in the previous step.
client_id	myclientid	—	Value issed by Paylogic
redirect_uri	https://example.org/	—	URLs whitelisted in our administration

The endpoint returns a JSON response with the following keys:

Key	Value
access_token	The access token for communication with AWS Cognito.
refresh_token	The refresh token for communication with AWS Cognito.
token_type	E.g. “Bearer”.
expires_in	E.g. “3600”.
id_token	E.g. “eyJ0XAi…4faeEoQ”