SAML API - Identity Provider

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

ISamlIdentityProvider

The ISamlIdentityProvider interface supports SAML SSO and SLO when acting as the identity provider.

ISamlIdentityProvider extends the ISamlProvider interface.

Initiating SSO

InitiateSsoAsync initiates single sign-on from the identity provider to the service provider (i.e. IdP-initiated SSO).

A SAML response containing a SAML assertion is constructed and sent to the service provider's assertion consumer service.

Prior to calling this method, the user must have been authenticated at the identity provider.

Task InitiateSsoAsync(
    string partnerName = null, 
    string userID = null, 
    IList<SamlAttribute> attributes = null, 
    string relayState = null, 
    string authnContext = null, 
    string nameIDFormat = null);

For example:

await _samlIdentityProvider.InitiateSsoAsync(partnerName, userName, attributes);

partnerName

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

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

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

userID

The user ID is the primary information identifying the user. It's included as the SAML assertion's subject name identifier (i.e. NameID).

For example, the user ID could be their email address.

attributes

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

For example, the user's first and last name may be included as SAML attributes.

relayState

The relay state specifies the target URL the service provider should redirect to once SSO completes successfully.

Its purpose is to support deep web links.

If not specified, the service provider determines which page to display after SSO completes. Typically, this will be the home page.

authnContext

The authentication context identifies how the user was authenticated.

If not specified, the configured authentication context, if any, is used.

nameIDFormat

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

If not specified, the configured name ID format, if any, is used.

Receiving SSO Requests

ReceiveSsoAsync receives a single sign-on request from a service provider (i.e. SP-initiated SSO).

A SAML authentication request is received and processed.

The identity provider must authenticate the user and respond to the service provider by calling the SendSsoAsync method.

Task<IIdpSsoResult> ReceiveSsoAsync();

For example:

var idpSsoResult = await _samlIdentityProvider.ReceiveSsoAsync();

Sending SSO Responses

SendSsoAsync method sends a single sign-on response to the service provider (i.e. SP-initiated SSO).

A SAML response containing a SAML assertion is constructed and sent to the service provider's assertion consumer service.

Prior to calling this method, ReceiveSsoAsync must have been called and the user authenticated at the identity provider.

Task SendSsoAsync(
    string userID = null, 
    IList<SamlAttribute> attributes = null, 
    string authnContext = null, 
    string nameIDFormat = null, 
    string correlationID = null);

For example:

await _samlIdentityProvider.SendSsoAsync(userName, attributes);

userID

The user ID is the primary information identifying the user. It's included as the SAML assertion's subject name identifier (i.e. NameID).

For example, the user ID could be their email address.

attributes

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

For example, the user's first and last name may be included as SAML attributes.

authnContext

The authentication context identifies how the user was authenticated.

If not specified, the configured authentication context, if any, is used.

nameIDFormat

The name ID format specifies the name ID format.

If not specified, the configured name ID format, if any, is used.

correlationID

The correlation ID identifying the authentication request to respond to.

Sending SSO Error Responses

If an error occurs at the identity provider during SP-initiated SSO, an error status may be returned to the service provider.

Task SendSsoAsync(Status status, string correlationID = null);

For example:

await _samlIdentityProvider.SendSsoAsync(
    new Status(SamlConstants.PrimaryStatusCodes.Responder));

status

The status is returned in the SAML response to the service provider.

It should provide generic information that doesn't compromise security in any way.

correlationID

The correlation ID identifying the authentication request to respond to.

Initiating SLO

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

A SAML logout request is sent to each service provider with a current SSO session for the user.

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

For example:

await _samlIdentityProvider.InitiateSloAsync();

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 service providers.

Its use is supported but not recommended.

Receiving SLO Messages

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

A SAML logout request or response is received and processed.

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

Task<ISloResult> ReceiveSloAsync();

For example:

var sloResult = await _samlIdentityProvider.ReceiveSloAsync();

Sending SLO Responses

SendSloAsync sends a logout response to the service provider (i.e. SP-initiated SLO).

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

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

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

For example:

await _samlIdentityProvider.SendSloAsync();

errorMessage

If specified, the error message indicates why logout failed.

correlationID

The correlation ID identifying the logout request to respond to.

IIdPSsoResult

IIdPSsoResult returns the result of SP-initiated SSO at the identity provider.

correlationID

The correlation ID identifying the authentication request to respond to.

PartnerName

The partner name identifies the service provider that initiated SSO.

It's retrieved from the issuer field of the authentication request.

It's provided in case the application has service provider specific processing to perform.

SsoOptions

The SSO options associated with the authentication request.