OAuth Client Registration

To initiate the process of OAuth authentication, you must first register a Client.

Provide registration data about your client. The registration data is categorised into the following types:

• Human-readable information
• Pleo specific information
• Technical information

Registration Data

Human-Readable Information

Human-readable information represents the following to the end-users:

• Branding of the client
• Link to the home page of the application or a page announcing the integration of the application with Pleo
• Legal Policy documentation

❗️

Do not use Pleo branding

In human-readable information, do not mention Pleo's name and branding. Also, instead of naming the application branding as a client of Pleo (Example Client for Pleo), just use Example Client.

The following table lists the human-readable parameters required for registering a client:

Pleo Specific Information

The following table lists the parameters that are specific to integration of your client with Pleo:

Technical Information

Technical information is used internally in OAuth protocol to implement the redirection between the Pleo authentication server and the client.

Client Credentials

After completing registration, you would receive a set of credentials for your client:

• Client Identifier: This is a unique identifier that makes your client easily identifiable from others. In addition, it allows Pleo to present the branding of your client to end-users when they are asked to authenticate their identity while trying to access the Pleo data. Client identifier is not a confidential information and is visible to anyone attempting to connect your client with Pleo using OAuth.
• Client Secret: Requests from the client are authenticated using the Client Secret, most notably, during access token request. As the name suggests, this information is confidential and you must store this securely.
  • Client secret must never be stored on or exposed to a device to which the end user has direct access. For example, it cannot be embedded in the code of the application that runs on users’ devices or transferred over network to a user's device.
  • Client secret may only be stored and used on a secured server component of your client from where it cannot be extracted easily.

⚠️

Note: These credentials are confidential and must be implemented in such a way that it is impossible for any end user of your client or any unauthorised party to extract the information.

The Pleo OAuth Authorisation Server does not support any public client that cannot protect the confidentiality of the authentication credentials.

Client Registration Example

A hypothetical client can be registered using the following parameters:

After registration, partners receives a set of client credentials.

These values are used in the Example section of Implementing the OAuth client from scratch document.

Redirect URIs

Redirect URI indicates the location where the users are redirected after successful authentication. Hence, in the context of Pleo integration with your client, after the Pleo Authorisation Server authenticates your client, the users are redirected to the specific URI.

HTTP redirections are crucial in OAuth protocol flow using authorisation code grant.

The client must implement a redirection endpoint, also known as “OAuth callback”. This endpoint must be secured by Transport Layer Security (TLS) and must be hosted on a public domain (hence, accessible to all users on the internet). When registering your client, you must provide this redirection URL in the technical information.

HTTP is allowed for local development

Use of HTTPS is often inconvenient in local development environment. Therefore, there is an exception for "loopback" or "localhost" redirect URIs, which can use the unencrypted HTTP protocol. Specifically, these hosts can use http scheme in redirect URIs:

• localhost loopback interface
• 127.0.0.1 IPv4 loopback interface, recommended
• [::1] IPv6 loopback interface

Only exact localhost host name is supported. Aliases such as myclient.localhost or myclient.local would not be accepted.

💡 Note When deploying your client in the production environment, use of HTTPS is mandatory.

Multiple Redirect URIs

If you intend to support multiple URLs for redirection endpoints, you must provided as a list of registered redirect URIs.

Often, a client allocates resources of their customers in subdomains (or sub-paths). For example: an application might host Alice’s resources at alice.client.example, Bob’s resources at bob.client.example. Some early implementations of OAuth offered this functionality, but later it is diagnosed to be vulnerable to a certain class of attacks on the OAuth protocol.

❗️

Wildcard redirect URIs are not supported

To comply with best security practices, Pleo authorisation server does not offer any support for wildcards in redirect URIs.

If your client uses wildcards, we recommended using the state parameter to save the location your users must be redirected to after completing the OAuth flow. In this way, a single redirect endpoint can dispatch users’ browsers to different destinations.

Testing OAuth Using Graphical User Interface (GUI) Applications

During development, it is often beneficial to test the OAuth flow, before setting up the client in the production environment. There are a number of popular HTTP GUI applications that offer support to test the OAuth authorisation.

⚠️

Note: Register redirect URIs of your GUI application - if you intend to use a HTTP GUI application for testing the OAuth flow and debugging Pleo API calls, ensure that you include the redirect URIs (supported by the GUI applications) in a list of registered redirect URIs for your client.

We recommend using Postman how to configure and use Postman to test OAuth and Pleo APIs.