Authentication and authorization with OAuth 2.0
Introduction
OP APIs use authentication and authorization flows based on OAuth and OpenID Connect. OAuth provides clients with "secure delegated access" to server resources on behalf of a resource owner, allowing resource owners (e.g. end users) to authorize third-party access to their resources without sharing or exposing their credentials.
Different APIs have different security needs, which is reflected in their selected method of authentication and authorization. The documentation of each API will describe the requirements in more detail.
For PSD2 auth flows, see the documentation for PSD2 APIs
Always store your API keys and secrets securely!
Roles
OAuth defines four roles:
Resource Owner
The resource owner is the user who authorizes an application to access their resources. The application's access to the user's resource is limited to the "scope" of the authorization granted (e.g. read or write access).
Client
The client is the application that wants to access the user's resources. Before it may do so, it must be authorized by the user, and the authorization must be validated by the API.
Resource Server
The resource server (Service API) hosts the protected user resources.
Authorization Server
The authorization server (Authorization API) verifies the identity of the user then issues access tokens to the application.
Tokens
Depending on the grant type and the position of access flow, authorization endpoints respond with slightly different tokens.
A typical token response contains these fields:
Field | Explanation |
token_type | Type of the token (bearer, refresh, etc) |
access_token | Requested access token |
scope | Defines the amount of access granted to this access token |
status | Token status (approved, rejected, pending, etc.) |
refresh_token | Token for refreshing access token |
refresh_token_expires_in | Validity period for refresh token (in seconds) |
refresh_token_issued_at | Issue time (in seconds since epoch) |
expires_in | Validity period for access token (in seconds) |
refresh_count | Number of times access token has been refreshed |
Grant types
Authorization Code Grant
The Authorization Code Grant is used when an application needs to access resources owned by an end user. The flow implements strong user authentication and lets customers authorize TPP applications to access protected customer data.
The Authorization Code Grant is used with APIs whose security rating is Substantial.
Please note that each API making use of the Authorization Code Grant may require additional parameters or procedures before granting access to the API. These requirements will always be described together with the API in question.
Client Credentials Grant
The OAuth Client Credentials grant is used when an application wants to access resources it owns, and which do not require acting on behalf of a user.
In our context, the Client Credentials grant is used as a means of identifying third parties in cases where strong end user identification is not required, and/or where end user consent is handled separately from the actual API interaction.
In practice, the client credentials grant is implemented by a token endpoint which returns an access token corresponding to the supplied API key and secret. Some APIs require extra attributes during token requests. For more information see corresponding API documentation.