Tutorial

How this authorization process works

1. A TPP requests an ABN AMRO client's consent and an authorization code for the client.
   1. The TPP sends their client_id and scope to authorization server.
   2. The authorization server redirects the ABN AMRO client to the consent application.
   3. The ABN AMRO client provides consent by supplying their account details and pin.
   4. The Authorization server supplies an authorization code to TPP.
2. The TPP sends the authorization code to the authorization server and requests an access token. They authenticate themselves using mutual TLS and provide a public key, private key, and certificate chain.
3. The authorization server authenticates the TPP and sends them an access token and a refresh token. This access token is used when calling APIs on the ABN AMRO API gateway.
4. When the access token expires, a new access token is requested by exchanging the refresh token for a new access token and a refresh token. An access token is valid for 1 hour and a refresh token is valid for 180 days.

Mutual TLS (TLSMA)

This authorization method uses mutual TLS to authenticate the consumer based on an x.509 certificate. The consumer must send a public key, private key, and certificate chain in the request to prove their identity.

In Mutual TLS, the server authenticates using a server certificate. The consumer must send a certificate to verify their identity. The consumer is configured to accept one certificate for authentication which is used to set up TLS-MA.

In the TLSMA process, a verification check is performed on the issuer DN and the subject DN of certificate. Expired certificates can be renewed without updating the configuration of your client.

The TPP must use TLS version TLS v1.1 or higher.

Important: When renewing a certificate, SubjectDN must be the same as the value used in the previous request. The certificate must also be signed by an ABN AMRO Approved CA.

Development Guidelines

To prevent false positives and the blocking of legitimate traffic, Akamai developed some guidelines and standards to detect the bot requests

Why: Akamai is able to detect automated processes connected to your application. If we do not know what they are, Akamai can start blocking this traffic.

If you are using traffic that potentially can trigger bot detection, please contact the Network Security Services team by sending an email to nss@nl.abnamro.com so we can discuss alternatives.

What: Use standardized HTTP headers, so Akamai can whitelist this bot detection. How to mitigate: Set the following user-agent header while requesting Token.

• User-Agent: Anything that is specific (no development tools etc)
• from: contact email address

Approved certificate authorities

Certificates used in authorization process must be signed by an ABN AMRO approved Certificate Authority (CA). Certificate authorities that are not in the list of supported certificate authorities will not be accepted. If your certificate authority is not in the list, see Support

Note: To add a new certificate authority, a minimum of 3 to 4 weeks is required to complete the approval procedure.

CA list

To view the most recent list of approved CAs, execute the following command:

    openssl s_client -connect auth-mtls-trustedcerts.abnamro.com:443 -servername auth-mtls-trustedcerts.abnamro.com

Check if your CA is approved

To check if your CA is ABN AMRO approved, execute the following cURL sample using the attributes below.

• certificate - application certificate location
• private_key - private key location
• cacert - ca certificate chain location

    curl -X GET \
    https://auth-mtls.abnamro.com/.well-known/openid-configuration \
    --cert ./certificatefile.crt \
    --key ./private_key.key \
    --cacert ./ca_certificate_chain.pem

If authentication is successful, you will receive a 200 - OK as HTTP Status code with response body with "Not found" message. This indicates that the attempt for mutual authentication is successful and that the issuer (cacert) has been accepted by us.

Requirements

To use this authorization process, you must have:

• An account and an application in the ABN AMRO Developer Portal. For more information, go to Basics and complete step 2 and 3.
• An approved certificate. For more information, see Approved certificate authorities.

How to use this API

Note: This process uses the Postman API Client.

Step 1 - Configure Postman

1. Open Postman.
2. In the top left of the screen, click File > Settings > Certificates > Add Certificate.
3. In the Hostname field, enter https://auth-mtls.abnamro.com and the port number as: 443.
4. In the CRT file field, click Select File and add your CRT file.
5. In the KEY file field, click Select File and add your KEY file.

   Optionally: If you import a p12 or pfx file, you do not need to complete the above 2 steps.

6. In the Passphrase field, passphrase of the KEY file.
7. Click on a request, then click Authorization.
8. In the Type dropdown field, select Inherit auth from the parent.

Step 2 - Obtain client consent

This step involves sending your client_id and scope to the authorization server. The authorization server redirects the ABN AMRO client to the consent application, where they are asked to provide their account details and pin. In the response, you will receive an authorization code.

To request an ABN AMRO client's consent and an authorization code for the client, see the requestAuthCode operation.

Step 3 - Exchange an authorization code for an access and a refresh token

Mutual TLS is used in this step, you must provide a public key, private key, and certificate chain. For more information, see Mutual TLS(TLSMA).

Important: An access token is valid for 1 hour. A refresh token is valid for 180 days.

To send your authorization code to the authorization server and request an access and a refresh token, go to the requestAccessToken operation, and select the accessToken One of parameter.

Step 4 - Use your refresh token to obtain a new access and refresh token

Mutual TLS is used in this step, you must provide a public key, private key, and certificate chain. For more information, see Mutual TLS(TLSMA).

An access token is valid for 1 hour. When it expires, the refresh token is used to obtain an access and a refresh token. To exchange your refresh token for an new access and refresh token, go to the requestAccessToken operation and select the accessAndRefreshToken One of parameter.