Integration of Dynamic Automated Metadata Exchange into the SAML 2.0 Web Browser SSO Profile

In a federated identity management scenario, enabling communication between an identity provider and a service provider is possible within trust boundaries, which typically entails joining one or several federations before the exchange of metadata takes place. The exchange of SAML metadata is out of scope of the SAML specifications, but normally done by pre-sharing metadata files of all entities within the trust boundaries. This document specifies the HTTP-based integration of SAML metadata exchange into the SAML2 Web Browser SSO profile. Focusing on the automation and the on-demand initiation of the metadata exchange between an identity provider and a service provider to build a form of opportunistic trust, even if these do not share membership in a common federation a-priori or if regular federation scenarios are not suitable. This could be the case in projects containing partners outside regular federations. The initiation of the metadata exchange starts after the identity provider discovery in order to keep the user experience consistent with traditional federation-based service access. This document specifies the initiation of the metadata exchange but does not anticipate the use of either a public metadata registry or the metadata query itself. The metadata exchange is triggered by a trusted third party, which does not interfere in further communication once identity provider and service provider have successfully exchanged their metadata. In contrast to identity provider proxies, the trusted third party does not cache assertions nor is it involved in subsequent communication. Integrated identity provider discovery, the mutual exchange of required SAML metadata, and user authentication take place in a fully automated, user-initiated, and on-demand manner. To provide a flexible solution, either pull-based metadata exchange, such as the SAML Profile for MD Query , or any kind of push mechanism can be used. The degree of integration chosen for DAME explicitly does not imply that disclosing personally identifiable information is required from an identity provider by sending it to any particular service provider. This is left to appropriate means, e.g., explicitly acquiring user consent, in compliance with regulations and policies. The described integration addresses the protocol, content and processing of SAML messages for interoperability, referring to , but also specifies some deployment details and phases for cross-boundary trust. Fitting in seamlessly with implemented SAML-based SSO workflows and being scalable for a large number of users and entities without exceeding administrative procedures, it enables to participate in dynamically set up federations.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

This document uses identity management terminology from and . In particular, this document uses the terms identity provider, service provider and identity management. Furthermore, it uses following terminology: Entity - A single logical construct for which metadata is provided. This is usually either a service provider (SP) or an identity provider (IDP). Metadata - The SAML metadata specification is a machine-readable description of certain entity characteristics and contains information about, e.g., identifiers, endpoints, certificates and keys. Trusted Third Party - An intermediate entity facilitating interaction between different entities, which trust the third party (TTP).

Based on , SAML profiles define rules how to embed SAML assertions in or combine them with other objects as files or protocol data units of communication protocols. The profile defined in this document is based on the existing SAML Web Browser SSO profile, which implements the SAML Authentication Request protocol enhanced by a trusted entity between an originating party (IDP) and a receiving party (SP). A SAML binding maps request-response messages of the SAML protocol onto standard communication protocols. For compliance reasons with the underlying Web Browser SSO profile, the SAML HTTP Redirect and HTTP POST Bindings MUST be used. SAML metadata information MUST be extended to support this protocol. For each entity a MetadataSyncLocation MUST be defined, e.g., for an IDP idp.example.net. To ensure conformity and uniqueness of the attribute the URN namespace for GEANT MUST be used:

https://idp.example.net/idp/profile/SAML2/DAME ]]>

The protocol defined in this document MUST be divided into two phases: Discovery of the appropriate IDP User authentication on behalf of the SP through a TTP User authentication to TTP On-demand metadata exchange User authentication to SP The protocol defined in this document primarily adds the on-demand metadata exchange between IDP and SP, which is triggered by the user. The exchange of the metadata itself is explicitly out of scope. The authentication to the TTP step in the latter phase is required due to the security considerations discussed below.

entityID - Specifies the unique identity of an entity, whose metadata is exchanged, as specified in and .

A web user attempts to access a secured resource provided by a SP via an HTTP user agent. Missing an established technical trust relationship, a certain IDP MUST be discovered by the discovery functionality that is integrated into or accessible via the TTP.

| | | | | |---HTTP Redirect----| | | | | |--------------------------HTTP Request----->| | | | |<------Selection of identity provider ----->| | | | |--------------------------HTTP Redirect-----| | | | |---HTTP Request---->| | | | | ]]> Figure 1: Identity provider discovery.

