SAML API - Service Provider

The SAML API supports web applications acting as a SAML service provider (SP) and participating in single sign-on (SSO) and single logout (SLO).

ISamlServiceProvider

The ISamlServiceProvider interface supports SAML SSO and SLO when acting as the service provider.

ISamlServiceProvider extends the ISamlProvider interface.

Initiating SSO

InitiateSsoAsync initiates SSO from the service provider to the identity provider (i.e. SP-initiated SSO).

A SAML authentication request is constructed and sent to the identity provider's SSO service.

Task InitiateSsoAsync(
    string partnerName = null, 
    string relayState = null, 
    ISsoOptions ssoOptions = null);

For example:

await _samlServiceProvider.InitiateSsoAsync(partnerName);

partnerName

The partner name corresponds to one of the partner identity provider names in the SAML configuration.

For example, if a configured partner identity provider is "https://ExampleIdentityProvider", this name must be specified in order to initiate SSO to this identity provider.

If multiple partner identity providers are configured, the partner name must be specified.

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 identity provider.

Its use is supported but not recommended.

ssoOptions

The SSO options are included in the authentication request sent to the identity provider.

Receiving SSO Responses

ReceiveSsoAsync receives a single sign-on response from an identity provider (i.e. IdP-initiated or SP-initiated SSO).

A SAML response is received and processed. If the SAML response indicates success, the included SAML assertion is processed.

The service provider should perform an automatic login of the user using information returned from the SAML assertion.

Task<ISpSsoResult> ReceiveSsoAsync();

For example:

var ssoResult = await _samlServiceProvider.ReceiveSsoAsync();

Initiating SLO

InitiateSloAsync initiates single logout from the service provider to the identity provider (i.e. SP-initiated SLO).

A SAML logout request is sent to the identity provider.

Task InitiateSloAsync(
    string partnerName = null, 
    string logoutReason = null, 
    string relayState = null);

For example:

await _samlServiceProvider.InitiateSloAsync(partnerName);

partnerName

The partner name corresponds to one of the partner identity provider names in the SAML configuration.

For example, if a configured partner identity provider is "https://ExampleIdentityProvider", this name must be specified in order to initiate SSO to this identity provider.

If multiple partner identity providers are configured, the partner name must be specified.

logoutReason

If specified, 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 identity provider.

Its use is supported but not recommended.

Receiving SLO Messages

ReceiveSloAsync receives a single logout request (i.e. IdP-initiated SLO) or a single logout response (i.e. SP-initiated SLO) from an identity provider and returns an SLO result.

A SAML logout request or response is received and processed.

For a logout request, the service provider must logout the user and respond to the identity provider by calling SendSloAsync.

Task<ISloResult> ReceiveSloAsync();

For example:

var sloResult = await _samlServiceProvider.ReceiveSloAsync();

Sending SLO Responses

SendSloAsync method sends a single logout response to the identity provider (i.e. IdP-initiated SLO).

A SAML logout response is constructed and sent to the identity provider's logout service.

Prior to calling this method, ReceiveSloAsync must have been called and the user logged out at the service provider.

Task SendSloAsync(string errorMessage = null, string correlationID = null);

For example:

await _samlServiceProvider.SendSloAsync();

errorMessage

If specified, the error message indicates why logout failed.

correlationID

The correlation ID identifying the logout request to respond to.

Accessing SAML Events

The ISamlServiceProviderEvents interface provides access to optional events associated with SAML SSO and SLO.

ISamlServiceProviderEvents Events { get; set; }

ISPSsoResult

ISPSsoResult returns the result of IdP-initiated or SP-initiated SSO at the service provider.

PartnerName

The partner name identifies the identity provider that initiated or responded to SSO.

It's retrieved from the issuer field of the SAML response.

This allows applications to perform IdP-specific processing, if needed.

InResponseTo

The InResponseTo flag indicates whether the SSO result is in response to a previous SSO request.

For IdP-initiated SSO, the flag is false. For SP-initiated SSO, the flag is true.

UserID

The user ID identifies the user and is retrieved from the SAML assertion's subject name identifier.

Attributes

SAML attributes are name/value pairs of additional information about the user that are retrieved from the SAML assertion.

NameIDFormat

Specifies the format of the NameID used in the SAML assertion.

AuthnContext

Specifies how the user was authenticated, as indicated in the SAML assertion.

RelayState

The relay state is opaque data that is sent with the authentication request and returned with the SAML response.

Its use is supported but not recommended.