Skip to content

SAML Configuration Reference

The SAML configuration is defined by an XML schema.

This section describes each object in the schema.

SAMLConfigurations

SAMLConfigurations specifies the SAML configurations.

Configurations [required]

Configurations is a list of one or more SAMLConfiguration items.

Each SAMLConfiguration item corresponds to a tenant in a multi-tenancy application.

In the more common single tenancy application, a single SAMLConfiguration is defined.

SAMLConfiguration

SAMLConfiguration specifies a single SAML configuration for a local identity provider or service provider.

Name [optional]

Each SAMLConfiguration is identified by a unique name. This name is internal to the configuration and is not exposed to partner providers.

A name is only required if there are multiple SAML configurations.

LocalIdentityProviderConfiguration [optional]

This property specifies the LocalIdentityProviderConfiguration.

LocalServiceProviderConfiguration [optional]

This property specifies the LocalServiceProviderConfiguration.

PartnerIdentityProviderConfigurations [optional]

The PartnerIdentityProviderConfigurations is the list of one or more PartnerIdentityProviderConfiguration items.

Each PartnerIdentityProviderConfiguration specifies the configuration to participate in SSO with a partner identity provider.

PartnerServiceProviderConfigurations [optional]

The PartnerServiceProviderConfigurations is the list of one or more PartnerServiceProviderConfiguration items.

Each PartnerServiceProviderConfiguration specifies the configuration to participate in SSO with a partner service provider.

LocalIdentityProviderConfiguration

LocalIdentityProviderConfiguration specifies the configuration for the local identity provider.

Its base class is LocalProviderConfiguration.

SingleSignOnServiceUrl [optional]

The single sign-on service URL is the location of the local identity provider's SSO service where SAML authentication requests are received as part of SP-initiated SSO.

If specified, it may be used to perform certain security checks as part of the SAML protocol.

Its use is optional but recommended.

LocalServiceProviderConfiguration

LocalServiceProviderConfiguration specifies the configuration for the local service provider.

Its base class is LocalProviderConfiguration.

AssertionConsumerServiceUrl [optional]

The assertion consumer service URL is the location of the local service provider's assertion consumer service where SAML responses are received as part of SSO.

If specified, it may be used to perform additional security checks as part of the SAML protocol.

Its use is optional but recommended.

PartnerIdentityProviderConfiguration

PartnerIdentityProviderConfiguration specifies the configuration for a partner identity provider.

Its base class is PartnerProviderConfiguration.

SingleSignOnServiceUrl [optional]

The single sign-on service URL is the location of the partner identity provider's SSO service where SAML authentication requests are sent as part of SP-initiated SSO. If only IdP-initated SSO is supported, this URL may be omitted.

SingleSignOnServiceBinding [optional]

The single sign-on service binding specifies the transport mechanism (ie SAML binding) to use when sending SAML authentication requests to the partner identity provider.

The binding options are:

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

The default is urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect.

SignAuthnRequest [optional]

The flag specifies whether SAML authentication requests sent to the partner identity provider should be signed. Signing authentication requests is recommended but optional.

The default is true.

ForceAuthn [optional]

The flag specifies whether the force authentication attribute in SAML authentication requests sent to the partner identity provider should be set.

The default is false.

WantAssertionOrResponseSigned [optional]

The flag specifies whether either SAML responses or assertions received from the partner identity provider should be signed. If the flag is set and neither the SAML response nor SAML assertion is signed or the signature cannot be verified, this is considered an error.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the partner provider with its private key and verified by the local provider with the partner provider's public key.

Generally, it doesn't matter whether the SAML response or assertion is signed. The payload of the SAML response is the SAML assertion so signing the SAML response includes the SAML assertion.

It's recommended that WantAssertionOrResponseSigned is set to true.

The default is true.

WantSAMLResponseSigned [optional]

