This article describes the principles of OAuth 2.0 and how to configure OAuth 2.0 in Smart ID Digital Access component.

The purpose of OAuth 2.0 is to give applications limited and secure access to an HTTP resource on behalf of an end-user without exposing that user’s credentials to the application or the user’s device. OAuth 2.0 offers a way to limit what a specific client can access through “scopes”.

The most common scenario in OAuth 2.0 is accessing a protected resource on the resource server by providing an access token. There are multiple ways to provide the token, and the preferred way is to include it in the authorization header of the request. The resource server validates the token and lets the client through if the token is valid for the resource being requested.

OAuth 2.0 requires a database in order to store codes and tokens. The Digital Access component appliance bundles a preconfigured PostgreSQL database with a predefined “oauth” user. It is also possible to configure an external database if needed. This is mandatory for systems running in distributed mode since the different nodes are sharing the OAuth 2.0 database configuration.

The REST-based administration web service makes it possible to configure parts of Digital Access component without using the graphical user interface. This is very useful if parts of the configuration needs to be done automated or when using Nexus PRIME as main frontend. See Enable OAuth 2.0 authorization for Digital Access administration web service

Terms

These are terms that are used in this article.

Authorization server

The authorization server issues access tokens to the client after the resource owner has been authenticated and has authorized the client to access the requested resource scopes.
In Digital Access component, this is the Policy Service (protected by and accessed through the Access Point), which exposes its services through two REST endpoints; /authorize and /token.

Resource server

A resource server is an entity that stores a protected resource.
In Digital Access component, this is the Access Point, even though it does not actually store any resource. As a reverse proxy it can seamlessly extend any resource with OAuth 2.0 access token validation without the resource needing any knowledge of OAuth 2.0.

Resource owner

A resource owner is an entity that owns a specific resource (data) and is capable of granting a client access to that resource.
In Digital Access component this is a user. Can also be referred to as an ‘end-user’.

Client

A client is an application that wants to access a protected resource on behalf of a resource owner. There are two types of clients in OAuth 2.0, confidential clients and public clients.
A confidential client is a client that can keep a secret (for example, an application executing on a secure server)
A public client is a client that cannot keep a secret (for example, a mobile device or web app).
In order to get access to the resource the client must first obtain a token through one of the token grant flows. A token gives access to a specific set of scopes that must be defined before registering a client.

Scope

A scope refers to a collection of one or more resources that are protected by OAuth 2.0.

Access token

An access token is issued to a client in order to allow that client to access one or more scopes on behalf of a specific resource owner.

Grant types

A grant type is a way to obtain an access token.

General grant flow

This is the general grant flow:

The client redirects the resource owner to the authorization server with a request for a specific set of scopes.
The authorization server authenticates the client and the resource owner.
The resource owner consents to the client accessing the requested scopes.
The authorization server creates an access token and redirects the resource owner back to the client together with the token.

Authorization code

The authorization code grant type is the preferred way to obtain access tokens (and refresh tokens) with a confidential client. Other grant types should only be considered for public clients or when the added level of security is redundant (for example, when the client is a secure server on the same network).

These are the steps in the authorization code grant flow:

The client redirects the resource owner to the authorization server’s /authorize endpoint, providing client identification and the set of scopes that the client wants to get access to.
The authorization server identifies the client and ensures that the client is allowed to access the requested scopes.
The authorization server authenticates the resource owner if the user does not already have an authenticated session.
The authorization server presents the resource owner with the requested scopes and asks for consent.
The resource owner is redirected back to the client. If consent was given, an access code is included in the URL.
The client extracts the code from the URL and makes a request to the /token endpoint on the authorization server, providing the extracted code.
The authorization server authenticates the client, validates the code, and returns an access token (and refresh token) to the client.

Implicit

The implicit grant type is intended for public clients. Refresh tokens are never issued when using this grant type. Specifically, this grant type is intended to be used by clients executing in the resource owner’s browser and is the only one which does not authenticate the client. This grant type should only be used if other grant types are unavailable. Impersonating a client that has this grant type enabled is as easy as knowing their client ID. The authenticity of the client is left (almost) entirely to the resource owner’s discretion.

These are the steps in the implicit grant flow:

The client redirects the resource owner to the authorization server’s /authorize endpoint, providing the set of scopes that the client wants to get access to.
The authorization server authenticates the resource owner and ensures that the client is allowed to access the requested scopes.
The authorization server presents the resource owner with the requested scopes and asks for consent.
The resource owner is redirected back to the client. If consent was given, an access token is included in the URL.

Resource owner password credentials

The resource owner password credentials grant type is intended for confidential clients with a high degree of trust from the resource owner. The strength of not needing to provide the client with the resource owner’s credentials is lost by using this grant type. This grant type is used to eliminate the need for the client to store the resource owner’s credentials by exchanging them for a long-lived token. It is suited for clients such as a device’s operating system which may have access to the resource owner’s credentials anyway, or is trusted to not misuse or unintentionally expose the resource owner’s credentials.

These are the steps in the resource owner password credentials grant flow:

