Authentication

This document will provide a high level overview, but we recommend that users familiarise themselves with the following specs:

• OpenID Connect Core
• Financial Grade API Read Only Profile
• Financial Grade API Read/Write Profile

Base URL:

• https://identity.moneyhub.co.uk

Discovery

https://identity.moneyhub.co.uk/oidc/.well-known/openid-configuration

OpenID Connect Discovery Spec

Our discovery document is available here. It will contain our up-to-date machine readable configuration and for example will list our:

• token endpoint
• authorization endpoint
• jwks endpoint
• scopes that we support
• claims that we support
• the cryptographic algorithms we support
• the response types we support

Examples of discovery metadata from other providers are:

• Google
• Microsoft

Response Types

Our discovery doc will list the response types that we support. Currently these are: code, code id_token and id_token.

code is fairly straight forward and is the standard OAuth 2 authorization code flow.

code id_token is one of the variants of the hybrid flow and isn’t always understood. At a basic level it means that we will send an id_token along with the authorization code when we redirect the user back to your redirect_uri. This id_token doesn’t contain any identity information, but is rather a detached signature which cryptographically binds the authorization_code we send back with the nonce and the state that you sent to us. It prevents a certain class of code interception attacks and we encourage implementers to use it rather than the basic authorization code flow.

🚧

Response type configuration

When using response_type "code id_token", the redirect URL should be https, rather than http, and grant types configured for the API Client should include "implicit". This is required for production use.

Alternatively, during development, use the "code" response type, without the "implicit" grant type, and you can use http redirect URLs.

Token Endpoint

https://identity.moneyhub.co.uk/oidc/token

To obtain an Access Token, an ID Token, and optionally a Refresh Token, the RP (Client) sends a Token Request to the Token Endpoint to obtain a Token Response when using the Authorization Code Flow.

OpenID Connect Token Spec

We support the following grant types:

• authorization_code
• client_credentials
• refresh_token

Authenticating on the Token Endpoint

Depending on the configured token endpoint method, the authentication sent to the token end point will differ. If you are using a client with client_secret_basic (which is not a recommended approach) then an Authorization header will be sent with a value of Basic base_64_env(${client_id}:${client_secret}).

If your client has a token endpoint authentication method of private_key_jwt you will also need a JWT when getting a token. The JWT will have the following properties in the payload:

• iss - your client id
• sub - your client id
• jti - A unique identifier for the token, which can be used to prevent reuse
• aud - our token endpoint, i.e. https://identity.moneyhub.co.uk/oidc/token
• iat - the time at which the token was issued
• exp - the time at which the token will expire

The JWT is put in the token endpoint body in the property client_assertion. The client_assertion_type will need to be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Example JWT for client assertion

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlRxVk1laV9XdUtqZW5HWlJUbnJpeUxXRnZuS2tzTjNvLWFuWXBqS0JEbVUifQ.eyJqdGkiOiJmRnVjb0JpZTc2MGhJcXA3Vn5CeGQiLCJpc3MiOiI5NzlhYmRhYi1mZDY0LTQyZTYtYWJkMi1lZTc0NTQyZjM0OTMiLCJpYXQiOjE2MjI4MTIzNzUsImV4cCI6MTYyMjgxMjk3NSwiYXVkIjoiaHR0cHM6Ly9pZGVudGl0eS5tb25leWh1Yi5jby51ay9vaWRjL3Rva2VuIiwic3ViIjoiOTc5YWJkYWItZmQ2NC00MmU2LWFiZDItZWU3NDU0MmYzNDkzIn0.Q0CFDaGNAv5qCnH_VLN0Hw62A0NvXqTdwKazaAoV7Vo

{
  "jti": "fFucoBie760hIqp7V~Bxd",
  "iss": "979abdab-fd64-42e6-abd2-ee74542f3493",
  "iat": 1622812375,
  "exp": 1622812975,
  "aud": "https://identity.moneyhub.co.uk/oidc/token",
  "sub": "979abdab-fd64-42e6-abd2-ee74542f3493"
}

