Documentation

Creating an Authorisation URL

The first step to the majority use cases.

Suggest Edits

📘

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.

📘

Pushed Authorisation Requests

We now recommend creating an authorisation URLs using the Pushed Authorisation Request feature of OIDC. This will be explained in this document. If you wish to use the older way, look at version 2.3 of our documentation.

For pushed authorisation request URLs, it is recommended that you have the Request Object Signing Algorithm set to none on your API Client configuration.

To create a connection to a banking provider, you'll need to create an OpenID Connection authorisation URL. The URL will contain a request URI that is generated when sending the following request information to our Pushed Authorisation Request end point:

  • 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

📘

Payment Claims

If you are wishing to create a payment authorisation URL, you will need to include the mh:payment claims. You can find documentation on that here

With all of the information above, you can construct a request to the pushed authorisation request end point to get a request URI, from there you will be able to generate the authorisation URL. The high level steps for that are as follows:

  1. Gather the authorisation parameters you require that would go in a normal authorisation URL (see above)
  2. Put the parameters in a request body, the request should have content type of application/x-www-form-urlencoded
  3. Add to the request the required authentication that you would use for the token end point. (See Authentication)
  4. Send the request to https://identity.moneyhub.co.uk/oidc/request
  5. From the response, extract the request_uri
  6. Create the authorisation URL in the format: https://identity.moneyhub.co.uk/oidc/auth?request_uri=<request_uri>

Examples

Make a request to the Pushed Authorisation Request end point with a body with the required auth parameters, and authentication for your client. The example cURL below is configured for a publicly available API client with client secret basic auth for you to try.

The example below makes a simple one time access connection to a test bank where the resulting access token will allow you to see the accounts and transactions of the connection made.

Example using client_secret_basic auth method

curl --location --request POST 'https://identity.moneyhub.co.uk/oidc/request' \
--header 'Authorization: Basic NDkyYTk5YmYtY2I0OS00NmFlLThkYzQtZjQ2YWViOGQwMzQ3OjYwMGQyMDRlLWE3M2MtNGE0NC04MTRmLTEwMWMyMzVhZjM3Zg==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=openid id:test accounts:read transactions:read:all' \
--data-urlencode 'response_type=code id_token' \
--data-urlencode 'redirect_uri=https://example.com' \
--data-urlencode 'state=foo' \
--data-urlencode 'nonce=bar' \
--data-urlencode 'claims={"id_token":{"sub":{"essential":true},"mh:con_id":{"essential":true}}}' \
--data-urlencode 'prompt=consent' \
--data-urlencode 'client_id=492a99bf-cb49-46ae-8dc4-f46aeb8d0347'

Example using private_key_jwt auth method

If you client is set to using private_key_jwt at the token endpoint auth method, then please see below an example of how you should construct the request to https://identity.moneyhub.co.uk/oidc/request. It is the same as above except we do not send an Authorization header, but instead provide a client_assertion JWT signed with the corresponding private key (that matches the public key configure in the admin portal).

curl --location --request POST 'https://identity.moneyhub.co.uk/oidc/request' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=openid id:test accounts:read transactions:read:all' \
--data-urlencode 'response_type=code id_token' \
--data-urlencode 'redirect_uri=https://example.com' \
--data-urlencode 'state=foo' \
--data-urlencode 'nonce=bar' \
--data-urlencode 'claims={"id_token":{"sub":{"essential":true},"mh:con_id":{"essential":true}}}' \
--data-urlencode 'prompt=consent' \
--data-urlencode 'client_id=492a99bf-cb49-46ae-8dc4-f46aeb8d0347'
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
--data-urlencode 'eyJhbGciOiJSUzI1NiIsImtpZCI6Im9TQzVYTzgtaU43SzRobWVHXzg1OGlTSi1Ma3lqVUZXOVlmR0l3S1JXekEifQ.eyJzdWIiOiI0OTJhOTliZi1jYjQ5LTQ2YWUtOGRjNC1mNDZhZWI4ZDAzNDciLCJhdWQiOiJodHRwczovL2lkZW50aXR5Lm1vbmV5aHViLmNvLnVrL29pZGMvdG9rZW4iLCJpc3MiOiI0OTJhOTliZi1jYjQ5LTQ2YWUtOGRjNC1mNDZhZWI4ZDAzNDciLCJqdGkiOiJlZTAwMDliNC0yYjgyLTQwYmYtOTAyZi00MTUwZmVjYWQ5ZjQiLCJpYXQiOjE3MjQ5MjY0MTcsImV4cCI6MTcyNDkyNzAxN30.qns74r5M8ajraWplPJt6S_TTQDn-iQFPxnVyVgLXLYQFWd-RNqC7yzUGfuHR6ZTWlyjuphBvqKF1I0HSRmpvshL5j8Lt0-3Bk1MP5L58J58Gdsh8-rQ5Q2Itc_Ga5LbVVVvTzFel4xPtwFMSwMfPxSRF4dXfg2m6Qx0zPYAAhd-lNitMqG4TipcIViKUaTS2UJKvvMUBG7G56CpweAls-GeONv6kK5Nn0o72VDStwFLzlhHITofqB_qqk8Qf9E4LbgjofA61gC54143KKHu7AKjnlbfFYTWGYO4fm0sufAHsBJx-auLdJXZYvJRsW7kn5T0r84tUNK-lBzlPyo5NbA'

The response of the request will return a request_uri, use that value to construct a URL in the format of: https://identity.moneyhub.co.uk/oidc/auth?request_uri=<REQUEST_URI>

Updated 4 months ago