Forums, Documentation & Knowledge Base - ComponentSpace

SAML Configuration


http://componentspace.com/Forums/Topic37.aspx

By ComponentSpace - 2/20/2014

Configuration information associated with the high level API may be specified:
  • within the saml.config file in the application’s root directory
  • within a SAML configuration file in some other directory
  • programmatically

If specified within a file, the syntax must comply with the following XML schema.
Any errors in the configuration will be reported when the configuration is first loaded.

SAML Configuration XML Schema

The XML schema file is attached to this topic.


<?xml version="1.0" encoding="utf-8"?>
<!-- This schema defines the SAML configuration syntax. -->
<schema targetNamespace="urn:componentspace:SAML:2.0:configuration"
        xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:saml="urn:componentspace:SAML:2.0:configuration"
        elementFormDefault="qualified">

  <!-- SAML configuration -->
  <element name="SAMLConfiguration" type="saml:SAMLConfigurationType"/>

  <complexType name="SAMLConfigurationType">
    <sequence>
      <element name="IdentityProvider" type="saml:IdentityProviderType" minOccurs="0"/>
      <element name="ServiceProvider" type="saml:ServiceProviderType" minOccurs="0"/>
      <element name="PartnerIdentityProvider" type="saml: PartnerIdentityProviderType" minOccurs="0" maxOccurs="unbounded"/>
      <element name="PartnerServiceProvider" type="saml: PartnerServiceProviderType" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
    <attribute name="ReloadOnConfigurationChange" type="boolean" default="true"/>
    <attribute name="TraceLevel" type="saml:TraceLevelType"/>
  </complexType>

  <!-- Identity Provider -->
  <complexType name="IdentityProviderType">
    <complexContent>
      <extension base="saml:LocalProviderType"/>
    </complexContent>
  </complexType>

  <!-- Service Provider -->
  <complexType name="ServiceProviderType">
    <complexContent>
      <extension base="saml:LocalProviderType">
        <attribute name="AssertionConsumerServiceUrl" type="string" use="required"/>
      </extension>
    </complexContent>
  </complexType>

  <!-- Partner Identity Provider -->
  <complexType name="PartnerIdentityProviderType">
    <complexContent>
      <extension base="saml: PartnerProviderType">
        <attribute name="SingleSignOnServiceUrl" type="string"/>
        <attribute name="SingleSignOnServiceBinding" type="saml:SAMLBindingType" default="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
        <attribute name="SignAuthnRequest" type="boolean" default="false"/>
        <attribute name="ForceAuthn" type="boolean" default="false"/>
        <attribute name="WantSAMLResponseSigned" type="boolean" default="false"/>
        <attribute name="WantAssertionSigned" type="boolean" default="false"/>
        <attribute name="WantAssertionEncrypted" type="boolean" default="false"/>
        <attribute name="DisableAudienceRestrictionCheck" type="boolean" default="false"/>
        <attribute name="OverridePendingAuthnRequest" type="boolean" default="false"/>
        <attribute name="RequestedAuthnContext" type="string"/>
        <attribute name="ProviderName" type="string"/>
      </extension>
    </complexContent>
  </complexType>

  <!-- Partner Service Provider -->
  <complexType name="PartnerServiceProviderType">
    <complexContent>
      <extension base="saml: PartnerProviderType">
        <attribute name="AssertionConsumerServiceUrl" type="string"/>
        <attribute name="WantAuthnRequestSigned" type="boolean" default="false"/>
        <attribute name="SignSAMLResponse" type="boolean" default="false"/>
        <attribute name="SignAssertion" type="boolean" default="false"/>
        <attribute name="EncryptAssertion" type="boolean" default="false"/>
        <attribute name="AssertionLifeTime" type="string" default="00:03:00"/>
        <attribute name="AuthnContext" type="string" default="urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified"/>
      </extension>
    </complexContent>
  </complexType>

  <!-- Local and partner provider types -->
  <complexType name="LocalProviderType" abstract="true">
    <complexContent>
      <extension base="saml: ProviderType"/>
    </complexContent>
  </complexType>

  <complexType name="PartnerProviderType" abstract="true">
    <complexContent>
      <extension base="saml: ProviderType">
        <attribute name="PartnerCertificateFile" type="string"/>
        <attribute name="PartnerCertificateSerialNumber" type="string"/>
        <attribute name="PartnerCertificateThumbprint" type="string"/>
        <attribute name="PartnerCertificateSubject" type="string"/>
        <attribute name="SingleLogoutServiceUrl" type="string"/>
        <attribute name="SingleLogoutServiceResponseUrl" type="string"/>
        <attribute name="SingleLogoutServiceBinding" type="saml:SAMLBindingType" default="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
        <attribute name="LogoutRequestLifeTime" type="string" default="00:03:00"/>
        <attribute name="DisableInboundLogout" type="boolean" default="false"/>
        <attribute name="DisableOutboundLogout" type="boolean" default="false"/>
        <attribute name="DisableInResponseToCheck" type="boolean" default="false"/>
        <attribute name="SignLogoutRequest" type="boolean" default="false"/>
        <attribute name="SignLogoutResponse" type="boolean" default="false"/>
        <attribute name="WantLogoutRequestSigned" type="boolean" default="false"/>
        <attribute name="WantLogoutResponseSigned" type="boolean" default="false"/>
        <attribute name="UseEmbeddedCertificate" type="boolean" default="false"/>
        <attribute name="NameIDFormat" type="string" default="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"/>
        <attribute name="DigestMethod" type="saml: DigestMethodType" default="http://www.w3.org/2000/09/xmldsig#sha1"/>
        <attribute name="SignatureMethod" type="saml:SignatureMethodType" default="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
        <attribute name="KeyEncryptionMethod" type="saml:KeyEncryptionMethodType" default="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
        <attribute name="DataEncryptionMethod" type="saml: DataEncryptionMethodType" default="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
        <attribute name="ClockSkew" type="string" default="00:03:00"/>
      </extension>
    </complexContent>
  </complexType>

  <complexType name="ProviderType" abstract="true">
    <attribute name="Name" type="string" use="required"/>
    <attribute name="LocalCertificateFile" type="string"/>
    <attribute name="LocalCertificatePassword" type="string"/>
    <attribute name="LocalCertificatePasswordKey" type="string"/>
    <attribute name="LocalCertificateSerialNumber" type="string"/>
    <attribute name="LocalCertificateThumbprint" type="string"/>
    <attribute name="LocalCertificateSubject" type="string"/>
  </complexType>

  <!-- Bindings -->
  <simpleType name="SAMLBindingType">
    <restriction base="string">
      <enumeration value="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
      <enumeration value="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"/>
    </restriction>
  </simpleType>

  <!-- Security -->
  <simpleType name="KeyEncryptionMethodType">
    <restriction base="string">
      <enumeration value="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
      <enumeration value="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
    </restriction>
  </simpleType>

  <simpleType name="DataEncryptionMethodType">
    <restriction base="string">
      <enumeration value="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
      <enumeration value="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
      <enumeration value="http://www.w3.org/2001/04/xmlenc#aes192-cbc"/>
      <enumeration value="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
    </restriction>
  </simpleType>

  <simpleType name="DigestMethodType">
    <restriction base="string">
      <enumeration value="http://www.w3.org/2000/09/xmldsig#sha1"/>
      <enumeration value="http://www.w3.org/2001/04/xmlenc#sha256"/>
    </restriction>
  </simpleType>

  <simpleType name="SignatureMethodType">
    <restriction base="string">
      <enumeration value="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
      <enumeration value="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
    </restriction>
  </simpleType>
 
  <!-- Trace -->
  <simpleType name="TraceLevelType">
    <restriction base="string">
      <enumeration value="Off"/>
      <enumeration value="Verbose"/>
    </restriction>
  </simpleType>
