OAuth client registration
Registering your application to use OAuth
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".
Parameter | Description |
---|---|
Client Name | A brand name of your application. |
Client URI | A link to the home page of your application, or a landing page dedicated to integration of your application with Pleo. |
Logo | An image representing the logo of your application. Square images (1:1 aspect ratio) in high resolution work best. |
Terms of Service | Link to human-readable legal document describing contractual relationship between the end-user and the client, which is accepted by the end-user during authorisation of the client. |
Privacy Policy | Link to human-readable legal document that describes how the deployment organisation collects, uses, retains, and discloses personal data. |
Contacts | Contact information of people responsible for this client, typically email addresses. |
Initiation URI | (Pleo-specific) A link to a page on which the end user can start the process of connecting your application to Pleo. Allows your application to be listed in the catalogue of applications integrated with Pleo. |
Configuration URI | (Pleo-specific) A link to a page hosting the user interface to changing preferences of your application. Allows to link to the configuration page of your application directly from within Pleo product applications. |
Technical information is used internally in OAuth protocol to implement the redirection between authorization server and client.
Parameter | Description |
---|---|
Redirect URIs | A list of URIs implementing the OAuth redirection endpoint. |
Scopes | A list of API scopes that a client is restricted to when requesting access tokens. |
PKCE Support | By default, we require all clients to implement PKCE extension of OAuth protocol to secure it against certain types of attacks. If this requirement cannot be met for technical reasons, we allow exceptions from this requirement for certain clients on an individual basis. |
Subject Type Preference | (Optional, Pleo-specific) The default type of resources your application is capable of working with. |
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 interface127.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.
Parameter | Value |
---|---|
Client Name | “Example Client” |
Client URI | https://client.example/ |
Terms of Service | https://client.example/legal/tos.html |
Privacy Policy | https://client.example/legal/privacy.pdf |
Contacts | [email protected] |
Redirect URIs | https://client.example/callback |
Scopes | test:test users:read users:write |
PKCE Support | Supported |
Subject Type Preference | None |
After registration, partners receives a set of client credentials.
Credential | Value |
---|---|
Client identifier | 36e3b610-56d7-4d36-92c7-a003ca7bfc5f |
Client secret | 70771f3cbf472ba916aefd21be9c7a |
These values are used in the Example section of Implementing the OAuth client from scratch document.
Updated 3 months ago
Implement and configure your OAuth client