Analogous to the SAML identity provider discovery profile , the SP redirects the user agent to the TTP with an HTTP GET request including the REQUIRED or OPTIONAL parameters specified in . In distinction to the existing discovery profile, the OPTIONAL "isPassive" parameter, which controls the visible interaction with the user agent, SHOULD NOT be set to "true" in this profile. If the parameter "isPassive" is used, the request sent to the TTP MUST contain the entityID of the IDP as a URL query. The URL query is indicated by the '?' operator, followed by variable name entityID, '=', and the variable's value . This template provides both a structural description and machine-readable instructions. The URLs of the participating entities MUST be known to the TTP through the metadata. The URLs depend on the implementation and MAY include the literal string "DAME" as query , indicating the usage of this profile for dynamic automated metadata exchange.

The TTP MUST respond by redirecting the user agent back to the requesting SP with an HTTP GET request message to the location specified in the return parameter of the original request. The unique identifier of the selected IDP MUST be included as value of the query string parameter specified as returnIDParam or the entityID if no parameter was supplied.

If the IDP was not determined or the discovery service cannot answer or an unspecified communication error occurs, the discovery service MAY halt further processing, either displaying an error message to the user agent or redirecting the user agent back to the SP.

After receiving the information about the selected IDP it is RECOMMENDED that the SP verifies acceptance. If the IDP has not been accepted, the SP halts processing and displays an error message to the user agent.

In the second phase of the protocol user authentication MUST be performed. The trusted third party relays the SP's authentication request to the IDP. For this step, the authentication request of the SP is cached and a new authentication request is sent to the IDP as both entities do not have previously exchanged their metadata. These authentication requests are REQUIRED to ensure that a metadata exchange will be initiated only if the user has successfully been authenticated by the selected IDP.

| | | | | | |--------------------HTTP Redirect---| | | | | | |----------------------------------------AuthRequest2--->| | | | | |<-----------------User authentication------------------>| | | | | | | |<---AuthResponse2--| | | | | | | |----MDI Request--->| | | | | | | |<---MDI Response---| | | | | | |<----MDI Request---| | | | | | | |---MDI Response--->| | | | | | |--------------------HTTP Redirect---| | | | | | |----------------------------------------AuthRequest1--->| | | | | | |<-----------AuthResponse1--------------| | | | | |<-HTTP Response-| | | | | | | ]]> Figure 2: User authentication Request Protocol using a TTP.

In the first sub-phase the user MUST be authenticated by the selected identity provider, but in distinction to , the trusted third party initiates the authentication.

After accepting the selected IDP, the SP creates and sends a SAML Authentication Request message (AuthnRequest) to the TTP using an HTTP Redirect to transfer the message through the user agent. It is RECOMMENDED that this request message is signed or otherwise authenticated and integrity-protected by the requesting SP.

The TTP MUST temporarily store the SAML AuthnRequest message by means out of scope of this specification.

After that, a second SAML AuthnRequest message MUST be sent by the trusted third party to the selected IDP using a HTTP redirect message to authenticate the user. The OPTIONAL "ForceAuthn" parameter MAY be included in the request. The AuthnRequest message SHOULD be signed or otherwise authenticated and integrity protected by the TTP or by the protocol binding used to deliver the message.

The user MUST be identified and authenticated by the IDP by some means out of scope of this profile. A new authentication SHOULD be performed unless the IDP can rely on a previously authenticated session. A previous session MUST NOT be reused if the request contains a "ForceAuthn" parameter.

The IDP MUST issue a SAML AuthnResponse message to the TTP containing one or more assertions or an error message with a status describing the error occurred. The HTTP POST binding MUST be used to transfer the message. It is RECOMMENDED that the message is signed by the IDP or otherwise authenticated or integrity-protected.

In the second sub-phase, the metadata of SP and IDP are exchanged in a way that is orchestrated and synchronized by the TTP.

After the user has been authenticated, the TTP MUST initiate the metadata integration (MDI) between IDP and SP by a metadata integration request. The URL sent to the entities for the MDI request SHOULD contain the query elements {?action,entityID}. The variable name 'action' MUST be followed by '=' and the variable's value 'fetchmetadata'. The variable name 'entityID' is followed by '=' and the variable's value. The means used for the metadata exchange are implementation-dependent. The TTP MAY trigger a metadata query as described by the work in progress about the Metadata Query Protocol and the SAML Profile for the Metadata Query Protocol . IDP and SP MUST integrate each other's metadata in their configuration. It is RECOMMENDED that the IDP is triggered regarding metadata integration before the SP because it MAY object to accepting certain service providers. But any kind of concurrent operation MAY be supported. It is RECOMMENDED that the TTP queries the IDP before the metadata exchange because it MAY be the case that the IDP has already integrated the SP's metadata. The IDP SHOULD then indicate the found metadata by the appropriate HTTP status code according to .

