MagNet NextGen PSD2 OAUTH 2 specification

1. Introduction

This document contains a detailed specification about MagNet NextGen PSD2 authentication and authorisation service.

Our authentication and authorisation layer based on Oauth 2 with some Berlin Group specialisations.

Our applied oauth 2 configuration:

- Flow: authorization code flow. (Using any other flow is forbidden!)

- Client registration is not neccessary. (We use PKCE extension instead of client registration mechanism.)

- Using of the client-id and scope attributes are defined in the Berlin Group NextGenPsd2 specifiaction. (See below.)

Basic OAUTH 2 RFC can be found here:

https://tools.ietf.org/html/rfc6749

Basic bearer (access) token usage RFC can be found here:

https://tools.ietf.org/html/rfc6750

Our detailed Oauth 2 extensions and its detailed specifications with documentation URL:

2. Using MagNet Oauth2 authentication and authorisation layer

The following steps required to obtain access (bearer) token.

1. The client first creates a random string (between 43 and 128 characters) known as „code verifier”. Then using the SHA256 algorithm it calculates the „code challenge” value.
   
   Code challenge = SHA256(code verifier)

2. The client posts an authorisation request by any of the following urls:

• {proto}://{host:port}/NetBankOAuth/psd2-authorize.xhtml?response_type=code&client_id={client-id}&scope=AIS&state={state}&redirect_uri={redirect-uri}&code_challenge_method=S256&code_challenge={code-challenge}&consent_id={consent-id}

• {proto}://{host:port}/NetBankOAuth/psd2-authorize.xhtml?response_type=code&client_id={client-id}&scope=PIS&state={state}&redirect_uri={redirect-uri}&code_challenge_method=S256&code_challenge={code-challenge}&payment_id={payment-id}

• {proto}://{host:port}/NetBankOAuth/psd2-authorize.xhtml?response_type=code&client_id={client-id}&scope=SBS&state={state}&redirect_uri={redirect-uri}&code_challenge_method=S256&code_challenge={code-challenge}&signing_basket_id={basket-id}

• {proto}://{host:port}/NetBankOAuth/psd2-authorize.xhtml?response_type=code&client_id={client-id}&scope=AIS:{consent-id}&state={state}&redirect_uri={redirect-uri}&code_challenge_method=S256&code_challenge={code-challenge}

• {proto}://{host:port}/NetBankOAuth/psd2-authorize.xhtml?response_type=code&client_id={client-id}&scope=PIS:{payment-id}&state={state}&redirect_uri={redirect-uri}&code_challenge_method=S256&code_challenge={code-challenge}

• {proto}://{host:port}/NetBankOAuth/psd2-authorize.xhtml?response_type=code&client_id={client-id}&scope=SBS:{basket-id}&state={state}&redirect_uri={redirect-uri}&code_challenge_method=S256&code_challenge={code-challenge}

3. Authorisation response:

The authorisation response of the ASPSP to the TPP will deliver the following data:

- code: authorisation code generated by ASPSP

- state: same state value as for the request

4. Token request:

The TPP send a POST request to the token endpoint in order to exchange authorisation code provided in the authorisation response.

Token request endpoint URL template:

• {proto}://{host:port}/NetBankOAuth/psd2/token?grant_type=authorisationCode&code={authorisation_code}&client_id={client_id}&redirect_uri={redirect_uri}&code_verifier={code_verifier}

• {proto}://{hosT:port}/NetBankOAuth/psd2/token
  In this case the neccessery params are to send in http body with application/x-www-form-urlencoded HTTP content type.
  
  Example:
  
  POST /token HTTP/1.1
Host: https://api.testbank.com
Content-Type: application/x-www-form-urlencoded
client_id="PSDES-BDE-3DFD21"
&grant_type=authorisationCode
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri= https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&code_verifier=7814hj4hjai87qqhjz9hahdeu9qu771367647864676787878

5. Token response:

The ASPSPS responds with the following parameters:

Example:

HTTP/1.1 200 OK

Content-Type: application/json

Cache-Control: no-store

Pragma: no-cache

{

"access_token":"SlAV32hkKG",

"token_type":"Bearer",

"expires_in":3600,

"refresh_token": "tGzv3JokF0XG5Qx2TlKWIA",

"scope": "AIS:1234"

}

You can use the access token as a bearer token authorisation. See RFC 6750.

https://tools.ietf.org/html/rfc6750

4. MagNet NetxtGen PSD2 endpoints:

The following table contains all OAUTH2 specific endpoints.