DPoP

DPoP (Demonstrating Proof of Possession at the Application Layer) is an effective mechanism that protects against theft of Access tokens.

Background

Securing resources, such as a REST API, with OAuth 2.0 has traditionally been achieved using bearer tokens. A bearer token is a type of token that can be used by whoever possesses it.Specifically, the use of a bearer token does not require the user to provide cryptographic proof of legitimacy.

As a result, token theft is the single biggest threat to token-based authentication. DPoP addresses this issue by ensuring that only the rightful recipient of an Access token can use this token with an API.

Functionality

DPoP works by the client having access to a secret (a private key) that must be used both in requests to the Token endpoint in HelseID to retrieve tokens and in calls to an API where the token provides access.

When retrieving tokens from HelseID, the client includes a DPoP proof, which in practice is a JWT signed with the client's secret. HelseID then issues an Access Token containing a new claim, cnf, which indicates which key pair was used. Later, when the client wants to call an API, they attach the Access Token but also include a new DPoP proof to demonstrate that the client has access to the same private key as before.

sequenceDiagram participant Client participant HelseID (Token endpoint) participant API Client->>HelseID (Token endpoint): Requests Access Token, includes DPoP proof HelseID (Token endpoint)->>Client: Invalid Request, nonce is also required Client->>HelseID (Token endpoint): Requests Access Token, includes DPoP proof with nonce HelseID (Token endpoint)->>Client: Access Token with cnf claim Client->>API: Calls API, includes Access Token and DPoP proof API->>API: Verifies DPoP proof against cnf claim in Access Token API->>Client: API call result

Detailed Description of DPoP Calls to the Token endpoint

When you are requesting a DPoP token from the Token endpoint, several requirements must be met.

Securing the Private Key

The private key used for signing the DPoP proof must be secured in the same way as the private key used for client authentication. This is described in the security profile document Use of Client Secrets.

In the context of HelseID, you can secure a DPoP proof in two different ways:

you can use the same private key that you use to sign the client assertion for client authentication or
you can generate new key pairs as needed

Accepted signing algorithms are detailed in the security profile document Requirements for Cryptography.

Formatting a DPoP Proof

The DPoP proof must be formatted in a specific manner; this is described in the security profile: Formatting DPoP proofs.

Use of Nonce

HelseID requires the client to make two calls to the token endpoint to acquire a DPoP token. On the first call, HelseID will respond with an HTTP 400 error code and the message use_dpop_nonce. A header named DPoP-Nonce will be included, containing a randomly generated value. This value must be incorporated into a new DPoP proof, which is then submitted in a second call to HelseID. A more detailed description of this functionality can be found in this section of the specification.

Requirements for API's Verification of DPoP Proofs

For all of this to be meaningful, the API validating the DPoP token must also validate the accompanying DPoP proof. This process is described in the security profile: Validating DPoP proofs.