The flag specifies whether SAML responses received from the partner identity provider should be signed. If the flag is set and either the SAML response isn't signed or the signature cannot be verified, this is considered an error.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the partner provider with its private key and verified by the local provider with the partner provider's public key.

It's recommended that WantAssertionOrResponseSigned, WantSAMLResponseSigned or WantAssertionSigned is set to true.

The default is false.

WantAssertionSigned [optional]

The flag specifies whether SAML assertions received from the partner identity provider should be signed. If the flag is set and either the SAML assertion isn't signed or the signature cannot be verified, this is considered an error.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the partner provider with its private key and verified by the local provider with the partner provider's public key.

It's recommended that WantAssertionOrResponseSigned, WantSamlResponseSigned or WantAssertionSigned is set to true.

The default is false.

WantAssertionEncrypted [optional]

The flag specifies whether SAML assertions received from the partner identity provider should be encrypted. If the flag is set and either the SAML assertion isn't encrypted or cannot be decrypted, this is considered an error.

Encrypting ensures the privacy of the content. Assertions will be encrypted by the partner provider with the local provider's public key and decrypted by the local provider with its private key.

If the SAML assertion includes sensitive information it's recommended that it's encrypted. This SAML assertion encryption is in addition to the privacy provided at the transport layer when using the recommended HTTPS protocol. In many scenarios, encryption of the assertion is not required.

The default is false.

ProviderName [optional]

The provider name is included in the SAML authentication requests sent to the partner identity provider.

AuthnContextComparison [optional]

The comparison method is included in the SAML authentication requests sent to the partner identity provider.

The comparison method is used to evaluate the requested contexts.

The comparison methods are:

  • exact
  • minimum
  • maximum
  • better

The default is to not include a comparison which is equivalent to specifying exact.

DisableIdPInitiatedSso [optional]

The flag specifies whether IdP-initiated SSO is supported.

Both IdP-initiated and SP-initiated SSO are supported.

Setting the flag to true disables IdP-initiated SSO.

The default is false.

DisableAssertionReplayCheck [optional]

The flag specifies whether checks for SAML assertion replay attacks are disabled.

Each SAML assertion includes a unique ID. A cache of received SAML assertion IDs is maintained and if an ID matches a previously received ID this is considered an error.

Setting the flag to true disables this check.

The default is false.

DisableRecipientCheck [optional]

A SAML assertion may include a subject confirmation recipient URI. This identifies the intended recipient of the SAML assertion. If included, it should match the service provider's assertion consumer service URL specified by the AssertionConsumerServiceUrl configuration property.

Setting the flag to true disables this check.

The default is false.

DisableAudienceRestrictionCheck [optional]

A SAML assertion may include an audience restriction URI. This identifies the intended recipient of the SAML assertion. If included, it should match the service provider's name.

Setting the flag to true disables this check.

The default is false.

DisableAuthnContextCheck [optional]

A SAML assertion may include an authentication context. This identifies the mechanism by which the user was authenticated at the identity provider. For example, if the user was authenticated by password, the authentication context would be "urn:oasis:names:tc:SAML:2.0:ac:classes:Password". If included, it should match the authentication context class specified by the optional ExpectedAuthnContext configuration property.

Setting the flag to true disables this check.

The default is false.

PartnerServiceProviderConfiguration

PartnerServiceProviderConfiguration specifies the configuration for a partner service provider.

Its base class is PartnerProviderConfiguration.

AssertionConsumerServiceUrl [optional]

The assertion consumer service URL is the location of the partner service provider's ACS where SAML responses are sent as part of SSO.

WantAuthnRequestSigned [optional]

The flag specifies whether SAML authentication requests received from the partner service provider should be signed. Receiving signed authentication requests is recommended but optional.

The default is true.

SignSAMLResponse [optional]

The flag specifies whether SAML responses sent to the partner service provider should be signed.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the local provider with its private key and verified by the partner provider with the local provider's public key.

It's recommended that either SignSAMLResponse or SignAssertion is set to true.

