identityserver-token-security

What this skill does

# Advanced Token Security (DPoP, mTLS, PAR, JAR, FAPI)

## When to Use This Skill

- Implementing Proof-of-Possession (PoP) tokens with DPoP or mTLS
- Configuring Pushed Authorization Requests (PAR) for front-channel parameter security
- Setting up JWT Secured Authorization Requests (JAR) for tamperproof authorize requests
- Building FAPI 2.0 compliant authorization servers
- Choosing between DPoP and mTLS for sender-constrained tokens
- Configuring APIs to validate proof-of-possession tokens
- Meeting regulatory or industry security requirements (open banking, e-health, e-government)

Docs: https://docs.duendesoftware.com/identityserver/tokens/security

## Proof-of-Possession Tokens: Why They Matter

Default OAuth access tokens are **bearer tokens** -- anyone who possesses the token can use it. If a token leaks, a malicious third party can impersonate the client/user.

**Proof-of-Possession (PoP) tokens** are cryptographically bound to the client that requested them via the `cnf` (confirmation) claim:

```json
{
  "iss": "https://identity.example.com",
  "aud": "urn:api",
  "client_id": "web_app",
  "sub": "88421113",
  "cnf": "confirmation_method"
}
```

When using reference tokens, the `cnf` claim is returned from the introspection endpoint.

## DPoP vs mTLS: Decision Matrix

| Factor                    | DPoP                               | mTLS                                               |
| ------------------------- | ---------------------------------- | -------------------------------------------------- |
| **Edition required**      | Enterprise                         | All editions (binding); Enterprise (some features) |
| **Minimum version**       | 6.3                                | All versions                                       |
| **Key management**        | Application-layer JWK (dynamic)    | X.509 certificate (TLS layer)                      |
| **Infrastructure**        | No TLS changes needed              | Requires TLS client certificate infrastructure     |
| **Deployment complexity** | Lower                              | Higher (certificate distribution, renewal)         |
| **Protocol layer**        | HTTP headers (`DPoP` header)       | TLS channel                                        |
| **Public clients**        | Supported (mobile/SPA)             | Harder for public clients                          |
| **FAPI 2.0**              | Accepted                           | Accepted                                           |
| **Replay protection**     | Nonce mechanism + `iat` validation | TLS channel binding                                |
| **Recommendation**        | Start here for most use cases      | When TLS infrastructure already exists             |

## Mutual TLS (mTLS)

### How It Works

IdentityServer embeds the SHA-256 thumbprint of the client's X.509 certificate into the access token via the `cnf` claim:

```json
{
  "cnf": { "x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2" }
}
```

The client must use the same certificate when calling APIs. APIs validate the `cnf` claim against the TLS client certificate thumbprint.

### mTLS for Client Authentication

Configure IdentityServer to accept client certificates:

```csharp
// Program.cs
var idsvrBuilder = builder.Services.AddIdentityServer(options =>
{
    options.MutualTls.Enabled = true;
    options.MutualTls.DomainName = "mtls"; // mTLS endpoints on mtls subdomain
    options.MutualTls.ClientCertificateAuthenticationScheme = "Certificate";
});

idsvrBuilder.AddMutualTlsSecretValidators();

builder.Services.AddAuthentication()
    .AddCertificate("Certificate", options =>
    {
        options.AllowedCertificateTypes = CertificateTypes.SelfSigned;
        options.ValidateCertificateUse = true;
    });
```

Configure the client with certificate-based secrets:

```csharp
new Client
{
    ClientId = "mtls.client",
    AllowedGrantTypes = GrantTypes.ClientCredentials,
    AllowedScopes = { "api1" },
    ClientSecrets =
    {
        // PKI-based (by distinguished name)
        new Secret(@"CN=client, OU=production, O=company", "client.dn")
        {
            Type = SecretTypes.X509CertificateName
        },
        // Self-issued (by thumbprint)
        new Secret("bca0d040847f843c5ee0fa6eb494837470155868", "mtls.tb")
        {
            Type = SecretTypes.X509CertificateThumbprint
        }
    }
}
```

### mTLS without Client Authentication

You can bind tokens to a client certificate without using the certificate for client authentication. This works with any authentication method, including public clients:

```csharp
// Program.cs
var idsvrBuilder = builder.Services.AddIdentityServer(options =>
{
    options.MutualTls.AlwaysEmitConfirmationClaim = true;
});
```

The client creates a certificate on the fly and uses it to establish the TLS channel:

```csharp
static X509Certificate2 CreateClientCertificate(string name)
{
    X500DistinguishedName distinguishedName = new X500DistinguishedName($"CN={name}");

    using (RSA rsa = RSA.Create(2048))
    {
        var request = new CertificateRequest(distinguishedName, rsa, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
        request.CertificateExtensions.Add(
            new X509KeyUsageExtension(
                X509KeyUsageFlags.DataEncipherment |
                X509KeyUsageFlags.KeyEncipherment |
                X509KeyUsageFlags.DigitalSignature, false));
        request.CertificateExtensions.Add(
            new X509EnhancedKeyUsageExtension(
                new OidCollection { new Oid("1.3.6.1.5.5.7.3.2") }, false));

        return request.CreateSelfSigned(
            new DateTimeOffset(DateTime.UtcNow.AddDays(-1)),
            new DateTimeOffset(DateTime.UtcNow.AddDays(10)));
    }
}
```

### .NET Client Requesting mTLS Token

```csharp
static async Task<TokenResponse> RequestTokenAsync()
{
    var handler = new SocketsHttpHandler();
    var cert = new X509Certificate2("client.p12", "password");
    handler.SslOptions.ClientCertificates = new X509CertificateCollection { cert };

    var client = new HttpClient(handler);

    var disco = await client.GetDiscoveryDocumentAsync(Constants.Authority);
    if (disco.IsError) throw new Exception(disco.Error);

    var response = await client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
    {
        Address = disco.MtlsEndpointAliases.TokenEndpoint,
        ClientCredentialStyle = ClientCredentialStyle.PostBody,
        ClientId = "mtls.client",
        Scope = "api1"
    });

    if (response.IsError) throw new Exception(response.Error);
    return response;
}
```

### Validating mTLS in APIs

Add custom middleware to compare the `cnf` claim against the TLS client certificate:

```csharp
// API middleware pipeline
app.UseAuthentication();
app.UseConfirmationValidation(); // custom middleware
app.UseAuthorization();
```

The middleware validates the `x5t#S256` value in the `cnf` claim against the SHA-256 thumbprint of the client certificate on the TLS channel.

## DPoP (Demonstrating Proof-of-Possession at the Application Layer)

**Version:** >= 6.3 (Enterprise Edition)

DPoP binds an asymmetric key (stored as a JWK) to an access token via the `cnf` claim:

```json
{
  "cnf": {
    "jkt": "JGSVlE73oKtQQI1dypYg8_JNat0xJjsQNyOI5oxaZf4"
  }
}
```

The client proves possession of the private key by sending a signed JWT (proof token) via the `DPoP` HTTP header on every request.

### Enabling DPoP in IdentityServer

DPoP can be used dynamically with no server configuration, or enforced per-client:

```csharp
new Client
{
    ClientId = "dpop_client",
    RequireDPoP = true,

    // Optional: control DPoP proof token expiration validation
    // DPoPValidationMode = DPoPTokenExpirationValidationMode.Iat (default)
    // DPoPClockSkew = TimeSpan.FromMinutes(5) (default)
}
```

### Client-Side DPoP Configuration

Use `Duende.AccessTokenManagement` for automatic DPoP proof token handling.

**Client credentials flow:**