</schema>


The following sections described the SAML configuration. 

SAML Configuration
IdentityProvider
The optional IdentityProvider element specifies the configuration for the application when acting as an identity provider.
ServiceProvider
The optional ServiceProvider element specifies the configuration for the application when acting as a service provider.
PartnerIdentityProvider
The optional PartnerIdentityProvider element specifies the configuration for a partner identity provider.
PartnerServiceProvider
The optional PartnerServiceProvider element specifies the configuration for a partner service provider.
ReloadOnConfigurationChange
The optional ReloadOnConfigurationChange attribute specifies whether the application should be reloaded if the configuration changes. The default is true.
TraceLevel
The optional TraceLevel attribute specifies the trace level for logging.
Tracing configuration is specified in the application’s web.config. Refer to section 15.1 for more details. The trace switch value in the <system.diagnostics> section specifies whether verbose trace is enabled or not.
The trace switch may be overridden by specifying a trace level. For example, if the trace switch value in <system.diagnostics> is Off, the trace level may be set to Verbose to enable trace without modifying web.config.
In most scenarios, it’s preferable to modify the trace switch value in <system.diagnostics>.
By default, the trace level is not specified and therefore the trace switch value in <system.diagnostics> applies.
Identity Provider Configuration
There is no identity provider specific configuration.
Service Provider Configuration
AssertionConsumerServiceUrl
The AssertionConsumerServiceUrl attribute specifies the application’s assertion consumer service (ACS) URL. SAML responses will be received at the ACS.
Partner Identity Provider Configuration
SingleSignOnServiceUrl
The optional SingleSignOnServiceUrl attribute specifies the partner identity provider’s single sign-on (SSO) service URL. Authentication requests will be sent to the SSO service. This is only required for SP-initiated SSO.
SingleSignOnServiceBinding
The optional SingleSignOnServiceBinding attribute specifies the transport binding to use when sending authentication requests to the partner identity provider’s SSO service. The default is to use the HTTP-Redirect binding.
SignAuthnRequest
The optional SignAuthnRequest attribute specifies whether authentication requests sent to the partner identity provider should be signed. The default is false.
ForceAuthn
The optional ForceAuthn attribute specifies whether to set the force authentication attribute in authentication requests. The default is false.
WantResponseSigned
The optional WantResponseSigned attribute specifies whether the SAML response from the partner identity provider should be signed. The default is false.
WantAssertionSigned
The optional WantAssertionSigned attribute specifies whether the SAML assertion from the partner identity provider should be signed. The default is false.
WantAssertionEncrypted
The optional WantAssertionEncrypted attribute specifies whether the SAML assertion from the partner identity provider should be encrypted. The default is false.
DisableAudienceRestrictionCheck
The optional DisableAudienceRestrictionCheck attribute specifies whether the audience restriction condition in the SAML assertion should be checked. This attribute should only be set to true to work around limitations in the partner identity provider. The default is false.
OverridePendingAuthnRequest
The optional OverridePendingAuthnRequest attribute specifies whether a pending authentication request may be overridden and an IdP-initiated SAML response received. Setting this flag to true supports an SP-initiated SSO flow being supplanted by an IdP-initiated SSO. The default is false.
RequestedAuthnContext
The optional RequestedAuthnContext attribute specifies the requested authentication context to include in authentication requests sent to the partner identity provider. The default is none.
ProviderName
The optional ProviderName attribute specifies the provider name to include in authentication requests sent to the partner identity provider. The default is none.
Partner Service Provider Configuration
AssertionConsumerServiceUrl
The optional AssertionConsumerServiceUrl attribute specifies the partner service provider’s assertion consumer service (ACS) URL. SAML responses will be sent to the ACS.
An AssertionConsumerServiceUrl must be configured for IdP-initiated SSO.
For SP-initiated SSO, the assertion consumer service URL included in the authn request from the service provider will be used. If no assertion consumer service URL is included in the authn request then the AssertionConsumerServiceUrl must be configured for SP-initiated SSO.
WantAuthnRequestSigned
The optional WantAuthnRequestSigned attribute specifies whether the authentication request from the partner service provider should be signed. The default is false.
SignSAMLResponse
The optional SignSAMLResponse attribute specifies whether SAML responses sent to the partner service provider should be signed. The default is false.
SignAssertion
The optional SignAssertion attribute specifies whether SAML assertions sent to the partner service provider should be signed. The default is false.
EncryptAssertion
The optional EncryptAssertion attribute specifies whether SAML assertions sent to the partner service provider should be encrypted. The default is false.
AssertionLifeTime
The optional AssertionLifeTime attribute specifies the NotBefore/NotOnOrAfter time interval for the SAML assertion. The format is hh:mm:ss. The default is 3 minutes.
AuthnContext
The optional AuthnContext attribute specifies the authentication context to include in SAML assertions sent to the partner service provider. The default is urn:oasis:names:tc:saml:2.0:ac:classes:unspecified.
Partner Provider Configuration
PartnerCertificateFile
The optional PartnerCertificateFile attribute specifies the X.509 certificate file for this provider. The certificate file name may be an absolute path or a path relative to the application folder.
PartnerCertificateSerialNumber
The optional PartnerCertificateSerialNumber attribute specifies the X.509 certificate by serial number for this provider. The certificate is retrieved from the local computer’s X.509 certificate store.
PartnerCertificateThumbprint
The optional PartnerCertificateThumbprint attribute specifies the X.509 certificate by thumbprint for this provider. The certificate is retrieved from the local computer’s X.509 certificate store.
PartnerCertificateSubject
The optional PartnerCertificateSubject attribute specifies the X.509 certificate by subject name for this provider. The certificate is retrieved from the local computer’s X.509 certificate store.
SingleLogoutServiceUrl
The SingleLogoutServiceUrl attribute specifies the partner provider’s single logout (SLO) service URL. Logout requests will be sent to the SLO service.
SingleLogoutServiceResponseUrl
The SingleLogoutServiceResponseUrl attribute specifies the partner provider’s single logout (SLO) service response URL. Logout responses will be sent to the SLO response service. If not specified then logout responses are sent to the same URL as logout requests.
SingleLogoutServiceBinding
The optional SingleLogoutServiceBinding attribute specifies the transport binding to use when sending logout messages to the partner provider’s SLO service. The default is to use the HTTP-Redirect binding.
LogoutRequestLifeTime
The optional LogoutRequestLifeTime attribute specifies the NotOnOrAfter time interval for the logout request. The format is hh:mm:ss. The default is 3 minutes.
DisableInboundLogout
The optional DisableInboundLogout attribute specifies whether logout requests sent by the partner provider are not supported. The default is false.
DisableOutboundLogout
The optional DisableOutboundLogout attribute specifies whether logout requests sent to the partner provider are not supported. The default is false.
DisableInResponseToCheck
The optional DisableInResponseToCheck attribute specifies whether the SAML message’s InResponseTo should be checked. This attribute should only be set to true to work around limitations in the partner provider. The default is false.
SignLogoutRequest
The optional SignLogoutRequest attribute specifies whether logout requests sent to the partner provider should be signed. The default is false.
SignLogoutResponse
The optional SignLogoutResponse attribute specifies whether logout responses sent to the partner provider should be signed. The default is false.
WantLogoutRequestSigned
The optional WantLogoutRequestSigned attribute specifies whether the logout request from the partner provider should be signed. The default is false.
WantLogoutResponseSigned
The optional WantLogoutResponseSigned attribute specifies whether the logout response from the partner provider should be signed. The default is false.
UseEmbeddedCertificate
The optional UseEmbeddedCertificate attribute specifies whether the certificate embedded in the XML signature should be used when verifying the signature. If false then a configured certificate retrieved from the certificate manager is used. The default is false.
NameIDFormat
The optional NameIDFormat attribute specifies the name identifier format to include in SAML assertions sent to the partner service provider or in authn requests sent to the partner identity provider. The default is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified.
DigestMethod
The optional DigestMethod attribute specifies the XML signature digest method. The default is http://www.w3.org/2000/09/xmldsig#sha1.
SignatureMethod
The optional SignatureMethod attribute specifies the XML signature method. The default is "http://www.w3.org/2000/09/xmldsig#rsa-sha1.
KeyEncryptionMethod
The optional KeyEncryptionMethod attribute specifies the XML encryption key encryption method. The default is http://www.w3.org/2001/04/xmlenc#rsa-1_5.
DataEncryptionMethod
The optional DataEncryptionMethod attribute specifies the XML encryption data encryption method. The default is http://www.w3.org/2001/04/xmlenc#aes128-cbc.
ClockSkew
The optional ClockSkew attribute specifies the time span to allow for differences between local and partner computer clocks when checking time intervals. The default is no clock skew.
Provider Configuration
Name
The Name attribute specifies the name of the provider.
LocalCertificateFile
The optional LocalCertificateFile attribute specifies the X.509 certificate file for this provider. The certificate file name may be an absolute path or a path relative to the application folder.
LocalCertificatePassword
The optional LocalCertificatePassword attribute specifies the password associated with the X.509 certificate file for this provider.
Certificate files (*.pfx) that include the private key should be protected by a password.
Certificate files (*.cer) that do not include a private key are not password protected.
The certificate password must be kept secure. In a test environment using a test certificate, specifying the password using the LocalCertificatePassword attribute is acceptable.
For a production certificate, the password should be stored encrypted in web.config. Refer to the LocalCertificatePasswordKey attribute for more details.
LocalCertificatePasswordKey
The optional LocalCertificatePasswordKey attribute specifies the web.config’s appSettings key for the certificate file password.
For example, if the LocalCertificatePasswordKey attribute value is localCertificatePassword, then under the web.config’s appSettings section, an entry with the key name localCertificatePassword is expected and the entry value is used as the password.
By encrypting the appSettings section using the aspnet_regiis utility, the certificate file password is secured.
LocalCertificateSerialNumber
The optional LocalCertificateSerialNumber attribute specifies the X.509 certificate by serial number for this provider. The certificate is retrieved from the local computer’s X.509 certificate store.
LocalCertificateThumbprint
The optional LocalCertificateThumbprint attribute specifies the X.509 certificate by thumbprint for this provider. The certificate is retrieved from the local computer’s X.509 certificate store.
LocalCertificateSubject
The optional LocalCertificateSubject attribute specifies the X.509 certificate by subject name for this provider. The certificate is retrieved from the local computer’s X.509 certificate store.



By ComponentSpace - 10/7/2019

We refactored the SAML configuration a few years ago and moved some of these properties to a separate ComponentSpace.SAML2.SAMLController class.
Your code should be:


using ComponentSpace.SAML2;

SAMLController.Configuration = samlConfig;