Refresh token-based authentication workflow

To access the BSN.cloud APIs you are required to submit your credentials in order to obtain your access and refresh tokens. Access tokens are temporary credentials that grant access to a protected resource, while refresh tokens are used to obtain new access tokens when the current ones expire.

When your application or script accesses the token endpoint and authorizes successfully, it is granted an access token and a refresh token. The access token is then passed with each API request to allow the resource to be accessed.

After a period of time (the access token lifetime), making the API call will fail with an error because the access token has expired. At this point, your code should use the refresh token to exchange for a new access token. This is done by passing the refresh token to the token endpoint, which verifies the refresh token and issues new access and refresh tokens in the response. You should then use this new access token in your subsequent API call.

This process continues until either:

• the refresh token is expired

• the refresh token is revoked

• the current session is expired

At this point you will need to re-authenticate with your credentials.

The following flow diagram shows this flow:

Open

1. The client application authenticates with the BSN.cloud token endpoint by providing the credentials

2. If the credentials are valid, an access token and a refresh token are returned in the result

3. The client application makes an API call and must pass the access token

4. The API component validates the access token and allows access to the resource

5. Steps 3 and 4 can continue until the access token expires and the API signals this by returning an error response (this will be a 401 or 403 status code)

6. When the access token expires, the client application requests a new access token by providing the refresh token

7. The BSN.cloud token endpoint then issues a new access token and a new refresh token

8. Steps 3 through 7 repeat until the refresh token expires, or is revoked, or the current session ends

9. The client needs to re-authenticate with the authentication server once again and the flow repeats from step 1.

Refresh Tokens

So, why do we need both access tokens and refresh tokens? Why don’t we just set a long expiration date, like a month or a year for the access tokens? If we do that and someone manages to get hold of our access token they can use it for a long period, even if we change our password

The idea of refresh tokens is that we can make the access token short-lived so that, even if it is compromised, the attacker gets access only for a short period. With refresh token-based flow, the authentication server issues a one-time use refresh token along with the access token. Your application should store the refresh token safely

Every time your application sends a request to the server it sends the access token in the Authorization header and the server can identify the application using it. When the access token expires, the server will send a token expired response. When your application receives the token expired response, it must send the refresh token to obtain a new access token and refresh token

If something goes wrong, the refresh token can be revoked which means that when the your application tries to use it to get a new access token, that request will be rejected and you will have to enter the credentials once again and authenticate.

Why can’t we just use Steps 1, 2 and 3 constantly instead of having to deal with refresh tokens? Issuing many active access tokens is not an efficient process and it leads to an increase in storage and decrease in performance for our backend servers. Up until now we have permitted this approach but going forward we will be adding limitations to the number of unexpired access tokens that an application can have at any one time.