The default is false.

SignAssertion [optional]

The flag specifies whether SAML assertions sent to the partner service provider should be signed.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the local provider with its private key and verified by the partner provider with the local provider's public key.

It's recommended that either SignSamlResponse or SignAssertion is set to true.

The default is true.

EncryptAssertion [optional]

The flag specifies whether SAML assertions sent to the partner service provider should be encrypted.

Encrypting ensures the privacy of the content. Assertions will be encrypted by the local provider with the partner provider's public key and decrypted by the partner provider with its private key.

If the SAML assertion includes sensitive information, it's recommended that it's encrypted. This SAML assertion encryption is in addition to the privacy provided at the transport layer when using the recommended HTTPS protocol. In many scenarios, encryption of the assertion is not required.

The default is false.

AssertionLifeTime [optional]

The assertion lifetime specifies the time span for which the SAML assertion is valid. It is the current UTC time plus or minus the assertion lifetime time span.

The time span should be kept short but not so short as to cause issues when server clocks are not synchronized exactly.

The default is 3 minutes.

RelayState [optional]

The relay state is sent as part of IdP-initiated SSO and specifies the URL the service provider should redirect to once SSO completes.

LocalProviderConfiguration

LocalProviderConfiguration is an abstract base class.

Its base class is ProviderConfiguration.

SingleLogoutServiceUrl [optional]

The single logout service URL is the location of the local provider's SLO service where SAML logout messages are received. If SLO is not supported, this URL may be omitted.

If specified, it may be used to perform certain security checks as part of the SAML protocol.

Its use is optional but recommended.

ResolveToHttps [optional]

The flag specifies whether local URLs should be resolved to HTTPS.

This is useful when using an SSL terminating device such as a load balancer.

For example, if true, a local URL of http://www.sp.com/SAML/AssertionConsumerService would be resolved to https://www.sp.com/SAML/AssertionConsumerService when included in the SAML authentication request sent to the identity provider.

The default is true.

PartnerProviderConfiguration

PartnerProviderConfiguration is an abstract base class.

Its base class is ProviderConfiguration.

PartnerCertificates [optional]

PartnerCertificates is a list of Certificate items that specify one or more X.509 certificates issued to the partner provider and used by the local provider. Typically, only a single certificate is specified. If more than one certificate is specified and a security operation using the certificates fails, the operation is retried using the next certificate in the list until either successful or all certificates have been tried.

As an example, if the SAML assertion received by the local service provider is signed, each partner certificate is used in an attempt to verify the signature.

Multiple partner certificates support scenarios including the phased rollover of expired certificates.

AssertionConsumerServiceBinding [optional]

The assertion consumer service binding specifies the transport mechanism (i.e. SAML binding) to use when sending SAML responses to the service provider.

The binding options are:

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

The default is urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

SingleLogoutServiceUrl [optional]

The single logout service URL is the location of the partner provider's SLO service where SAML logout messages are sent. If SLO is not supported, this URL may be omitted.

SingleLogoutServiceResponseUrl [optional]

The single logout service response URL is the location of the partner provider's SLO service where SAML logout responses are sent. If SLO is not supported or the same partner provider endpoint receives logout requests and responses, this URL may be omitted.

SingleLogoutServiceBinding [optional]

The single logout service binding specifies the transport mechanism (i.e. SAML binding) to use when sending SAML logout messages to the partner provider.

The binding options are:

  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

The default is urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect.

LogoutRequestLifeTime [optional]

The assertion lifetime specifies the time span for which the SAML logout request is valid. It is the current UTC time plus or minus the logout request lifetime time span.

The time span should be kept short but not so short as to cause issues when server clocks are not synchronized exactly.

The default is 3 minutes.

SignLogoutRequest [optional]

The flag specifies whether SAML logout requests sent to the partner provider should be signed.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the local provider with its private key and verified by the partner provider with the local provider's public key.

The default is true.

