Demonstrating Proof-of-Possession (DPoP)

DPoP specifies how to bind an asymmetric key stored within a JSON Web Key (JWK) to an access token. This will make the access token bound to the key such that if the access token were to leak, it cannot be used without also having access to the private key of the corresponding JWK.

The Duende.IdentityModel.OidcClient.Extensions library adds supports for DPoP to OidcClient.

DPoP Key

Before we begin, your application needs to have a DPoP key in the form of a JSON Web Key (or JWK). According to the DPoP specification, this key needs to use an asymmetric algorithm (“RS”, “ES”, or “PS” style).

Note

The client application is responsible for creating the DPoP key, rotating it, and managing its lifetime. For as long as there are access tokens (and possibly refresh tokens) bound to a DPoP key, that key needs to remain available to the client application.

You can create a JWK in .NET using the Duende.IdentityModel.OidcClient.Extensions library. The JsonWebKeys class has several static methods to help with creating JWKs using various algorithms.

Program.cs

using Duende.IdentityModel.OidcClient.DPoP;

// Creates a JWK using the PS256 algorithm:
var jwk = JsonWebKeys.CreateRsaJson();

Console.WriteLine(jwk);

Caution

In a production scenario, you’ll want to store this JWK in a secure location and use ASP.NET’s data protection to further protect the JWK. See our data protection guide for more information.

Initializing the OIDC client with DPoP support

We will need to extend the OidcClientOptions before we can use DPoP.

After creating the OidcClientOptions to connect our client application with the Identity Provider, we retrieve a JWK to use for DPoP, and add that JWK to our options by calling the ConfigureDPoP extension method:

Program.cs

using Duende.IdentityModel.OidcClient;
using Duende.IdentityModel.OidcClient.DPoP;

var options = new OidcClientOptions
{
    Authority = "https://demo.duendesoftware.com",
    ClientId = "native.dpop",
    Scope = "openid profile email offline_access",
    // ...
};

// creates a new JWK, or returns an existing one
var jwk = GetDPoPJwk();

// Enable DPoP
options.ConfigureDPoP(jwk);

var oidcClient = new OidcClient(options);

Proof Tokens for the API

Now that we’ve configured the OidcClientOptions with DPoP support and created an OidcClient instance, you can use this instance to create an HttpMessageHandler which will:

• manage access and refresh tokens
• add DPoP proof tokens to HTTP requests

The OidcClient provides CreateDPoPHandler as a convenience method to create such a handler, which can be used with the .NET HttpClient.

Program.cs

var sessionRefreshToken = "..."; // read from a previous session, if any

var handler = oidcClient.CreateDPoPHandler(jwk, sessionRefreshToken);
var apiClient = new HttpClient(handler);

For a full example, have a look at our WPF with the system browser sample.