Skip to content

Protocols

OAuth 2.0

OAuth 2.0 is an industry-standard protocol for authorization. In NAV, we use this protocol in order to acquire security tokens that can be used to secure and assert requests between applications.

The framework is extensible and has a number of associated specifications. However, we will only describe the relevant parts.

In order to obtain an access token, we need an authorization grant. The grant represents a delegated authorization. The client is granted authorization by a resource owner (such as an end user or the client itself) to access protected resources that belong to the owner.

There are multiple ways of obtaining such a grant, depending on the context of the actual use case. We'll go through the relevant ones below.

Client Credentials Grant

The client acts on its own behalf where it is also the resource owner. That is, the client owns the requested resources or has otherwise been granted access to them.

This grant is used for internal machine-to-machine requests without end users with Azure AD.

Detailed specifications in RFC 6749, Section 4.4.

JWT Authorization Grant

This grant is similar to the client credentials grant, however uses a JWT assertion to acquire the grant instead of explicitly authenticating itself.

This grant is used for external machine-to-machine requests without end users with Maskinporten.

Detailed specifications in RFC 7523, Section 2.1.

Token Exchange Grant

This grant allows a client to act on behalf of another principal, typically an end user - this is also known as delegation. In short, the grant involves exchanging the principal's token received in the request for a new token that grants access to another backend/downstream resource while still preserving the end user context.

This grant is used for machine-to-machine requests with end user context using TokenX.

Detailed specifications in RFC 8693.

On-Behalf-Of Grant

This grant is Microsoft's implementation of the Token Exchange Grant. As it was implemented before the RFC for the Token Exchange Grant was finalized, there are some minor differences in parameter names and values - however the main concepts remain the same.

This grant is used for machine-to-machine requests with end user context using Azure AD.


OpenID Connect

OpenID Connect (OIDC) is a simple identity layer on top of the OAuth 2.0 protocol. This allows for clients and applications to verify the identity and make assertions about an end user that has authenticated themselves with a trusted authorization server.

The OpenID Connect Core 1.0 specifications define a number of authentication flows. As best practice, we recommend the use of the Authorization Code Flow, especially together with the OAuth 2.0 - Proof Key for Code Exchange (PKCE) extension.

Authorization Code Flow

The Authorization Code Flow involves the following steps:

  1. Client prepares an Authentication Request containing the desired request parameters.
  2. Client sends the request to the Authorization Server.
  3. Authorization Server Authenticates the End-User.
  4. Authorization Server obtains End-User Consent/Authorization.
  5. Authorization Server sends the End-User back to the Client with an Authorization Code.
  6. Client requests a response using the Authorization Code at the Token Endpoint.
  7. Client receives a response that contains an ID Token and Access Token in the response body.
  8. Client validates the ID token and retrieves the End-User's Subject Identifier.

The client is usually implemented in a backend-for-frontend, which means the flow and session management is handled server-side.

This flow is supported by the following identity providers:

The platform provides opt-in sidecars that implement such clients:

Due to the complexity involved in implementing and maintaining such clients, we recommend that your applications use these sidecars when possible.


Further Reading