SAML NameID Generator
Duende.IdentityServer.Saml.Services.ISamlNameIdGenerator
Section titled “Duende.IdentityServer.Saml.Services.ISamlNameIdGenerator”Generates SAML NameID values for SSO responses. The built-in handling generates an email NameID for the email format and uses the sub claim for every other format, including persistent and transient. Register a custom implementation if a service provider needs a different value, for example a pairwise identifier for the persistent format or a session-scoped identifier for the transient format. It’s called for an assertion after the user authenticates and the NameID format is resolved.
public interface ISamlNameIdGenerator{ Task<NameIdGenerationResult> GenerateAsync(NameIdGenerationContext context, CancellationToken ct);}GenerateAsync generates a NameID for the given context.
NameIdGenerationContext
Section titled “NameIdGenerationContext”public sealed class NameIdGenerationContext{ public required ClaimsPrincipal Subject { get; init; } public required SamlServiceProvider ServiceProvider { get; init; } public required string ResolvedFormat { get; init; } public string? SPNameQualifier { get; init; }}Context provided to ISamlNameIdGenerator for NameID generation.
| Property | Description |
|---|---|
Subject | The authenticated subject. |
ServiceProvider | The SAML service provider requesting the assertion. |
ResolvedFormat | The resolved NameID format (after applying priority: request → SP default → unspecified). |
SPNameQualifier | SPNameQualifier from the AuthnRequest NameIDPolicy, if present. |
NameIdGenerationResult
Section titled “NameIdGenerationResult”public sealed class NameIdGenerationResult{ public NameId? NameId { get; } public SamlError? Error { get; } public bool IsError { get; }
public static NameIdGenerationResult Success(NameId nameId); public static NameIdGenerationResult Failure(string statusCode, string subStatusCode, string message);}Result of NameID generation, representing either a successful NameId or a SAML protocol error.
| Member | Description |
|---|---|
NameId | The generated NameID, or null if generation failed. |
Error | The error, or null if generation succeeded. |
IsError | Whether this result represents an error. |
Success | Creates a successful result. |
Failure | Creates a failure result with SAML error status codes. |
NameId (namespace Duende.IdentityServer.Saml) is the Saml NameIDType. It converts implicitly from string, which creates a NameId with the string supplied as value.
| Property | Description |
|---|---|
Value | The value, i.e. string contents of the XML node. |
Format | A URI reference representing the classification of string-based identifier information. |
SPNameQualifier | Optionally qualifies a name identifier in the namespace of a service provider or affiliation of providers. |
NameQualifier | The security or administrative domain that qualifies the name. |
Use SamlStatusCodes for the failure codes, for example SamlStatusCodes.Responder and SamlStatusCodes.UnknownPrincipal.
return Task.FromResult(NameIdGenerationResult.Failure( SamlStatusCodes.Responder, SamlStatusCodes.UnknownPrincipal, "Employee ID claim not found."));Default behavior
Section titled “Default behavior”Default implementation of ISamlNameIdGenerator that generates an email NameID for the email format and uses the sub claim for every other format.
- Email format: uses the claim type from
SamlServiceProvider.EmailNameIdClaimType, falling back toSamlOptions.EmailNameIdClaimType(defaultemail). - Every other format: uses the
subclaim and echoesResolvedFormat, including forpersistentandtransient. - On failure, the default implementation returns
Responder/InvalidNameIDPolicystatus codes with a message. The defaultISaml2SsoResponseGeneratoruses only the message: the user sees the IdentityServer error page and no SAML error response is sent to the SP.
Registration
Section titled “Registration”builder.Services.AddScoped<ISamlNameIdGenerator, CustomNameIdGenerator>();