SAML

SAML Proxying

This section describes SAML proxying in DirX Access, which enables the delegation of initial user authentication in SAML Web SSO federation from the local SAML IdP endpoint to external SAML IdP endpoints.

SAML proxying is performed in a system that comprises the following entities:

  • An SP and an external SAML SP endpoint.

  • An authentication IdP and an external SAML IdP endpoint.

  • A proxying IdP and a combination of local SAML IdP and auxiliary SAML SP endpoints.

The SAML SP and the authentication SAML IdP are not (necessarily) aware of SAML proxying.

Deployment Steps

A proxying IdP combines a traditional SAML authentication IdP endpoint (implementing SAML SingleSignOnService in particular) and a traditional SAML SP endpoint (implementing SAML assertionConsumerService). The DirX Access Manager enables you to deploy both components under Federation | Web | SAML section. For further details on configuration see the Administrative tasks chapter of this guide.

After deployment DirX Access Manager creates the following SAML FEP applications under the Services webapps folder during the Services deployment:

  • saml-idp - a traditional SAML IdP FEP component where clientId in web.xml matches a clientId specified in the SAML IdP Proxying FEP Web application configuration data.

  • saml-sp - an auxiliary SAML SP FEP where clientId in web.xml matches the clientId from the configuration data.

Configuration Steps

When no corresponding FEP configuration data are specified during the SAML IdP Proxying FEP deployment, the following default SAML FEP Endpoint configuration objects are created during the deployment:

  • dxa-config:SamlIdPEndpoint, the SAML IdP FEP configuration with Identifier matching the SAML IdP Proxying FEP’s Component identifier in the deployment data.

  • dxa-config:SamlSPEndpoint, the auxiliary SAML SP FEP configuration with Identifier matching the Component identifier suffixed with the - IdP internal SP-FEP string.

Triggering SAML Proxying at the Client

SAML proxying is employed if the following conditions are true:

  • the incoming request contains an element that specifies a list of accepted authentication SAML IdP endpoints, and

  • the SAML IdP endpoint that processes this is not on the list.

For DirX Access SAML SP endpoints, the content of the element is controlled by the initial SP-FEP request. The entity IDs of the authentication SAML IdP endpoints are specified in values of the DXASAMLProxying HTTP request parameter.

The element can also contain a ProxyCount attribute that specifies the number of proxying indirections permissible between the identity provider that receives the initial request and the identity provider that ultimately authenticates the principal. The presence and value of this attribute is driven by the DXAProxyCount HTTP request parameter in the initial SAML SP endpoint request.

Voluntary Configuration Options

SAML IdP endpoints may restrict the usage of the issued assertion with respect to eventual proxying; that is, using the assertion by another SAML IdP endpoint to issue another assertion for a certain subject. There are two main means of proxy restriction; both are configured in the SAML assertion construction template configuration properties:

  • SAML proxy restriction audience.

  • SAML proxy maximum count.

SAML SP endpoints may also place restrictions with respect to proxying. Specifically, SPs set the limit of indirections between the AuthenticationRequest receiver and the entity that authenticates the subject. DirX Access SAML SP FEPs honor the ProxyCount that is set in an incoming . Nonetheless, if there is no ProxyCount in an incoming , then a default value is imprinted. The default is set in DirX Access SAML SP endpoint configuration property:

  • Default proxy count

Upon receiving an AuthenticationRequest without a proxying requirement, the SAML Proxying IdP can either perform initial user authentication locally or trigger SAML proxying and redirect a user to the SP part of SAML Proxying IdP and show the WAYF page. This behavior is controlled by the DirX Access SAML IdP endpoint configuration property:

  • Do allow initial authentication

Preconfigured SAML Service Providers

DirX Access supports preconfigured SAML Service Providers that allow administrators to easily establish SAML-based interoperability with well-known providers such as Google or Salesforce, including parameterizing provider instances and creating custom templates for other preconfigured SPs or IdPs.