SignLogoutResponse [optional]

The flag specifies whether SAML logout responses sent to the partner provider should be signed.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the local provider with its private key and verified by the partner provider with the local provider's public key.

The default is true.

WantLogoutRequestSigned [optional]

The flag specifies whether SAML logout requests received from the partner provider should be signed. If the flag is set and either the logout request isn't signed or the signature cannot be verified, this is considered an error.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the partner provider with its private key and verified by the local provider with the partner provider's public key.

The default is true.

WantLogoutResponseSigned [optional]

The flag specifies whether SAML logout responses received from the partner provider should be signed. If the flag is set and either the logout response isn't signed or the signature cannot be verified, this is considered an error.

Signing ensures the identity of the sender and the integrity of the content. Signatures will be generated by the partner provider with its private key and verified by the local provider with the partner provider's public key.

The default is true.

EncryptLogoutNameID [optional]

The flag specifies whether Name IDs in logout requests sent to the partner service provider should be encrypted.

Encrypting ensures the privacy of the content. Name IDs will be encrypted by the local provider with the partner provider's public key and decrypted by the partner provider with its private key.

If the Name ID is sensitive information, it's recommended that it's encrypted. This Name ID encryption is in addition to the privacy provided at the transport layer when using the recommended HTTPS protocol. In many scenarios, encryption of the Name ID is not required.

The default is false.

IssuerFormat [optional]

The issuer format specifies the format of the issuer field included in SAML messages.

NameIDFormat [optional]

The name ID format specifies the format of the name identifier. For a local identity provider, the format is included with the SAML assertion name identifier. For a local service provider, the format is included with the SAML authentication request name identifier policy.

DigestMethod [optional]

The digest method specifies how to generate the digest for XML signatures.

The supported digest methods are:

  • http://www.w3.org/2000/09/xmldsig#sha1
  • http://www.w3.org/2001/04/xmlenc#sha256
  • http://www.w3.org/2001/04/xmldsig-more#sha384
  • http://www.w3.org/2001/04/xmlenc#sha512

The default is http://www.w3.org/2001/04/xmlenc#sha256.

SignatureMethod [optional]

The signature method specifies how to generate XML signatures.

The supported signature methods are:

  • http://www.w3.org/2000/09/xmldsig#rsa-sha1
  • http://www.w3.org/2001/04/xmldsig-more#rsa-sha256
  • http://www.w3.org/2001/04/xmldsig-more#rsa-sha384

  • http://www.w3.org/2001/04/xmldsig-more#rsa-sha512

  • http://www.w3.org/2007/05/xmldsig-more#sha1-rsa-MGF1

  • http://www.w3.org/2007/05/xmldsig-more#sha256-rsa-MGF1
  • http://www.w3.org/2007/05/xmldsig-more#sha384-rsa-MGF1

  • http://www.w3.org/2007/05/xmldsig-more#sha512-rsa-MGF1

  • http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha1

  • http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256
  • http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha384
  • http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha512

The default is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256.

WantDigestMethod [optional]

The digest method specifies the required digest method of received XML signatures.

If unspecified, any digest method is permitted.

WantSignatureMethod [optional]

The signature method specifies the required signature method of received XML signatures.

If unspecified, any signature method is permitted.

KeyEncryptionMethod [optional]

The key encryption method specifies how to encrypt the symmetric key used in XML encryption.

The supported key encryption methods are:

  • http://www.w3.org/2001/04/xmlenc#rsa-1_5
  • http://www.w3.org/2009/xmlenc11#rsa-oaep
  • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

The default is http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p.

The http://www.w3.org/2009/xmlenc11#rsa-oaep method requires the use of the ComponentSpace.Saml2.Net.Extension.RsaOaep NuGet package.

KeyEncryptionDigestMethod [optional]

The key encryption digest method is used by the http://www.w3.org/2009/xmlenc11#rsa-oaep and http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p key encryption methods.

