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).
SAMLServiceProvider
SAMLServiceProvider supports SAML SSO and SLO when acting as the service provider.
Initiating SSO
InitiateSSO 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.
public static void InitiateSSO(
HttpResponseBase httpResponse,
string relayState = null,
string partnerIdP = null,
SSOOptions ssoOptions = null,
string assertionConsumerServiceUrl = null,
string singleSignOnServiceUrl = null)
For example:
httpResponse
The HTTP response.
relayState
The relay state is opaque data sent with the authentication request and returned with the SAML response. It should not be interpreted by the receiving identity providers.
Its use is supported but not recommended.
partnerIdP
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.
ssoOptions
The SSO options are included in the authentication request sent to the identity provider.
assertionConsumerServiceUrl
The assertion consumer service URL overrides any configured value. It's the endpoint that receives SAML responses.
singleSignOnServiceUrl
The single sign-on service URL overrides any configured value. It's the endpoint that the SAML authentication request is sent to.
Receiving SSO Responses
ReceiveSSO 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 is responsible for performing an application-level automatic login of the user using information returned from the SAML assertion.
public static void ReceiveSSO(
HttpRequestBase httpRequest,
out bool isInResponseTo,
out string partnerIdP,
out string authnContext,
out string userName,
out IDictionary<string, string> attributes,
out string relayState)
For example:
SAMLServiceProvider.ReceiveSSO(
Request,
out bool isInResponseTo,
out string partnerIdP,
out string authnContext,
out string userName,
out IDictionary<string, string> attributes,
out string relayState);
Returning 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 returned instead.
public static void ReceiveSSO(
HttpRequestBase httpRequest,
out bool isInResponseTo,
out string partnerIdP,
out string authnContext,
out string userName,
out SAMLAttribute[] attributes,
out string relayState)
httpRequest
The HTTP request.
isInResponseTo
This will be true for SP-initiated SSO and false for IdP-initiated SSO.
partnerIdP
The partner identity provider name.
authnContext
The authentication context identifying how the user was authenticated.
userName
The user name in the SAML assertion.
attributes
The SAML attributes in the SAML assertion.
relayState
The relay state.
Initiating SLO
InitiateSLO 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.
public static void InitiateSLO(
HttpResponseBase httpResponse,
string logoutReason,
string relayState,
string partnerIdP = null)
For example:
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 identity provider.
Its use is supported but not recommended.
partnerIdP
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 SLO to this identity provider.
If multiple partner identity providers are configured, the partner name must be specified.
Receiving SLO Messages
ReceiveSLO receives a single logout request (i.e. IdP-initiated SLO) or a single logout response (i.e. SP-initiated SLO) from an identity provider.
A SAML logout request or response is received and processed.
For a logout request, the service provider must logout the user before responding to the identity provider by calling SendSLO.
public static void ReceiveSLO(
HttpRequestBase httpRequest,
out bool isRequest,
out string logoutReason,
out string partnerIdP,
out string relayState)
For example:
SAMLServiceProvider.ReceiveSLO(
Request,
out bool isRequest,
out string logoutReason,
out string partnerIdP,
out string relayState);
httpRequest
The HTTP request.
isRequest
True if a logout request was received rather than a logout response.
logoutReason
The logout reason.
partnerIdP
The partner identity provider name.
relayState
The relay state.
Sending SLO Responses
SendSLO 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, ReceiveSLO must have been called and the user logged out at the service provider.
For example:
httpResponse
The HTTP response.
errorMessage
If specified, the error message indicates why logout failed.