After each other's metadata is integrated, each entity MUST send a metadata integration response message to the TTP containing the status of the integration by the HTTP status code. If an entity was not able to integrate the metadata before sending the response, the status MUST indicate this state and a new request MUST be sent by the entity containing the status after the integration. If an error occurs integrating the metadata, the message MUST contain a HTTP status code describing the error and the TTP MUST halt further processing by displaying an error message to the user agent. It is RECOMMENDED to roll back any configuration changes by some means out of scope of this specification.

In last step the stored AuthnRequest of the SP MUST be presented by the TTP to the IDP if no error occurred beforehand. Because of the successful user authentication already initiated by the trusted third party, the IDP SHOULD respond with an assertion transferred to the service provider without further act of authentication, except for the case where the request contains a "ForceAuthn" parameter. The IDP MUST issue a SAML AuthnResponse message to the services provider's AssertionConsumerServiceURL. After receiving the response, the SP MUST decide if the user gets access to the requested resource based on the information contained within the SAML assertion.

Considering two organizations, SP S (sp.example.com) and identity provider I (idp.example.net). User U initiates the SAML metadata exchange between these entities using an user agent through the TTP T (ttp.example.org).

After requesting access to a secured resource via HTTPS, S redirects U to the discovery service of T:

U selects an appropriate IDP I. T redirects U back to S using the following message:

Receiving U's selection, S redirects the user to T containing a SAML authentication request (AuthnRequest1):

T temporarily stores the authentication request and redirects U to I sending a second authentication request (AuthnRequest2) containing the SAML request:

After successful authentication, I issues a SAML authentication response message to T:

As U is successfully authenticated, I and S are triggered to fetch each others metadata by T using the appropriate TTPMetadataSyncLocation defined in the entity's SAML metadata, e.g., /idp/profile/SAML2/DAME:

The entities download the metadata from T using, e.g., SAML Profile for Metadata Query Protocol . Only I's messages to download S's metadata are presented here, S's messages are equivalent:

... ]]> T sends a request to I and S in order to receive the status of the integration:

I answeres with:

After successful completion T forwards S's authentication request to I:

I answers to S's AssertionConsumerServiceURL with a SAML Response:

Receiving the SAMLResponse, S redirects U to the requested resource:

As SAML metadata contains information necessary for the secure operation of interacting services, it is strongly RECOMMENDED that a mechanism for integrity checking is provided to clients. This MAY include the use of SSL/TLS at the transport layer, digital signatures present within the metadata document, or any other such mechanism. It is RECOMMENDED that the integrity checking mechanism provided by a responder is a digital signature embedded in the returned metadata document, as defined by section 3: - SHOULD use an RSA key pair whose modulus is no less than 2048 bits in length. - SHOULD NOT use the SHA-1 cryptographic hash algorithm as a digest algorithm. - MUST NOT use the MD5 cryptographic hash algorithm as a digest algorithm. - SHOULD otherwise follow current cryptographic best practices in algorithm selection.

In many cases service metadata is public information and therefore confidentiality SHOULD NOT be required. In those cases, where such functionality is required, it is RECOMMENDED that both the requester and responder support SSL/TLS. Other mechanisms, such as XML encryption, MAY also be supported for privacy concerns.

This protocol mandates the authentication of users before any trust between SP and IDP is technically established. Although this requires a further step for users, it protects against inappropriate usage of the user-initiated trust establishment process. An example of inappropriate usage is triggering the metadata exchange for an IDP, where the user has no account. Therefore, the user MUST be authenticated before the metadata is exchanged.

This protocol enables the user to trigger the SAML metadata exchange between two entities and establish the bi-directional technical trust relationship. This is a prerequisite of the subsequent exchange of user information. For entities, which require a higher level of trust, it is RECOMMENDED to make use of one ore more additional mechanisms, e.g., the usage of flags in metadata, implementation depending mechanisms in order to secure sensitive information, or to take organizational measures, such as requiring written contracts between SPs and IDPs.

This document has no actions for IANA.

The research leading to these results has received funding from the European Community's Seventh Framework Programme under grant agreement no 605243 (GN3plus).