The supported key encryption digest methods are:

  • http://www.w3.org/2000/09/xmldsig#sha1
  • http://www.w3.org/2001/04/xmlenc#sha256
  • http://www.w3.org/2001/04/xmldsig-more#sha384
  • http://www.w3.org/2001/04/xmlenc#sha512

The default is http://www.w3.org/2000/09/xmldsig#sha1.

KeyEncryptionMaskGenerationFunction [optional]

The key encryption mask generation function is used by the http://www.w3.org/2009/xmlenc11#rsa-oaep key encryption method.

The supported key encryption mask generation functions are:

  • http://www.w3.org/2009/xmlenc11#mgf1sha1
  • http://www.w3.org/2009/xmlenc11#mgf1sha256
  • http://www.w3.org/2009/xmlenc11#mgf1sha384
  • http://www.w3.org/2009/xmlenc11#mgf1sha512

The default is http://www.w3.org/2009/xmlenc11#mgf1sha1.

DataEncryptionMethod [optional]

The data encryption method specifies how to encrypt the data in XML encryption.

The supported data encryption methods are:

  • http://www.w3.org/2001/04/xmlenc#tripledes-cbc

  • http://www.w3.org/2001/04/xmlenc#aes128-cbc

  • http://www.w3.org/2001/04/xmlenc#aes192-cbc

  • http://www.w3.org/2001/04/xmlenc#aes256-cbc

  • http://www.w3.org/2009/xmlenc11#aes128-gcm

  • http://www.w3.org/2009/xmlenc11#aes192-gcm
  • http://www.w3.org/2009/xmlenc11#aes256-gcm

The default is http://www.w3.org/2001/04/xmlenc#aes256-cbc.

The AES-GCM data encryption methods require the use of the ComponentSpace.Saml2.Net.Extension.AesGcm NuGet package.

ClockSkew [optional]

The clock skew specifies the time span to allow for differences between local and partner computer clocks when checking time intervals.

The time span should be kept short but not so short as to cause issues when server clocks are not synchronized exactly.

The default is 3 minutes.

AuthnContext [optional]

The authentication context to include in the SAML authentication request and expected in the SAML assertion.

UseEmbeddedCertificate [optional]

The flag specifies whether to use the X.509 certificate embedded in the XML signature when verifying the signature.

If the embedded certificate is used, no assumptions can be made about the identity of the sender.

The default is false.

Warning

Embedded certificates should not be used in production.

EnableSha1Support [optional]

The flag specifies whether SHA-1 algorithms are supported.

The default is false.

Warning

The use of SHA-1 is not recommended.

DisableDestinationCheck [optional]

A SAML message may include a destination URI identifying the address to which the message has been sent. If included, it should match the provider's URL where the message was received.

For example, for a SAML response the destination should be the local service provider's assertion consumer service URL as specified by the AssertionConsumerServiceUrl configuration property.

Setting the flag to true disables this check.

The default is false.

DisableTimePeriodCheck [optional]

A SAML assertion or logout request may include attributes identifying a time period in which it is valid. If included, the time at which the SAML assertion or logout request is received should be within this time period.

Setting the flag to true disables this check.

The default is false.

DisableInboundLogout [optional]

Setting the flag to true disables inbound SAML logout requests.

The default is false.

DisableOutboundLogout [optional]

Setting the flag to true disables outbound SAML logout requests.

The default is false.

DisableInResponseToCheck [optional]

All SAML messages includes a unique ID. SAML responses that are in response to a particular SAML request include an in-response-to attribute identifying the SAML request.

Setting the flag to true disables checking to ensure the in-response-to attribute is present and correct.

The default is false.

DisablePendingLogoutCheck [optional]

If a SAML logout response is received without having previously sent a logout request, this is considered an error.

Setting the flag to true disables this check.

The default is false.

DisableLogoutResponseStatusCheck [optional]

If a SAML logout response is received with an error status, this is considered an error.

