Reference

UseCognito

Package Trax.Api.Auth.Jwt.CognitoNamespace Trax.Api.Auth.Jwt.CognitoSource CognitoJwtBuilderExtensions.cs, CognitoTokenUse.cs, CognitoJwtPrincipalResolver.cs

NO WARRANTY. Trax auth is plumbing, not a security product. You are solely responsible for securing systems that use it. See API Security.

Extension method on JwtBuilder, declared on CognitoJwtBuilderExtensions, that configures an AddTraxJwtAuth scheme to validate tokens from an Amazon Cognito user pool. The package also ships CognitoJwtPrincipalResolver, a resolver for Cognito's claim shapes.

Signature

public static JwtBuilder UseCognito(
    this JwtBuilder builder,
    string region,
    string userPoolId,
    string clientId,
    CognitoTokenUse tokenUse = CognitoTokenUse.IdAndAccess);
 
public enum CognitoTokenUse
{
    Id,
    Access,
    IdAndAccess,
}
 
public sealed class CognitoJwtPrincipalResolver : ITraxPrincipalResolver<JwtTokenInput>
{
    public ValueTask<TraxPrincipal?> ResolveAsync(JwtTokenInput input, CancellationToken ct);
}

Parameters

ParameterTypeDescription
regionstringThe user pool's AWS region, such as us-east-1.
userPoolIdstringThe user pool id, such as us-east-1_AbCdEfGhI.
clientIdstringThe app client id. An ID token must carry it in aud, an access token in client_id.
tokenUseCognitoTokenUseWhich token shapes to accept: Id, Access, or IdAndAccess (the default).

Returns

The same JwtBuilder, for chaining.

Behavior

UseCognito calls UseAuthority("https://cognito-idp.{region}.amazonaws.com/{userPoolId}", clientId), so it cannot be combined with UseSymmetricKey or UseSigningKey on the same builder. It then calls CustomizeTokenValidation to install two validators:

  • AudienceValidator: accepts a token whose aud contains clientId when tokenUse admits ID tokens, and a token whose client_id claim is clientId when it admits access tokens. ValidAudience and ValidAudiences are not consulted.
  • LifetimeValidator: runs any lifetime validator set earlier on the builder, then checks token_use. It refuses an id token when only Access is admitted, and an access token when only Id is. Where access tokens are admitted, a token that carries client_id but no token_use is refused. A token that carries neither claim is not affected. It then checks exp, which is required, and nbf against the clock skew.

A later CustomizeTokenValidation call that assigns AudienceValidator or LifetimeValidator replaces the one UseCognito installed, and with it these checks.

A null or blank region, userPoolId or clientId throws ArgumentException.

CognitoJwtPrincipalResolver

Returns null, failing authentication, when the token has no subject.

Token claimLands on
sub, then ClaimTypes.NameIdentifierTraxPrincipal.Id
The first non-empty of name, ClaimTypes.Name, preferred_username, cognito:username, email, ClaimTypes.Email, then the idTraxPrincipal.DisplayName
cognito:groups, role, roles, ClaimTypes.RoleTraxPrincipal.Roles, without blanks or duplicates
identities: the providerName of the entry with primary true, else of the first entryClaims["identity_provider"]
No identities, or one that cannot be readClaims["identity_provider"] = "cognito"
Every other claim (token_use, email, email_verified, scopes)TraxPrincipal.Claims, the first value of each type
TraxPrincipal.PrincipalType is cognito.

A token with no email, such as Apple's after the first sign-in, still resolves: sub identifies the user.

Example

services.AddTraxJwtAuth<CognitoJwtPrincipalResolver>("cognito", jwt =>
    jwt.UseCognito(
        region: "us-east-1",
        userPoolId: "us-east-1_AbCdEfGhI",
        clientId: "mobile-app-client-id"));

See also