Made some changes to the strongly typed clients

Author: Erwinvandervalk

access-token-management/samples/Web/Startup.cs

@@ -79,7 +79,7 @@ internal static WebApplication ConfigureServices(this WebApplicationBuilder buil
         builder.Services.AddOpenIdConnectAccessTokenManagement(options =>
         {
             var useDPoP = builder.Configuration.GetValue<bool>("UseDPoP");
-            options.DPoPJsonWebKey = useDPoP ? ProofKeyString.ParseOrDefault(jwk) : null;
+            options.DPoPJsonWebKey = useDPoP ? DPoPProofKey.ParseOrDefault(jwk) : null;
         });
 
         // registers HTTP client that uses the managed user access token

access-token-management/samples/WebJarJwt/ClientAssertionService.cs

@@ -37,7 +37,7 @@ public class ClientAssertionService : IClientAssertionService
     public ClientAssertionService(
         IOpenIdConnectConfigurationService configurationService) => _configurationService = configurationService;
 
-    public async Task<ClientAssertion?> GetClientAssertionAsync(ClientName? clientName = null,
+    public async Task<ClientAssertion?> GetClientAssertionAsync(TokenClientName? clientName = null,
         TokenRequestParameters? parameters = null,
         CancellationToken ct = default)
     {

access-token-management/samples/Worker/ClientAssertionService.cs

@@ -31,7 +31,7 @@ public class ClientAssertionService(IOptionsMonitor<ClientCredentialsClient> opt
 
     private static SigningCredentials Credential = new(new JsonWebKey(RsaKey), "RS256");
 
-    public Task<ClientAssertion?> GetClientAssertionAsync(ClientName? clientName, TokenRequestParameters? parameters = null, CancellationToken ct = default)
+    public Task<ClientAssertion?> GetClientAssertionAsync(TokenClientName? clientName, TokenRequestParameters? parameters = null, CancellationToken ct = default)
     {
         if (clientName == "demo.jwt")
         {

access-token-management/samples/WorkerDI/ClientAssertionService.cs

@@ -31,7 +31,7 @@ public class ClientAssertionService(IOptionsMonitor<ClientCredentialsClient> opt
 
     private static SigningCredentials Credential = new(new JsonWebKey(RsaKey), "RS256");
 
-    public Task<ClientAssertion?> GetClientAssertionAsync(ClientName? clientName = null, TokenRequestParameters? parameters = null, CancellationToken ct = default)
+    public Task<ClientAssertion?> GetClientAssertionAsync(TokenClientName? clientName = null, TokenRequestParameters? parameters = null, CancellationToken ct = default)
     {
         if (clientName == "demo.jwt")
         {

access-token-management/src/AccessTokenManagement.OpenIdConnect/AccessTokenManagement.OpenIdConnect.csproj

@@ -18,4 +18,8 @@
   <ItemGroup>
     <ProjectReference Include="..\AccessTokenManagement\AccessTokenManagement.csproj" />
   </ItemGroup>
+  <ItemGroup>
+    <InternalsVisibleTo Include="AccessTokenManagement.Tests,PublicKey=00240000048000009400000006020000002400005253413100040000010001002f25809ad9fde9869a3ae4558b897c8a23458393921395b9439e03d6a52afadbf6ff65ef1049cd2ee4ca5501976ad45b453dc3780b8fa7eb39bae755163ef92d53403a0da484b79d24de1bb759eedceb1e13416c734d9c48b226fcd26c18e0a525b68cdba9f2395502d7df5a6d45c2478edd52752511e2924ea209f83aaa23a1" />
+  </ItemGroup>
+
 </Project>

access-token-management/src/AccessTokenManagement.OpenIdConnect/HttpContextExtensions.cs

@@ -85,8 +85,8 @@ public static async Task<TokenResult<ClientCredentialsToken>> GetClientAccessTok
     }
 
     const string AuthenticationPropertiesDPoPKey = ".Token.dpop_proof_key";
-    internal static void SetProofKey(this AuthenticationProperties properties, ProofKeyString keyString) => properties.Items[AuthenticationPropertiesDPoPKey] = keyString.ToString();
-    internal static ProofKeyString? GetProofKey(this AuthenticationProperties properties)
+    internal static void SetProofKey(this AuthenticationProperties properties, DPoPProofKey dpopProofKey) => properties.Items[AuthenticationPropertiesDPoPKey] = dpopProofKey.ToString();
+    internal static DPoPProofKey? GetProofKey(this AuthenticationProperties properties)
     {
         if (properties.Items.TryGetValue(AuthenticationPropertiesDPoPKey, out var key))
         {
@@ -95,18 +95,18 @@ public static async Task<TokenResult<ClientCredentialsToken>> GetClientAccessTok
                 return null;
             }
 
-            return ProofKeyString.Parse(key);
+            return DPoPProofKey.Parse(key);
         }
         return null;
     }
 
     const string HttpContextDPoPKey = "dpop_proof_key";
-    internal static void SetCodeExchangeDPoPKey(this HttpContext context, ProofKeyString keyString) => context.Items[HttpContextDPoPKey] = keyString;
-    internal static ProofKeyString? GetCodeExchangeDPoPKey(this HttpContext context)
+    internal static void SetCodeExchangeDPoPKey(this HttpContext context, DPoPProofKey dpopProofKey) => context.Items[HttpContextDPoPKey] = dpopProofKey;
+    internal static DPoPProofKey? GetCodeExchangeDPoPKey(this HttpContext context)
     {
         if (context.Items.TryGetValue(HttpContextDPoPKey, out var item))
         {
-            return item as ProofKeyString?;
+            return item as DPoPProofKey?;
         }
         return null;
     }

access-token-management/src/AccessTokenManagement.OpenIdConnect/Internal/AuthorizationServerDPoPHandler.cs

@@ -111,7 +111,7 @@ await dPoPNonceStore.StoreNonceAsync(new DPoPNonceContext
     /// <summary>
     /// Creates a DPoP proof token and attaches it to a request.
     /// </summary>
-    internal async Task SetDPoPProofTokenForCodeExchangeAsync(HttpRequestMessage request, DPoPNonce? dpopNonce = null, ProofKeyString? jwk = null)
+    internal async Task SetDPoPProofTokenForCodeExchangeAsync(HttpRequestMessage request, DPoPNonce? dpopNonce = null, DPoPProofKey? jwk = null)
     {
         if (jwk == null)
         {
@@ -124,7 +124,7 @@ internal async Task SetDPoPProofTokenForCodeExchangeAsync(HttpRequestMessage req
         {
             Url = request.GetDPoPUrl(),
             Method = request.Method,
-            ProofKey = jwk.Value,
+            DPoPProofKey = jwk.Value,
             DPoPNonce = dpopNonce,
         });
 

access-token-management/src/AccessTokenManagement.OpenIdConnect/Internal/OpenIdConnectUserTokenEndpoint.cs

@@ -84,14 +84,14 @@ public async Task<TokenResult<UserToken>> RefreshAccessTokenAsync(
             }
         }
 
-        var dPoPJsonWebKey = refreshToken.DPoPJsonWebKey;
+        var dPoPJsonWebKey = refreshToken.DPoPProofKey;
         if (dPoPJsonWebKey != null)
         {
             var proof = await dPoPProofService.CreateProofTokenAsync(new DPoPProof
             {
                 Url = tokenEndpoint,
                 Method = HttpMethod.Post,
-                ProofKey = dPoPJsonWebKey.Value,
+                DPoPProofKey = dPoPJsonWebKey.Value,
             }, ct);
 
             request.DPoPProofToken = proof;
@@ -112,7 +112,7 @@ public async Task<TokenResult<UserToken>> RefreshAccessTokenAsync(
             {
                 Url = tokenEndpoint,
                 Method = HttpMethod.Post,
-                ProofKey = dPoPJsonWebKey.Value,
+                DPoPProofKey = dPoPJsonWebKey.Value,
                 DPoPNonce = DPoPNonce.ParseOrDefault(response.DPoPNonce)
             };
             var proof = await dPoPProofService.CreateProofTokenAsync(dPoPProofRequest, ct);
@@ -136,8 +136,8 @@ public async Task<TokenResult<UserToken>> RefreshAccessTokenAsync(
         metrics.TokenRetrieved(request.ClientId, AccessTokenManagementMetrics.TokenRequestType.User);
         var token = new UserToken()
         {
-            IdentityToken = IdentityTokenString.ParseOrDefault(response.IdentityToken),
-            AccessToken = AccessTokenString.Parse(response.AccessToken ??
+            IdentityToken = IdentityToken.ParseOrDefault(response.IdentityToken),
+            AccessToken = AccessToken.Parse(response.AccessToken ??
                                                   throw new InvalidOperationException("No access token present")),
             AccessTokenType = AccessTokenType.ParseOrDefault(response.TokenType),
             DPoPJsonWebKey = dPoPJsonWebKey,
@@ -146,7 +146,7 @@ public async Task<TokenResult<UserToken>> RefreshAccessTokenAsync(
                 : DateTimeOffset.UtcNow.AddSeconds(response.ExpiresIn),
             RefreshToken = response.RefreshToken == null
                 ? refreshToken.RefreshToken // use input refresh token if none is returned
-                : RefreshTokenString.Parse(response.RefreshToken),
+                : RefreshToken.Parse(response.RefreshToken),
             Scope = Scope.ParseOrDefault(response.Scope),
             ClientId = oidc.ClientId
         };

access-token-management/src/AccessTokenManagement.OpenIdConnect/Internal/StoreTokensInAuthenticationProperties.cs

@@ -81,8 +81,8 @@ public TokenResult<TokenForParameters> GetUserToken(AuthenticationProperties aut
         var refreshToken = refreshTokenValue == null
             ? null
             : new UserRefreshToken(
-                RefreshTokenString.Parse(refreshTokenValue),
-                ProofKeyString.ParseOrDefault(dpopKey));
+                RefreshToken.Parse(refreshTokenValue),
+                DPoPProofKey.ParseOrDefault(dpopKey));
 
         if (accessTokenValue == null && refreshToken != null)
         {
@@ -91,13 +91,13 @@ public TokenResult<TokenForParameters> GetUserToken(AuthenticationProperties aut
 
         var userToken = new UserToken
         {
-            AccessToken = AccessTokenString.Parse(accessTokenValue ?? throw new NullReferenceException("access_token should not be null here.")),
+            AccessToken = AccessToken.Parse(accessTokenValue ?? throw new NullReferenceException("access_token should not be null here.")),
             AccessTokenType = AccessTokenType.ParseOrDefault(accessTokenType),
-            DPoPJsonWebKey = ProofKeyString.ParseOrDefault(dpopKey),
+            DPoPJsonWebKey = DPoPProofKey.ParseOrDefault(dpopKey),
             RefreshToken = refreshToken?.RefreshToken,
             Expiration = dtExpires,
             ClientId = ClientId.Parse(clientId ?? "unknown"),
-            IdentityToken = IdentityTokenString.ParseOrDefault(identityTokenValue),
+            IdentityToken = IdentityToken.ParseOrDefault(identityTokenValue),
         };
         return new TokenForParameters(userToken, refreshToken);
     }

access-token-management/src/AccessTokenManagement.OpenIdConnect/ServiceCollectionExtensions.cs

@@ -110,7 +110,7 @@ public static IHttpClientBuilder AddUserAccessTokenHttpClient<T>(this IServiceCo
     /// Adds a named HTTP client for the factory that automatically sends the current user access token
     /// </summary>
     /// <param name="services">The <see cref="IServiceCollection"/>.</param>
-    /// <param name="name">The name of the client.</param>
+    /// <param name="name">The name of the http client.</param>
     /// <param name="parameters"></param>
     /// <param name="configureClient">Additional configuration with service provider instance.</param>
     /// <returns></returns>

access-token-management/src/AccessTokenManagement.OpenIdConnect/TokenForParameters.cs

@@ -5,22 +5,51 @@
 
 namespace Duende.AccessTokenManagement.OpenIdConnect;
 
+/// <summary>
+/// Represents the result when asking for a token for a specific set of parameters, such
+/// as scope, resource and possibly others. 
+///
+/// You'll get either an UserToken with an optional UserRefreshToken, or a UserRefreshToken.
+///
+/// It's not possible to get back an optional user token and no refresh token, because that
+/// would be a failure. 
+/// 
+/// If you get back only a UserRefreshToken, it means that the token for the specified parameters was not found
+/// in the cache and you'll need the refresh token to acquire it. 
+/// 
+/// </summary>
 public sealed record TokenForParameters
 {
+    /// <summary>
+    /// A token has been found for the specified parameters. If the user has a refresh token,
+    /// that's also included. 
+    /// </summary>
     public TokenForParameters(UserToken tokenForSpecifiedParameters, UserRefreshToken? refreshToken)
     {
         TokenForSpecifiedParameters = tokenForSpecifiedParameters;
         RefreshToken = refreshToken;
         NoRefreshToken = refreshToken == null;
     }
 
+    /// <summary>
+    /// No token has been found for the specified parameters. The refresh token can be used
+    /// to get one. 
+    /// </summary>
+    /// <param name="refreshToken"></param>
     public TokenForParameters(UserRefreshToken refreshToken)
     {
         RefreshToken = refreshToken;
         NoRefreshToken = false;
     }
 
+    /// <summary>
+    /// The token for the specified parameters. This is the token that was found in the cache.
+    /// </summary>
     public UserToken? TokenForSpecifiedParameters { get; }
+
+    /// <summary>
+    /// The user's refresh token. 
+    /// </summary>
     public UserRefreshToken? RefreshToken { get; }
 
     [MemberNotNullWhen(true, nameof(TokenForSpecifiedParameters))]

access-token-management/src/AccessTokenManagement.OpenIdConnect/UserRefreshToken.cs

@@ -6,4 +6,9 @@
 
 namespace Duende.AccessTokenManagement.OpenIdConnect;
 
-public sealed record UserRefreshToken(RefreshTokenString RefreshToken, ProofKeyString? DPoPJsonWebKey);
+/// <summary>
+/// A record that captures the information to refresh an access token for a user.
+///
+/// Minimally, you need a refresh token. If you use dpop, you'll also need the dpop proof key
+/// </summary>
+public sealed record UserRefreshToken(RefreshToken RefreshToken, DPoPProofKey? DPoPProofKey);

access-token-management/src/AccessTokenManagement.OpenIdConnect/UserToken.cs

@@ -6,26 +6,49 @@
 
 namespace Duende.AccessTokenManagement.OpenIdConnect;
 
+/// <summary>
+/// A token that's tied to a speficic user. It likely contains claims like
+/// sub.
+/// </summary>
 public sealed record UserToken : AccessTokenRequestHandler.IToken
 {
-    public required AccessTokenString AccessToken { get; init; }
+    /// <summary>
+    /// The access token that was requested. 
+    /// </summary>
+    public required AccessToken AccessToken { get; init; }
 
-    public ProofKeyString? DPoPJsonWebKey { get; init; }
+    public DPoPProofKey? DPoPJsonWebKey { get; init; }
 
+    /// <summary>
+    /// Indicates when the token expires. If no expiration is used,
+    /// this value is set to DateTimeOffset.MaxValue.
+    /// </summary>
     public required DateTimeOffset Expiration { get; init; }
 
+    /// <summary>
+    /// The scope that was assigned to the token when requesting it. 
+    /// </summary>
     public Scope? Scope { get; init; }
 
+    /// <summary>
+    /// The OIDC Client that was used to acquire the token. This is not the same as the client that was used to acquire the
+    /// </summary>
     public required ClientId ClientId { get; init; }
 
+    /// <summary>
+    /// The type of access token. Typically maps to Bearer or DPoP.
+    /// </summary>
     public required AccessTokenType? AccessTokenType { get; init; }
 
-    public required RefreshTokenString? RefreshToken { get; init; }
+    /// <summary>
+    /// The refresh token that the user may have if offline access was requested. 
+    /// </summary>
+    public required RefreshToken? RefreshToken { get; init; }
 
     /// <summary>
     /// The identity token that may be populated by the OP when refreshing the access token. This
     /// value is not stored, but available should some OP's require to send this value, for example
     /// during logout.
     /// </summary>
-    public required IdentityTokenString? IdentityToken { get; init; }
+    public required IdentityToken? IdentityToken { get; init; }
 }

access-token-management/src/AccessTokenManagement.OpenIdConnect/UserTokenManagementOptions.cs

@@ -50,5 +50,5 @@ public sealed class UserTokenManagementOptions
     /// <summary>
     /// The string representation of the JSON web key to use for DPoP.
     /// </summary>
-    public ProofKeyString? DPoPJsonWebKey { get; set; }
+    public DPoPProofKey? DPoPJsonWebKey { get; set; }
 }

access-token-management/src/AccessTokenManagement/AccessToken.cs

@@ -0,0 +1,40 @@
+// Copyright (c) Duende Software. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Duende.AccessTokenManagement.Internal;
+
+namespace Duende.AccessTokenManagement;
+
+/// <summary>
+/// Strongly typed representation of an access token. This can be a Client Credentials or User token.
+/// </summary>
+[JsonConverter(typeof(StringValueJsonConverter<AccessToken>))]
+public readonly record struct AccessToken : IStronglyTypedValue<AccessToken>
+{
+    public override string ToString() => Value;
+
+    // Officially, there's no max length for JWTs, but 32k is a good limit
+    public const int MaxLength = 32 * 1024; // 32k
+
+    private static readonly ValidationRule<string>[] Validators = [
+        ValidationRules.MaxLength(MaxLength)
+    ];
+
+    public static implicit operator AccessToken(string value) => Parse(value);
+    public static implicit operator string (AccessToken value) => value.ToString();
+
+    public AccessToken() => throw new InvalidOperationException("Can't create null value");
+    private AccessToken(string value) => Value = value;
+
+    private string Value { get; }
+
+    public static bool TryParse(string value, [NotNullWhen(true)] out AccessToken? parsed, out string[] errors) =>
+        IStronglyTypedValue<AccessToken>.TryBuildValidatedObject(value, Validators, out parsed, out errors);
+
+
+    static AccessToken IStronglyTypedValue<AccessToken>.Create(string result) => new(result);
+
+    public static AccessToken Parse(string value) => StringParsers<AccessToken>.Parse(value);
+}

access-token-management/src/AccessTokenManagement/AccessTokenRequestHandler.cs

@@ -94,12 +94,12 @@ Task<TokenResult<IToken>> GetTokenAsync(
     /// </summary>
     public interface IToken
     {
-        AccessTokenString AccessToken { get; }
+        AccessToken AccessToken { get; }
 
         /// <summary>
         /// The string representation of the JSON web key to use for DPoP.
         /// </summary>
-        ProofKeyString? DPoPJsonWebKey { get; }
+        DPoPProofKey? DPoPJsonWebKey { get; }
 
         /// <summary>
         /// The Client id that this token was originally requested for.