Authorization and Authentication
Before a customer can authorize your application for account requests or payment initiation using Metro Bank APIs, you must be registered with Metro Bank and authorized by the Financial Conduct Authority (FCA).
The authorization process requires that customer authentication takes place with Metro Bank using strong customer authentication framework.
To fulfil this authentication, Metro Bank has implemented a strong customer authentication login portal through which the customer authenticates and provides consent to your application to access selected accounts and initiate payment. The consent granted in this step for account services shall include only the permissions supplied when creating an account request or account access consents.
A ConsentId (OBIE 3.1.1 API Portfolio including Account and Payment) or AccountRequestId (AISP API Portfolio) must have been created prior to attempting the customer authorization steps described below.
Step 1: Redirect customer to Metro bank consent login
Please redirect customer to Metro Bank's strong customer authentication portal using the following URLs:
- Sandbox: https://sandbox.metrobankonline.co.uk/identity/v1/authorize?client_id=&redirect_uri=redirect_uri&response_type=code id_token&scope=accountsopenid&state=<tpp_state_value>&nonce=<tpp_nonce_value>&request=<request_jwt>
- Production: https://scapip.metrobankonline.co.uk/portalserver/psd2/authorize?client_id=<client_id>&redirect_uri=redirect_uri&response_type=code id_token&scope=accountsopenid&state=<tpp_state_value>&nonce=<tpp_nonce_value>&request=<request_jwt>
Please use our interactive /authorize to see an example request and response to explore more. Here are few additional bits of information:
- client_id: Identifier of the TPP client, provided to you at successful registration.
- redirect_uri: After completing its interaction with the TPP consumer, the authorization server directs the TPP consumer's user-agent back to the TPP client using this uri. This is validated against the redirect urialready registered in the authorization server
- response_type: type of response you expect, as we are using open id connect hybrid flow and want to allow account to customers accounts you will use - use value "code id_token"
- scope: The scope accounts or payments must be used along with openid in order to gain secure access to accounts data endpoints or payment initiation - use value "accounts openid" for account and "payments openid" for payment
- state: An unpredictable randomised string used to protect against cross-site request forgery
- nonce: Used to help mitigate against replay attacks. If present, it will be replayed in the id_token.
- request: The request value is a JSON Web Tokens (JWT). JWTs are used throughout the API identity flow.
Creation of Request JWT
You should have a ConsentId (OBIE 3.1.1 API Portfolio including Account and Payment) or AccountRequestId (AISP API Portfolio) for each customer verification claim.
The ConsentId or AccountRequestId is the claim held in the request jwt. In decoded form the request JWT is structured like so:
Please use the private key that you have generated during CSR generation process, to sign the request JWT.
Step 2: Customer verification
Once a customer consent has finished, the Metro Bank's strong customer authentication portal will send a 302 redirect to the provided (through app registration form on developer portal) redirect_uri with the authorization code, id_token and state value.
Step 3: Exchange authorization code for access token
Please use the received authorization code to generate an oauth 2 access token, also known as bearer token and refresh token. You can only use this code once in exchange for an access token.
For an extra layer of security according to financial API standards we have provided the option to supply client assertion parameters when requesting access tokens.
There are two extra fields called:
- client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
- client_assertion: <assertion_jwt>
The client assertion JWT is to be constructed using the following structure by you the TPP:
Please refer to our /token reference to get more insight. With the access token, now you can start accessing the account and payment resources.
The difference as you can see is JWT payload. Validation is again done by Metro Bank receiving this JWT by confirming the iss, sub exp and aud fields.
Refresh access token: The access token will be valid for 9 hours before it times out, if this happens you can request a new access token by supplying the refresh token that was given along with the original access token. The refresh token will be available to use for 90 days, after that the customer must once again go through the /authorize resource to verify consent.