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).

SAMLIdentityProvider

SAMLIdentityProvider supports SAML SSO and SLO when acting as the identity provider.

Initiating SSO

InitiateSSO 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.

public static void InitiateSSO(
    HttpResponseBase httpResponse, 
    string userName, 
    IDictionary<string, string> attributes = null, 
    string authnContext = null, 
    string relayState = null, 
    string partnerSP = null, 
    string assertionConsumerServiceUrl = null)

For example:

SAMLIdentityProvider.InitiateSSO(
    Response, 
    userName, 
    attributes, 
    null, 
    null, 
    partnerSP);

Specifying SAML attributes as a dictionary is convenient for the most common use case of simple name/value pairs. For attributes with multiple values, complex structures, or repeated names, a SAMLAttribute array may be specified instead.

public static void InitiateSSO(
    HttpResponseBase httpResponse, 
    string userName, 
    SAMLAttribute[] attributes = null, 
    string authnContext = null, 
    string relayState = null, 
    string partnerSP = null, 
    string assertionConsumerServiceUrl = null)

httpResponse

The HTTP response.

userName

The user name 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 name 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.

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.

partnerSP

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.

assertionConsumerServiceUrl

The assertion consumer service URL overrides any configured value. It's the endpoint that receives SAML response.

Receiving SSO Requests

ReceiveSSO 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 SendSSO method.

public static void ReceiveSSO(
    HttpRequestBase httpRequest, 
    out string partnerSP, 
    out SSOOptions ssoOptions)

For example:

SAMLIdentityProvider.ReceiveSSO(
    Request, 
    out string partnerSP, 
    out SSOOptions ssoOptions);

httpRequest

The HTTP request.

partnerSP

The partner provider name.

ssoOptions

The SSO options.

Sending SSO Responses

SendSSO 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, ReceiveSSO must have been called and the user authenticated at the identity provider.

public static void SendSSO(
    HttpResponseBase httpResponse, 
    string userName, 
    IDictionary<string, string> attributes = null, 
    string authnContext = null, 
    string assertionConsumerServiceUrl = null)

For example:

SAMLIdentityProvider.SendSSO(Response, userName, attributes);

Specifying SAML attributes as a dictionary is convenient for the most common use case of simple name/value pairs. For attributes with multiple values, complex structures, or repeated names, a SAMLAttribute array may be specified instead.

public static void SendSSO(
    HttpResponseBase httpResponse, 
    string userName, 
    SAMLAttribute[] attributes = null, 
    string authnContext = null, 
    string assertionConsumerServiceUrl = null)

httpResponse

The HTTP response.

userName

The user name 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 name 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.

assertionConsumerServiceUrl

The assertion consumer service URL overrides any configured value. It's the endpoint that receives SAML response.

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.

public static void SendSSO(
    HttpResponseBase httpResponse, 
    string statusCode, 
    string statusMessage, 
    string assertionConsumerServiceUrl = null)

For example:

SAMLIdentityProvider.SendSSO(
    Response, 
    SamlIdentifiers.PrimaryStatusCodes.Responder, null);

statusCode

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

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

statusMessage

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

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

assertionConsumerServiceUrl

The assertion consumer service URL overrides any configured value. It's the endpoint that receives SAML response.

Initiating SLO

InitiateSLO 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 an active SSO session for the user.

public static void InitiateSLO(
    HttpResponseBase httpResponse, 
    string logoutReason, 
    string relayState)

For example:

SAMLIdentityProvider.InitiateSLO(Response, null, null);

httpResponse

The HTTP response.

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

ReceiveSLO receives a logout request (i.e. SP-initiated SLO) or a single logout response (i.e. IdP-initiated SLO) from a service provider.

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 SendSLO.

public static void ReceiveSLO(
    HttpRequestBase httpRequest, 
    HttpResponseBase httpResponse, 
    out bool isRequest, 
    out bool hasCompleted, 
    out string logoutReason, 
    out string partnerSP, 
    out string relayState)

For example:

SAMLIdentityProvider.ReceiveSLO(
    Request, 
    Response, 
    out bool isRequest, 
    out bool hasCompleted, 
    out string logoutReason, 
    out string partnerSP, 
    out string relayState);

httpRequest

The HTTP request.

httpResponse

The HTTP response.

isRequest

True if a logout request was received rather than a logout response.

hasCompleted

True if IdP-initiated SLO has completed.

logoutReason

The logout reason.

partnerSP

The partner service provider name.

relayState

The relay state.

Sending SLO Responses

SendSLO 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, ReceiveSLO must have been called and the user logged out at the identity provider.

public static void SendSLO(HttpResponseBase httpResponse, string errorMessage)

For example:

SAMLIdentityProvider.SendSLO(Response, null);

httpResponse

The HTTP response.

errorMessage

If specified, the error message indicates why logout failed.