Notes

• You will need to provide a unique token identifier and set it to the jti property for all JWTs.
• An issued at and expiry time will be required in the JWTs.
• We would recommend using our API Client Library to generate these auth URLs and token requests if you are developing in JavaScript, or to find an OpenID Connect library for your chosen language that supports request objects.

More information about JWT requests is available here

Client credentials

For a detailed look at the client credentials grant, please look at this document.

Authorization Code

For a detailed look at the authorization code grant, please look at this document.

Refresh Token

The refresh_token grant type is implemented exactly as according to the specs in RFC6749 and OIDC.

JWKS Endpoints & Asymmetric Signatures

The JSON Web Key Set (JWKS) endpoint is a read-only endpoint that returns your public key set in the JWKS format. This contains the signing key(s) that we will use to validate signatures from the tokens issued using your credentials. More infromation on this endpoint is available in the OIDC specs

We use jwks endpoints to support the rotation of signing keys

As part of registering your client software with us, we will ask you for your own jwks endpoint.

If you don’t yet have one, we strongly encourage you to implement one. JWKS endpoints provide a neat method to achieve key rotation without any interruption to service or any need for bilateral communication.

They enable you to manage your keys in which ever manner you see fit and removes the need for the client_secret.

The endpoint should be publicly accessible and should serve an array of public keys in JSON format like the example below:

{
  "keys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "NTAxZmMxNDMyZDg3MTU1ZGM0MzEzODJhZWI4NDNlZDU1OGFkNjFiMQ",
      "alg": "RS256",
      "n": "luZFdW1ynitztkWLC6xKegbRWxky-5P0p4ShYEOkHs30QI2VCuR6Qo4Bz5rTgLBrky03W1GAVrZxuvKRGj9V9-PmjdGtau4CTXu9pLLcqnruaczoSdvBYA3lS9a7zgFU0-s6kMl2EhB-rk7gXluEep7lIOenzfl2f6IoTKa2fVgVd3YKiSGsyL4tztS70vmmX121qm0sTJdKWP4HxXyqK9neolXI9fYyHOYILVNZ69z_73OOVhkh_mvTmWZLM7GM6sApmyLX6OXUp8z0pkY-vT_9-zRxxQs7GurC4_C1nK3rI_0ySUgGEafO1atNjYmlFN-M3tZX6nEcA6g94IavyQ"
    }
  ]
}

Errors

Many of the errors returned are in accordance with the OpenId Connect specification.

Authorization error response

The error codes returned from https://identity.moneyhub.co.uk/oidc/auth will match those in the OpenId spec. Please see here for a list of those errors.
OpenId Connect adds to the list of errors in the Oauth 2.0 spec. Please see here for a list of the Oauth 2.0 errors. For convenience we've also listed those errors here:

• invalid_request - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
• unauthorized_client - The client is not authorized to request an authorization code using this method.
• access_denied - The resource owner or authorization server denied the request
• unsupported_response_type - The authorization server does not support obtaining an authorization code using this method.
• invalid_scope - The requested scope is invalid, unknown or malformed.
• server_error - There was an unexpected error
• temporarily_unavailable - The authorization server is currently unable to handle the request due to a temporary overloading or maintenance of the server.
• invalid_request_uri - The request_uri in the Authorization Request returns an error or contains invalid data.
• invalid_request_object - The request parameter contains an invalid Request Object.
• access_denied - Returned on redirect when user cancels the flow whilst in providers authorisation screen.

Token error response

The error codes returned from the https://identity.moneyhub.co.uk/oidc/token endpoint will match those in the Oauth 2.0 spec. Please see here for a list of Oauth errors that can be returned. For convenience please also see that list below.

• invalid_request - The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
• invalid_client - Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).
• invalid_grant - The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
• unauthorized_client - The authenticated client is not authorized to use this authorization grant type.
• unsupported_grant_type - The authorization grant type is not supported by the authorization server.
• invalid_scope - The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

For more information about the benefits of this approach or advice on implementing, please contact us.