The client obtains the resource owner’s username and password.
The client sends a request to the authorization server’s /token endpoint, providing the resource owner’s username and password and the set of scopes that the client wants to get access to.
The authorization server authenticates the client and resource owner and ensures that the client is allowed to access the requested scopes.
The authorization server returns an access token (and refresh token) to the client.

Client credentials

The client credentials grant type is intended for confidential clients that do not act on behalf of a resource owner. In other words, this grant type is used when accessing resources not owned by a user.

These are the steps in the client credentials grant flow:

The client sends a request to the authorization server’s /token endpoint, providing the set of scopes that the client wants to get access to.
The authorization server authenticates the client and ensures that the client is allowed to access the requested scopes.
The authorization server returns an access token (and refresh token) to the client.

Refresh token

The refresh token grant type is a special grant type. When refresh tokens are enabled on the OAuth 2.0 client, other grant types (with the exception of implicit) will issue a refresh token alongside the access token. The refresh token has a longer lifetime than the access token and can be used to receive a new access token without needing to authenticate the resource owner. Since the refresh token is only sent to the client once and then isn’t exposed again until it is consumed, using refresh tokens is safer than using long-lived access tokens. Digital Access component will only issue refresh tokens to clients that are configured to have refresh tokens issued.

These are the steps in the refresh token grant flow:

The client sends a request to the authorization server’s /token endpoint, providing the refresh token.
The authorization server authenticates the client, validates the refresh token, and ensures that the client is (still) allowed to access the requested scopes.
The authorization server returns an access token (and refresh token) to the client.

Prerequisites

Prerequisites

A Digital Access component system with a configured authentication mechanism
A user with an active authentication method profile, such as Personal Mobile or a client certificate

Step-by-step instruction

Log in to Digital Access Admin

Log in to Digital Access Admin with an administrator account.

Enable OAuth 2.0

OAuth 2.0 must be enabled before it can be used:

In Digital Access Admin, go to Manage System.
Click OAuth2 Configuration > Manage Global OAuth2 Settings.
Check Enable OAuth2.
Click Save.

Add scope and client and configure OAuth 2.0 database

In Digital Access Admin, go to Manage System.
Click OAuth2 Configuration > Add scope.
Enter Name, Key and Value. Click ? for help.
Click Add description and Save.
On the Manage System > OAuth2 Configuration page, click Add client.
Enter information in the General Settings tab. Click ? for help. Click Save when done.
Enter information in the Privileges tab. Click ? for help. Click Save when done.
Enter information in the Access Rules tab. Click ? for help. Click Save when done.
On the Manage System > OAuth2 Configuration page, click Configure Database Connection.
Select a database type from the list of supported databases in the field Database. These databases have a default configuration. If you select a non supported database, settings for such a database is configured using Toggle Advanced Fields.
Enter Host and Name. Click ? for help. When you click Save, the system converts this information to the form shown in the Advanced Fields.
If a non supported database was selected, click Toggle Advanced Fields and enter Dialect, URL and Driver. For help and examples, click the ?-sign.
Enter User, Password and number of Retry Attempts.

When this page is saved it will save the information currently displayed. If the settings are saved while displaying the Standard Fields (Database, Host and Name) the information in the Standard Fields will be used, regardless of what manual changes has been made in the Advanced Fields. The same applies the other way around. If the page is saved while displaying the Advanced Fields the information in those fields will be used, regardless of what information might have been entered in the Standard Fields.

Protect a resource with OAuth 2.0

After registering a client and assigning it at least one scope, you add an access rule of the type “OAuth2 Bearer Token” to a web resource in order to protect it with OAuth 2.0. See Add access rule in Digital Access for more information.

In Digital Access Admin, go to Manage Resource Access > Access Rules and click Add Access Rule…
Enter a Display Name and click Next.
Select OAuth2 Bearer Token and click Next.
Select the client that shall get access and the scopes that shall be required. If you select multiple scopes, all of those scopes are required to access the resource. Register one access rule for every client that shall be able to access the resource.

OR

Create the access rule directly on the resource by clicking Add Access Rule… in the Access Rule section of the web resource configuration, see Web resources in Digital Access component for more information.

Revoke a token

If you revoke an access token, only that specific token is revoked. If you revoke a refresh token, all tokens related to that token are revoked.

In Digital Access Admin, go to Manage Accounts and Storage > User Accounts.
Search for the user connected to the tokens you want to revoke.
On the PortWise Authentication tab, go to the Connected Applications section, where all tokens issued to the user are listed.
To revoke a token, check Remove next to the token you wish to revoke, and click Save.

If a refresh token has been issued, the access tokens are grouped together with the refresh token. This is indicated by the Token type “Refresh, Access”.

Consent template

If you have more than one description for a scope, only the first one will be used if the default consent template is configured.

If you wish to enable branding/localization, modify wwwroot/wa/scripts/oauth2consent.js. In this file, there are descriptions of which lines you need to uncomment to enable branding/localization. When the lines are uncommented, all that is needed is to pass the correct description key to the sendRequest function. One way of doing this is having different wwwroots for different brandings/localizations and passing different keys depending on the branding/localization.

Related information

Browser not supported