pps-platform-auth

Overview

Access to PPS APIs requires an access token obtained through the Authorisation API, an OAuth 2.0 Authorisation Server implementation. The following text describes the PPS OAuth 2.0 implementation and its extensions.

OAuth 2.0

OAuth 2.0 is an industry-standard protocol for authorisation. OAuth 2.0 introduces the following terminology to describe entities involved in the authorisation process:

• Resource Owner - an entity capable of granting access to a protected resource e.g. the accountholder.
• Resource Server - The server hosting the protected resources i.e. PPS.
• Client - The application making protected resource requests on own behalf or on behalf of the resource owner.
• Authorisation Server - The PPS Authorisation API.

OAuth 2.0 defines multiple authorisation scenarios, termed 'Grant Types', to suit different use cases. The following grant types are currently implemented by PPS:

• Client Credentials Grant - the client (PPS customer or partner) requests an access token using only its client credentials.

Figure 1: Client Credentials Grant Authorisation

• Resource Owner Password Credentials Grant - where the client has a trust relationship with the Resource Owner the client requests an access token using its client credentials and the resource owners credentials (username and password).

Figure 2: Resource Owner Password Credentials Grant Authorisation

Additionally OAuth 2.0 defines the scope property as a space separated set of access privileges. Scopes may be optionally specified in the access token request or omitted to obtain the full access privileges for the Client or Resource Owner. The allowed scope is included in the token response (either matching the requested scope or the full access privileges if not provided in the request).

Authentication

Client Authentication

PPS have adopted the standard Signing HTTP Messages draft-cavage-http-signatures-12 for authentication. This will be used to authenticate the client for the Client Credentials Grant type.

Figure 3: Client Authentication with HTTP Message Signature

The Authorization header must be included with the authentication scheme 'Signature' as constructed below:

The following headers are required:

• (request-target) - A 'special' header field name generated by concatenating the lowercased :method, an ASCII space, and the :path pseudo-headers (as specified in HTTP/2, Section 8.1.2.3). See HTTP Message Signing, Section 2.3.
• host - The standard HTTP host header
• date - The standard HTTP date header

with message body:

• digest - The SHA-256 digest of the message body. This must be a digest of the url-encoded payload.

The Signature header is constructed as per HTTP Message Signing, Section 2.3. The algorithm must always be rsa-sha256.

Example:

request:

POST /auth/api/v1/token HTTP/1.1
Host: api.prepaysolutions.com
Date: Tue, 20 Mar 2020 01:02:25 GMT
Content-Type: application/x-www-form-urlencoded
Digest: SHA-256=HrFpt67h3Ildx4opZaosr3ucuzhO/O9dqsM17YgjlDE

client_id=myppsclient&grant_type=client_credentials

The signing string would be constructed as the concatenation of the following lines (new line should be included except for after the last line):

(request-target): post /auth/api/v1/token
host: api.prepaysolutions.com
date: Tue, 20 Mar 2020 01:02:25 GMT
digest: SHA-256=HrFpt67h3Ildx4opZaosr3ucuzhO/O9dqsM17YgjlDE

The final header has the form:

Signature keyId="key-0",algorithm="rsa-sha256",
         headers="(request-target) host date digest",
         signature="Base64(RSA-SHA256(signing string))"

Note that the order of the headers specified in the headers property of the Signature MUST correspond to the order of the headed in the signing string.

Scope

OAuth 2.0 defines the scope parameter to both request and confirm the allowed permissions for the authenticated client. Scopes are provided as a space separated list of permission or role ids. Applicable permissions are documented for each PPS API.