SAML Registration Extension Methods
These extension methods on IIdentityServerBuilder register SAML services. For other registration methods, see Dependency Injection Extension Methods.
SAML in IdentityServer works in two directions, and the registration methods differ for each:
- IdentityServer as the SAML identity provider (IdP). Your applications are service providers (SPs) that rely on IdentityServer to sign users in. These SPs are downstream of IdentityServer, and each one is a
SamlServiceProvider. - IdentityServer as a SAML service provider. Users sign in with an external SAML identity provider, which is upstream of IdentityServer, and each one is a
SamlProvider(a dynamic provider).
Serving downstream service providers
Section titled “Serving downstream service providers”| Method | Description |
|---|---|
AddSaml() / AddSaml(Action<SamlOptions>) | Adds SAML 2.0 support to IdentityServer. Registers all SAML services and endpoints, and enables the SAML endpoints in EndpointsOptions. The overload with a configureSaml action adds SAML 2.0 support to IdentityServer with custom endpoint configuration. configureSaml is the action to configure SAML options. Endpoint paths configured here are used for routing registration. Returns the builder, to allow chaining. |
AddInMemorySamlServiceProviders(IEnumerable<SamlServiceProvider>) | Adds the in-memory SAML service provider store. serviceProviders are the SAML service providers. Returns the builder, to allow chaining. Validation applies, duplicate entity IDs throw ArgumentException, and FindByEntityIdAsync doesn’t return disabled SPs. |
AddSamlServiceProviderStore<T>() | Adds a custom SAML service provider store. The store is wrapped in a ValidatingSamlServiceProviderStore<T> that validates service provider configuration on load using the registered ISamlServiceProviderConfigurationValidator. T is the type of the ISamlServiceProviderStore implementation. Returns the builder, to allow chaining. The registration is transient. |
AddSamlServiceProviderStoreCache<T>() | Registers a caching decorator around a custom ISamlServiceProviderStore implementation. T is the type of the concrete service provider store class that is registered in DI. Returns the builder, to allow chaining. The decorator caches SamlServiceProvider configuration objects in a HybridCache to reduce repeated store lookups. The cache duration is configured with SamlServiceProviderStoreExpiration on IdentityServerOptions.Caching. GetAllSamlServiceProvidersAsync isn’t cached. |
AddSamlSigninStateStore<T>() | Registers a custom ISamlSigninStateStore implementation for persisting SAML authentication state during the single sign-on flow. Replace the default in-memory store with a durable implementation for production use. The registration is transient. |
AddSamlLogoutSessionStore<T>() | Registers a custom ISamlLogoutSessionStore implementation for persisting SAML logout session tracking state during the single logout flow. Replace the default in-memory store with a durable implementation for production use. The registration is transient. |
Signing in with external identity providers
Section titled “Signing in with external identity providers”| Method | Description |
|---|---|
AddSamlDynamicProvider() | Adds the SAML 2.0 dynamic provider feature. It registers the SAML SP authentication handler for dynamic providers, so IdentityServer can act as the SP toward dynamically managed, external SAML identity providers (see Dynamic Providers). For downstream SamlServiceProvider entries, use the methods in the previous section. |
AddInMemorySamlProviders(IEnumerable<SamlProvider>) | Adds the in-memory SAML provider store. Providers registered by multiple calls to any in-memory identity provider registration method are accumulated rather than replacing one another. The supplied collection is retained by reference, so callers may mutate their own collection at runtime and have the changes observed by the store. The SamlProvider entries describe the external SAML identity providers that users sign in with. They’re separate from SamlServiceProvider entries. |
Registration behavior
Section titled “Registration behavior”AddSaml()registers its defaults without overwriting services you’ve already registered. The exception isISamlLogoutNotificationService, which it replaces, so register a custom logout notification service afterAddSaml().AddIdentityServer()registersISamlSigningService,ISaml2IssuerNameService,ISaml2SloResponseGenerator, and the in-memoryISamlLogoutSessionStoreas defaults, so they’re available even beforeAddSaml().- Defaults for the validators, response generators, resource resolver, NameID generator, metadata generator, front-channel logout request builder, and IdP-initiated service are transient.
ISamlSigningServiceis scoped. The in-memory sign-in state and logout session stores are singletons. AddIdentityServer()also registers an emptyISamlServiceProviderStoreand a no-opISamlLogoutNotificationService.AddSaml()replaces the no-op notification service.AddConfigurationStore()andAddOperationalStore()fromDuende.IdentityServer.EntityFrameworkregister the EF Core stores for service providers, sign-in state, and logout session stores.