The functionality is built into the DirX Access Server and DirX Access FEPs, allowing you to use or change preconfigured SPs at runtime. More specifically, the preconfigured SPs support is an extension of the SAML metadata configuration. In addition to the option to define static metadata, it is possible to define a pointer to an XML template and a set of parameters. An XSLT transformation derives the metadata instance from these items. An XML template () is a new configuration abstraction that encapsulates a set of XSLT templates and XML documents and defines a root template and root document that serve as the entry points for an XSLT transformation. DirX Access installation contains the definition of XML templates for two well-known SPs: Google and Salesforce. DirX Access administrators can easily create other templates at deployment or runtime.

Configuration Logic and Required Items

Configuration of preconfigured SAML SPs is based on the following elements from the dxa-configuration.xsd configuration XML schema:

  • <dxa-config:XmlTemplate>, which defines XSTL transformation object with one or more parametrical XSLT template(s) and XML document. For each preconfigured SAML SP exactly one instance of this object must exist in DirX Access configuration repository.

  • <dxa-config:SamlMetadata>, which defines a dynamic SAML metadata object via referencing the XSTL transformation object and defining values for XSLT template parameter(s).

Details on these configuration elements are described in the dxa-configuration.xsd configuration XML schema, which is available under the DirX Access installation folder ClientSDK\Integration\WebServicesCommunications\wsdl\configuration.

<dxa-config:SamlMetadata>

Since DirX Access V8.3, the configuration object can contain either the immediate value of SAML metadata or a reference to an XML template and template parameters. The preconfigured SP functionality uses the latter approach. Regardless of the approach, the object can be used the same way, for example, to define peer SAML metadata for a FEP. If the object contains an XmlTemplateId, the template is used to generate SAML metadata via XSLT transformation; otherwise, the content of the SamlMetadata child node is directly used as SAML metadata.

  • XmlTemplateId: Reference to a node. If not filled in (null) then the content of the SamlMetadata field is utilized. Otherwise, the specified template is used to generate the metadata.

  • XmlTemplateParameters: The parameters to be used when generating the metadata via the XSLT transformation that is defined by the referred XmlTemplate.

  • SamlMetadata: The immediate value.

<dxa-config:XmlTemplate>

This configuration object defines an XSLT transformation. It holds a key-value map of resources that include XSLT templates and documents. The configuration object also defines a root document and a root template. These two references specify with what template and what document the XSLT transformation is to be started. The other resources can be fetched via a resolver during the XSLT execution based on the references encountered.

  • RootTemplateId: A key of an entry in the ResourceMap. This entry contains the root XSLT template to be passed to the XSLT transformation engine.

  • RootDocumentId: A key of an entry in the ResourceMap. This entry contains the root document to be passed to the XSLT transformation engine.

  • ResourceMap: A key-value map containing XSLT transformation resources.

The keys (resource identifiers) must be absolute URIs; the resolver in the templates resolves relative URIs with the respect to the current resource’s URI and tries to locate the resulting absolute URI in the resource map. Therefore, using relative URIs is correct in the templates, but the keys must be absolute. An unused URI schema like resource:// is suggested for making the paths absolute.

Configuration Steps

Configuration consists of four steps. If you want to use Google SP or Salesforce SP, you can skip steps (1) and (2); templates for these providers are included in the DirX Access product data by default.

  1. Define <dxa-config:ConfigurationData>.

  2. Import <dxa-config:ConfigurationData>.

  3. Define <dxa-config:SamlMetadata>.

  4. Refer to <dxa-config:SamlMetadata>.

Define dxa-config:ConfigurationData

Create an instance containing a template, see the section “Configuration Logic and Required Items” above.

Import dxa-config:ConfigurationData

Perform this step via the DirX Access Console.

Define dxa-config:SamlMetadata

Define a SamlMetadata object that refers to the appropriate template and fill in the parameters of the template. The DirX Access Manager interface provides a convenient interface for this purpose, including the descriptions of all parameters.

Refer to dxa-config:SamlMetadata

Imported XSLT-template-based object(s) can be referred to in the same way as static SamlMetadata object(s). Typically, a preconfigured SP will be assigned to a SAML IdP FEP as a peer. Perform this step with DirX Access Manager, DirX Access Console or via delegates.