Setting the flag to true disables this check.

The default is false.

DisableClearAllSessionsOnLogout [optional]

On SAML logout, all sessions to the partner provider for the user are cleared as most partner providers don't support separate logout of multiple SSO sessions in the one browser session.

Setting the flag to true disables this and sessions are be logged out individually.

The default is false.

ProviderConfiguration

ProviderConfiguration specifies properties common to all local and partner providers.

Name [required]

All local and partner providers must have a unique name. Partner providers will supply their names. Local names should be universally unique and, for maximum interoperability, be in the form of a URL. The URL doesn't have to locate a resource but it's common for it to point to the home page of the web application or the download link to the local provider's SAML metadata.

The name corresponds to the entity ID, if SAML metadata is used.

Description [optional]

The description is purely for documentation and is not part of SAML SSO.

LocalCertificates [optional]

The LocalCertificates is a list of Certificate items that specify one or more X.509 certificates issued to and used by the local provider. Typically, only a single certificate is specified. If more than one certificate is specified and a security operation using the certificates fails, the operation is retried using the next certificate in the list until either successful or all certificates have been tried.

As an example, if the SAML assertion received by the local service provider is encrypted each local certificate is used in an attempt to decrypt the SAML assertion.

Multiple local certificates support scenarios including the staggered rollover of expired certificates.

Certificate

The certificate specifies the location and purpose of an X.509 certificate.

Certificates may be base-64 encoded strings, stored on the file system, within a Windows certificate store, or an Azure key vault.

For certificate strings, the base-64 encoded string and optional password must be specified.

For certificate files, the file name and optional password must be specified.

For certificates in a Windows certificate store, the store name and location may be specified along with one of the following: the certificate's serial number; thumb print; or subject name.

For certificates in an Azure key vault, the configuration key must be specified.

Use [optional]

The certificate use may be:

  • Encryption
  • Signature
  • Any

A certificate whose use is encryption may be used for encryption or decryption only.

A certificate whose use is signature may be used for signature generation or verification only.

A certificate whose use is any may be used for any purpose with no restrictions.

The default is encryption and signature.

String [optional]

The string is the certificate base-64 encoded string. This may contain the public key only or the public and private keys.

FileName [optional]

The file name is the relative or absolute path to the X.509 certificate file. This may be a CER file containing a public key only or a PFX file also containing a private key.

Password [optional]

The password protects the private key.

StoreName [optional]

For certificates in a Windows certificate store, the store name specifies the store.

The store name may be one of the standard stores:

  • AddressBook
  • AuthRoot
  • CertificateAuthority
  • Disallowed
  • My
  • Root
  • TrustedPeople
  • TrustedPublisher

Alternatively, it may be any other store including:

  • WebHosting

The default is the My (ie personal) store.

StoreLocation [optional]

For certificates in a Windows certificate store, the store location specifies the location.

The store location may be:

  • CurrentUser
  • LocalMachine

The default is the local machine.

SerialNumber [optional]

For certificates in a Windows certificate store, the certificate is specified by its serial number.

Thumbprint [optional]

For certificates in a Windows certificate store, the certificate is specified by its thumb print.

SubjectName [optional]

For certificates in a Windows certificate store, the certificate is specified by its subject name.

Key [optional]

For certificates in an Azure key vault, the certificate is specified by its configuration key.

DisableValidationCheck [optional]

The flag specifies whether certificate validation is disabled.

The default is false.

URL

Local and partner provider URLs may be absolute or relative.

URLs are relative to the host name and port number of the current HTTP request.

For example, an assertion consumer service URL may be specified absolutely.

https://localhost:44360/SAML/AssertionConsumerService

Alternatively, it may be specified as a path.

/SAML/AssertionConsumerService

This is converted to an absolute URL using the base URL of the current HTTP request.

Although the more common use case it to specify relative local URLs, relative partner URLs may be specified if, for example, the local and partner provider are installed on the same server.