Skip to content

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.

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.

PropertyDescription
SubjectThe authenticated subject.
ServiceProviderThe SAML service provider requesting the assertion.
ResolvedFormatThe resolved NameID format (after applying priority: request → SP default → unspecified).
SPNameQualifierSPNameQualifier from the AuthnRequest NameIDPolicy, if present.
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.

MemberDescription
NameIdThe generated NameID, or null if generation failed.
ErrorThe error, or null if generation succeeded.
IsErrorWhether this result represents an error.
SuccessCreates a successful result.
FailureCreates 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.

PropertyDescription
ValueThe value, i.e. string contents of the XML node.
FormatA URI reference representing the classification of string-based identifier information.
SPNameQualifierOptionally qualifies a name identifier in the namespace of a service provider or affiliation of providers.
NameQualifierThe 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 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 to SamlOptions.EmailNameIdClaimType (default email).
  • Every other format: uses the sub claim and echoes ResolvedFormat, including for persistent and transient.
  • On failure, the default implementation returns Responder / InvalidNameIDPolicy status codes with a message. The default ISaml2SsoResponseGenerator uses only the message: the user sees the IdentityServer error page and no SAML error response is sent to the SP.
builder.Services.AddScoped<ISamlNameIdGenerator, CustomNameIdGenerator>();