Creating an Authorisation URL

The first step to the majority use cases.

📘

This is a very in depth description of generating an authorisation URL. We would recommend finding an OIDC client library that has request object support in your language of choice. Some certified libraries are listed here.

To create a connection to a banking provider, you'll need to create an OpenID Connection authorisation URL. The URL will incorporate all the information required for our service to understand:

  • Scopes
  • Client ID the connection will belong to
  • Response type
  • Redirect URL to go to after user consent
  • State
  • Nonce
  • Claims
  • Prompt - our authorisation server will only accept a value of consent

With all the information above, you will be able to construct an authorisation URL. You can construct one by passing in the information as query parameters. This is the simplest way to generate an authorisation URL:

https://identity.moneyhub.co.uk/oidc/auth
  ?client_id=9553c702-0985-4124-b6cb-3cc02ae13c94
  &scope=openid%20id:1ffe704d39629a929c8e293880fb449a
  &response_type=code
  &redirect_uri=http%3A%2F%2Flocalhost%3A3001
  &state=foo
  &nonce=bar
  &prompt=consent
  &claims=%7B%22id_token%22:%7B%22sub%22:%7B%22essential%22:true%7D,%22mh:con_id%22:%7B%22essential%22:true%7D,%22mh:sync%22:%7B%22essential%22:true,%22value%22:%7B%22enableAsync%22:true%7D%7D%7D%7D

Request Object

We support the use of request objects in our authorisation URLs (JWT-Secured Authorization Request (JAR)). Put simply, all the information that is encoded into a JWT. Depending on the configuration of your API client will determine what the header and signature of the JWT will be.

Request Object Header

{
  "typ": "oauth-authz-req+jwt", // helps prevent cross JWT attacks
  "alg": "your configured request object signing algorithm"
  "kid": "if request object signing algorithm specified, specifies the Key ID used to sign JWT"
}

If you have a request object signing algorithm of none, then the header will be

{
  "alg": "none",
  "typ": "oauth-authz-req+jwt"
}

While a header for a client with request object signing algorithm of RS256 could look like this:

{
  "alg": "RS256",
  "typ": "oauth-authz-req+jwt",
  "kid": "eaQHEWFPfJexsV7ac5eRZBzfK8yoZYo6gJH7HnC3OPI"
}

Request Object Body

The body of the request object must contain the values you would normally contain in the authorisation request URL, as well as some additional parameters as per the specification. Below is an example decoded request object body:

{
  "client_id": "9679af15-691c-4c0b-8d48-f385f086b382", // from normal authorisation URL
  "scope": "openid offline_access id:1ffe704d39629a929c8e293880fb449a accounts:read transactions:read:all categories:read categories:write spending_goals:read savings_goals:read", // from normal authorisation URL
  "state": "foo", // from normal authorisation URL
  "nonce": "bar", // from normal authorisation URL
  "redirect_uri": "http://localhost:3001", // from normal authorisation URL
  "response_type": "code", // from normal authorisation URL
  "prompt": "consent", // from normal authorisation URL
  "claims": {
    "id_token": {
      "sub": {
        "essential": true
      },
      "mh:con_id": {
        "essential": true
      },
      "mh:sync": {
        "essential": true,
        "value": {
          "enableAsync": true
        }
      }
    }
  }, // from normal authorisation URL
  "iss": "9679af15-691c-4c0b-8d48-f385f086b382", // JWT spec and must be the client ID
  "aud": "https://identity.moneyhub.co.uk/oidc", // JWT spec and must be the value specified here
  "jti": "qj3_KqJ9ntPLmlS_ZNhgUP1I4ZQJS3LotW22zloh5XI", // JWT spec, a cryptographicaly random value (optional but recommended)
  "iat": 1659598578, // JWT spec issued at
  "exp": 1659598878 // JWT spec expired
}

Request Object Signature

If the request object signing algorithm is none, then this will be blank and the JWT will end in a .

🚧

URL Validation

If you're using no request object signing, please ensure that final . is included in the URL that is sent to the user's browser, otherwise we will reject the URL as invalid.

Otherwise, you must sign the JWT with the private key that matches with the public keys you've provided in your API client configuration (whether via the JWKS URI or the hard coded values).

We would recommend finding a JWT library that will handle the creation of a JWT for you.

Using the Request Object

When you have generated the request object JWT, you can supply it in two ways:

  • Directly in the authorisation URL in the request query parameter of the authorisation URL (example at the bottom)
  • Use the /requests end point. Information on that can be found here.