OAuth client registration

To begin using OAuth with Pleo, you must first register an OAuth client. In order to do that, you should provide information about your client, which broadly falls into two categories: human-readable information, and technical information.

Registration data

Human-readable information is presented to end-users, allowing them to recognise the branding of your client, and access its home page, read relevant legal documents, and so on.

🚧

Do not use Pleo branding

Do not use Pleo name or branding in human-readable information describing your client. Instead of naming the client "Example Client for Pleo", simply use "Example Client".

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

Redirect URIs

HTTP redirections are central to OAuth protocol flow using authorization code grant.

Your client must implement a redirection endpoint, also known as “OAuth callback”. This endpoint must be secured by TLS, and must be publicly accessible from the internet. When registering your client, provide the URL of a redirection endpoint of your client.

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 will not be accepted.

When deploying your application in production environment, use of HTTPS is required.

Multiple redirect URIs

If you plan on supporting multiple URLs for redirection endpoints, they must be provided as a list of registered redirect URIs.

Often, client applications allocate resources of their customer in subdomains (or sub-paths). For example: an application may host Alice’s resources at alice.client.example, Bob’s resources at bob.client.example, etc. In this case, it is tempting to register a redirection endpoint which uses a “wildcard” domain, like https://*.client.example/callback. Some early implementations of OAuth offered this functionality, but later it was found to be vulnerable to a certain class of attacks on the protocol.

🚧

Wildcard redirect URIs are not supported

According to best security practices, Pleo authorization server does not offer any support for wildcards in redirect URIs.

In case your application uses a similar mechanism, we recommended using state parameter to save the destination your users should arrive to after completing the OAuth flow. This way, a single redirect endpoint can dispatch users’ browsers to different destinations.

Testing OAuth using GUI clients

During development, it is often beneficial to test the OAuth flow before setting up a client in your production environment. A number of popular HTTP GUI applications offer support for OAuth authorization.

📘

Register redirect URIs of your GUI API client

If you plan on using a HTTP GUI app for testing the OAuth flow and debugging Pleo API calls, make sure to include the redirect URIs supported by those apps in a list of registered redirect URIs for your client.

We describe how to configure and use Postman, to test OAuth and Pleo APIs.

Clients with no support for PKCE extension

If your client doesn’t support PKCE (RFC 7636), you should request to mark it as not supporting PKCE when registering your client.

🚧

PKCE is recommended

PKCE extension significantly improves the safety of OAuth protocol, and should be implemented, if at all possible.

Client credentials

After completing registration, you will receive a set of credentials for your client: a client identifier and a client secret. You should store them safely. Anyone who knows the credentials of your client will potentially be able to present themselves as your application.

📘

Client must be able to keep its secrets

Only confidential clients are supported, which means the client has to be implemented in such a way as to make extraction of client secret impossible for end users of the client, or any other unauthorised parties.

🚧

Public clients are not supported

Public clients, which are incapable of maintaining confidentiality of their credentials, are not supported by Pleo OAuth authorization server.

A client identifier distinguishes your client from others, and allows Pleo to present the branding of your client to end-user when asking to authorise access to their Pleo data. Client identifier is not secret information, and is clearly visible to anyone who attempts to connect your application to Pleo using OAuth.

Requests from the client are authenticated using client secret, most notably, during access token request. As the name suggests, client secret is confidential and must be stored 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 device.

Client secret may only be stored and used on a secured server component of your client, from where it cannot be extracted easily.

Example

A hypothetical client application can be registered using these 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.