Skip to content

IdentityProviders Element

Jump to bottom
Michael Hallock edited this page Jan 2, 2018 · 5 revisions

The <identityProviders> element specifies configuration information for the Identity Providers. The minimal configuration for this element specifies the directory in which the metadata of the federation partners can be found, but other elements are exposed to allow for overriding the metadata.

In addition, automatic fetching of identity provider metadata at application start can be configured using the optional [Metadata Fetcher Module](Metadata Fetcher Module).

The <identityProviders> element exposes the following attributes:

Attribute Use
metadata The path to the directory where the metadata of the federation partners can be found. Make sure that the directory is readable by the user running the web server.
idpSelectionUrl URL for custom webpage that lets the user select from a list of available IDP’s. The attribute is used only when no common domain cookie is set, and no add-element (see below) has the default-property set to true. In case no idpSelectionUrl is specified, a default IDPSelectionPage is displayed.

The <identityProviders> element can also override default Identity Provider settings by adding them manually:

<saml2>
    ...
    <identityProviders metadata="C:\Path\To\Metadata\Directory">
    <add id="default.idp.com" />
    <add id="test.idp.com" />
    </identityProviders>
    ...
</saml2>

Each identity provider has the following attributes:

Attribute Use
id The id of the federation partner to which this configuration pertains. This id must have a match in one of the metadata files that are known by the service provider.
default (Optional) When set to true, this IdP will be used for authentication in case no Common Domain Cookie is set. If no IdP has default set to true, and more than one IdP is present in the IDPEndPoints collection, the user will be prompted to select from the list of IdP’s.
name (Optional) Contains a human-readable name for the federation partner. The name will replace the federation partner’s id, in cases where it is necessary to present the user with a choice of federation partners.
allowUnsolicitedResponses (Optional) Set this value to true if unsolicited responses should be allowed, for instance to allow for IDP initiated sign on.
omitAssertionSignatureCheck (Optional) Set this value to true if for some reason you do not wish the signature of the assertions from this IdP to be checked (for example if assertions are not signed).
forceAuth (Optional) Force authentication on each AuthnRequest.
isPassive (Optional) AuthnRequests are passive.

In addition, each identity provider can contain the following elements to further override default behaviors and metadata files.

Element Use
<endpoints> Configuration of the endpoints of the federation partner. The <endpoint> elements has only three attributes; type to specify the type of endpoint (SignOn or Logout), url for specifying the endpoint location, and binding, which specifies the binding type to use. Possible values for binding are "Post", "Redirect", and "Artifact".
<attributeQuery> (Optional) Lets you enable httpBasicAuth with username and password for attribute queries.
<artifactResolution> (Optional) Lets you enable httpBasicAuth with username and password for artifact resolution.
<certificateValidations> (Optional) Allows for setting the certificate validation type, in cases where default certificate chain checks will fail (e.g. when using self-signed certificates)
<persistentPseudonym> (Optional) Allows for specifying a custom mapper class for <Subjects> with the NameIDFormat of "persistent". This class will be used in setting the Saml20Identity principal's Name property, and will translate the <Subject> value to another, local identity name if required.
<commonDomainCookie> (Optional) Allows for setting common domain cookie settings for the identity provider. Key/value based. If used, "idpCookieWriterEndPoint" and "localReturnUrl" must be present.

Endpoints

The <endpoints> element defines the endpoints for the identity provider. This is an optional element, which is useful for overriding the identity provider's metadata for SignOn and Logout endpoints.

Each <endpoint> element exposes the following attributes for modification:

Attribute Use
type Specifies the type of endpoint. Can be one of "SignOn", "Logout", or "Metadata".
binding Specifies the binding to use for this endpoint. Can be one of "Post", "Redirect", "Soap", or "Artifact".
url The endpoint URL.
forceProtocolBinding (Optional) Allows for overriding the protocol binding for a given endpoint. Must be the fully qualified URI of a valid SAML binding type.
tokenAccessor (Optional) Allows for specifying a custom "TokenAccessor", which will preprocess the identity provider's response.

An example which overrides the default metadata SignOn and Logout endpoints is below.

<saml2>
    <identityProviders metadata="METADATALOCATION">
    <add id="IdProvider" default="true">
        <endpoints>
        <endpoint type="SignOn" url="http://www.example.com/signon" binding="POST" />
        <endpoint type="Logout" url="http://www.example.com/logout" binding="POST" />
        </endpoints>
    </add>
    </identityProviders>
</saml2>

CertificateValidations

The <certificateValidations> element allows for specifying how an identity provider's signing certificate should be validated. Two specifications are included, but custom implementations can also be injected using this element.

DefaultCertificateSpecification will validate a certificate according to standard conventions, including checking the certificate chain's validity.

SelfIssuedCertificateSpecification will validate a certificate according to standard conventions, but will not validate the certificate chain (useful for instances where self-signed certificates are being used for signing instead of valid commercial cirtificates).

Below is an example of an identity provider that uses self-signed certificates for signing.

<saml2>
    <identityProviders metadata="METADATALOCATION">
    <add id="IdProvider" default="true">
        ...
        <certificateValidations>
        <add type="SAML2.Specification.SelfIssuedCertificateSpecification, SAML2" />
        </certificateValidations>
    </add>
    </identityProviders>
</saml2>

AttributeQuery and ArtifactResolution

The <attributeQuery> and <artifactResolution> elements allow for turning on HTTP Basic Auth for attribute queries and artifact resolution.

Each element defines the following attributes:

Attribute Use
enableHttpBasicAuth Turns HTTP Basic Auth on or off. Must be "true" or "false".
username The username to use for HTTP Basic Auth.
password The password to use for HTTP Basic Auth.

PersistentPseudonym

The <persistentPseudonym> element allows for specifying a mapper for <Subjects> that use the "persistent" NameIDFormat. This is useful for when the "username" used by your MembershipProvider different from the value returned in the <Subject> element of a SAML response, and allows for converting that value to the local equivalent.

Attribute Use
mapper Allows for setting the assembly qualified name of a IPersistentPseudonymMapper that will handle translations between the returned persistent NameID SAML Subject and local equivalents.

Examples

Below is an example of an identity provider which overrides the default metadata endpoints, turns on httpBasicAuth for both AttributeQuery and ArtifactResolution, and sets the CertificateValidation to use the SelfIssuedCertificateSpecification (for self-signed certificates).

<saml2>
    <identityProviders metadata="METADATALOCATION">
    <add id="IdProvider" default="true">
        <endpoints>
        <endpoint type="SignOn" url="http://www.example.com/signon" binding="POST" />
        <endpoint type="Logout" url="http://www.example.com/logout" binding="POST" />
        </endpoints>
        <attributeQuery enableHttpBasicAuth="true" username="username" password="p@assw0rd" />
        <artifactResolution enableHttpBasicAuth="true" username="username" password="p@assw0rd" />
        <certificateValidations>
        <add type="SAML2.Specification.SelfIssuedCertificateSpecification, SAML2" />
        </certificateValidations>
    </add>
    </identityProviders>
</saml2>
Clone this wiki locally