Skip to content

SAML API - Common

This sections describes the interfaces common to both service provider and identity provider implementations.

ISamlProvider

The ISamlProvider interface is the base interface for ISamlServiceProvider and ISamlIdentityProvider.

ISamlProvider extends the IArtifactResolver interface.

Configuration Selection

The configuration name specifies the SAML configuration to use when processing SSO and SLO requests for the current browser session.

It must match the name of one of the SAML configurations.

Typically, it's used in multi-tenant applications where each tenant has a separate SAML configuration.

There are no concurrency issues setting the configuration name for multiple browser sessions as it's stored in the SAML SSO session state.

Note

Specifying the configuration name is only required when there are multiple SAML configurations.

Task SetConfigurationNameAsync(string configurationName);

For example:

await _samlServiceProvider.SetConfigurationNameAsync(configurationName);

configurationName

The configuration name specifies which SAML configuration to use when processing SSO and SLO requests for the current browser session.

SSO Status

GetStatusAsync returns the current SSO status for the browser session.

Task<ISsoStatus> GetStatusAsync();

For example:

var ssoStatus = await _samlServiceProvider.GetStatusAsync();

Peeking Message Types

PeekMessageTypeAsync returns the type of the SAML message currently being received.

The recommendation is to use separate endpoints for different message types.

However, if a single endpoint is being used to receive all SAML messages, the message type may be peeked to determine how to continue with the processing of the message.

Task<SamlMessageType> PeekMessageTypeAsync();

For example:

var samlMessageType = await _samlServiceProvider.PeekMessageTypeAsync();

Clearing the SAML Session

ClearSessionAsync clears the SAML session state for all partners or for the specified partner only.

Task ClearSessionAsync(string partnerName = null);

For example:

await _samlServiceProvider.ClearSessionAsync();

IArtifactResolver

The IArtifactResolver interface supports the HTTP-Artifact binding and the processing of SAML artifact resolve requests, which is less commonly used.

Artifact Resolution

ResolveArtifactAsync receives a SAML artifact resolve request and returns a SAML artifact response.

Task ResolveArtifactAsync();

For example:

await _samlServiceProvider.ResolveArtifactAsync();

ISsoOptions

The ISsoOptions interface encapsulates various options associated with SSO.

All ISsoOptions fields are included in the SAML authentication request unless otherwise noted.

RequestedUserName

The request user name identifies the user to be authenticated.

The default is none.

ForceAuthn

The ForceAuthn flag requests that the identity provider discards any existing user authentication session and establish a new user authentication session.

The default is false.

IsPassive

The IsPassive flag requests that the identity provider not visibly take control of the user interface.

The default is false.

AllowCreate

The AllowCreate flag indicates whether the identity provider is allowed to create a new user as part of processing the request.

The default is true.

ProviderName

The provider name is the human readable name of the requesting SAML provider.

The default is none.

NameIDFormat

The name ID format specifies the format of the name ID.

The default is none.

SPNameQualifier

The service provider name qualifier specifies that the assertion subject's identifier be returned in the namespace of a service provider other than the requester.

The default is none.

RequestedAuthnContexts

The requested authentication contexts place requirements on the authentication process at the identity provider. For example, it may request multi-factor authentication of users.

The default is none.

RequestedAuthnContextComparison

The comparison method is used to evaluate the requested contexts.

The comparison methods are:

  • exact
  • minimum
  • maximum
  • better

The default is exact.

TrustedIdentityProviders

The trusted identity providers are included as scoping.

The default is none.

Destination

The destination specifies the address to which the SAML authentication request is sent.

The default is the configured single sign-on service URL.

ITrustedIdentityProvider

The ITrustedIdentityProvider interface specifies scoping information.

ProviderID

The provider ID identifies the SAML provider by its ID.

Name

The name is the human readable name of the SAML provider.

The default is none.

ISloResult

ISloResult returns the result of receiving a logout message at the local provider.

correlationID

The correlation ID identifying the logout request to respond to.

PartnerName

The partner name identifies the partner provider that sent the logout message.

IsResponse

The flag indicating whether a logout request or response was received.

HasCompleted

The flag indicating whether SAML logout has completed.

LogoutReason

The logout reason identifies why the user logged out.

RelayState

The relay state is opaque data that is sent with the logout request and returned with the logout response. It should not be interpreted by the receiving service providers.

Its use is supported but not recommended.

ISsoStatus

The ISsoStatus interface encapsulates the SSO status for the browser session.

GetConfigurationName returns the SAML configuration name for the current SAML SSO session.

string GetConfigurationName();

IsSso indicates whether the local provider is currently single signed-on with any partner provider.

bool IsSso();

IsSso indicates whether the local provider is currently single signed-on with the specified partner provider.

bool IsSso(string partnerName);

IsSsoCompletionPending indicates whether completion of single sign-on is pending.

bool IsSsoCompletionPending();

IsSsoCompletionPending indicates whether completion of single sign-on is pending with the specified partner provider.

bool IsSsoCompletionPending(string partnerName);

IsSloCompletionPending indicates whether completion of single logout is pending.

bool IsSloCompletionPending();

IsSloCompletionPending indicates whether completion of single logout is pending with the specified partner provider.

bool IsSloCompletionPending(string partnerName);

CanSloAsync indicates whether the local provider can single logout to one or more partner providers.

Task<bool> CanSloAsync();

CanSloAsync indicates whether the local provider can single logout to the specified partner provider.

Task<bool> CanSloAsync(string partnerName);

GetPartnerPendingResponse returns name of the partner provider to which a response is pending for the specified correlation ID.

string GetPartnerPendingResponse(string correlationID);

GetPartnersPendingResponse returns the names of the partner providers to which a single sign-on or logout response is pending.

string[] GetPartnersPendingResponse();