| Network Working Group | D. Poehn |
| Internet-Draft | Leibniz Supercomputing Centre |
| Intended status: Standards Track | May 25, 2016 |
| Expires: November 26, 2016 |
Integration of Dynamic Automated Metadata Exchange into the SAML 2.0 Web Browser SSO Profile
draft-poehn-dame-05
This document specifies the integration of Dynamic Automated Metadata Exchange (DAME) through an intermediate trusted third party into the Security Assertion Markup Language (SAML) 2.0 Web Browser SSO Profile. The user-triggered, on-demand, and fully automated metadata exchange between identity provider (IDP) and service provider (SP) is intended for scenarios in which the a-priori, e.g., federation-based exchange of SAML metadata is neither practical, scalable nor mandatory for non-technical aspects, such as contract-based trust building between IDP and SP. The main benefit of DAME is the removal of waiting times for users and manual setup tasks for IDP and SP administrators before users can access the service. Implementations of DAME can leverage existing metadata repositories, such as REEP, and metadata transfer protocols, such as MD Query.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 26, 2016.
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
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 [RFC7230] integration of SAML metadata exchange into the SAML2 Web Browser SSO [OASIS.saml-profiles-2.0-os] 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 [I-D.young-md-query-saml], 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 [SAML2Int], 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 [RFC2119].
This document uses identity management terminology from [RFC6973] and [OASIS.saml-glossary-2.0-os]. 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 [OASIS.saml-profiles-2.0-os], 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 [OASIS.saml-core-2.0-os] enhanced by a trusted entity between an originating party (IDP) and a receiving party (SP).
A SAML binding [OASIS.saml-bindings-2.0-os] 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.
<md:Extensions>
<dame:DAMEInfo xmlns:dame="urn:geant:dame">
<dame:MetadataSyncLocation>
https://idp.example.net/idp/profile/SAML2/DAME
</dame:MetadataSyncLocation>
</dame:DAMEInfo>
</md:Extensions>
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 [RFC4926] MUST be used:
The protocol defined in this document MUST be divided into two phases:
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 [OASIS.saml-metadata-2.0-os] and [OASIS.saml-idp-discovery].
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.
User agent SP TTP
| | |
|----HTTP Request--->| |
| | |
|---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 [OASIS.saml-idp-discovery], the SP redirects the user agent to the TTP with an HTTP GET request including the REQUIRED or OPTIONAL parameters specified in [OASIS.saml-idp-discovery].
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 [RFC3986]. 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 [RFC3986], 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.
User agent SP TTP IDP | | | | |--HTTP Redirect-| | | | | | | |-----------AuthRequest1------------>| | | | | | |--------------------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 [OASIS.saml-idp-discovery], 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" [OASIS.saml-core-2.0-os] 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 [RFC3986] 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 [I-D.young-md-query] and the SAML Profile for the Metadata Query Protocol [I-D.young-md-query-saml].
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 [I-D.young-md-query].
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).
GET /discovery/DAME?entityID=https%3A%2F%2Fsp.example.com%2FSSO
&return=https%3A%2F%2Fsp.example.com%2FSSO%2FTTP%3FSAMLDS%3D1
%26target%3Dtarget HTTP/1.x
Host: ttp.example.org
After requesting access to a secured resource via HTTPS, S redirects U to the discovery service of T:
HTTP/1.x 302 Found
...
Location: https://sp.example.com/SSO/DAME?SAMLDS=1&target=target
&entityID=https%3A%2F%2Fidp.example.net%2Fidp%2FSAMLidp
U selects an appropriate IDP I. T redirects U back to S using the following message:
GET /SSO/DAME?SAMLDS=1&target=target
&entityID=https%3A%2F%2Fidp.example.net%2Fidp%2FSAMLidp
Host: sp.example.com
HTTP/1.x 302 Found
...
Location:
https://ttp.example.org/discovery/DAME?action=authenticate
&idpEntityID=https%3A%2F%2Fidp.example.net%2Fidp%2FSAMLidp
&SAMLRequest=fZHNTsMwEIRfJf.....
...
Receiving U's selection, S redirects the user to T containing a SAML authentication request (AuthnRequest1):
GET /DAME?action=authenticate
&SAMLRequest=fZHNTsMwEIRfJf.....
&RelayState=target
Host: ttp.example.org
GET /idp/profile/SAML2/Redirect/SSO
?SAMLRequest=lZLBbhshEIZfBXHfh..... HTTP/1.x
Host: idp.example.net
T temporarily stores the authentication request and redirects U to I sending a second authentication request (AuthnRequest2) containing the SAML request:
POST /SSO/SAML2/POST HTTP/1.x
POSTDATA
Referer:...
Set-Cookie:...
After successful authentication, I issues a SAML authentication response message to T:
GET /idp/profile/SAML2/DAME?action=fetchmetadata
?entityID=https%3A%2F%2Fsp.example.com%2FSSO HTTP/1.x
Host: idp.example.net
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:
GET SSO/DAME?action=fetchmetadata
?entityID=https%3A%2F%2Fidp.example.net%2Fidp%2FSAMLidp
Host: sp.example.com
GET /metadataservice/entities/https%3A%2F%2Fsp.example.com%2F
SSO HTTP/1.x
Host: ttp.example.org
Accept: application/samlmetadata+xml
The entities download the metadata from T using, e.g., SAML Profile for Metadata Query Protocol [I-D.young-md-query-saml]. Only I's messages to download S's metadata are presented here, S's messages are equivalent:
HTTP/1.x 200 OK
Content-Type: application/samlmetadata+xml
<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor entityID="https://sp.example.com/SSO"
xmlns="urn:oasis:names:tc:SAML:2.0:metadata">
...
GET /metadataservice/DAME?action=add&status=status HTTP/1.x
T sends a request to I and S in order to receive the status of the integration:
HTTP/1.x 200 OK
I answeres with:
GET /idp/profile/SAML2/Redirect/SSO
?SAMLRequest=fZHNTsMwEIRfJf.....
&RelayState=target HTTP/1.x
Host: idp.example.net
After successful completion T forwards S's authentication request to I:
POST /SSO/SAML2/POST HTTP/1.x
POSTDATA
...
I answers to S's AssertionConsumerServiceURL with a SAML Response:
HTTP/1.x 302 Found
...
Location: sp.example.com/secure
...
Receiving the SAMLResponse, S redirects U to the requested resource:
GET /secure HTTP/1.x
Cookie...
HTTP/1.x 200 OK
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 [OASIS.saml-metadata-2.0-os] 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 DAME workflow was originally developed together with Stefan Metzger (Leibniz Supercomputing Centre) and Wolfgang Hommel as well as Michael Grabatin (Universitat der Bundeswehr in Munchen, Computer Science Department).
| [OASIS.saml-bindings-2.0-os] | Cantor, S., "Bindings for the OASIS Security Assertion Markup Language (SAML) V2.0", March 2005. |
| [OASIS.saml-core-2.0-os] | Cantor, S., "Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0", March 2005. |
| [OASIS.saml-idp-discovery] | Cantor, S., "Identity Provider Discovery Service Protocol and Profile", March 2008. |
| [OASIS.saml-metadata-2.0-os] | Cantor, S., "Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0", March 2005. |
| [OASIS.saml-profiles-2.0-os] | Cantor, S., "Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0", March 2005. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", March 1997. |
| [RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", January 2005. |
| [RFC7230] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", June 2014. |
| [I-D.young-md-query] | Young, I., "Metadata Query Protocol, draft-young-md-query-05 [work in progress]", April 2015. |
| [I-D.young-md-query-saml] | Young, I., "SAML Profile for Metadata Query Protocol, draft-young-md-query-saml-05 [work in progress]", April 2015. |
| [OASIS.saml-glossary-2.0-os] | Hodges, J., "Glossary for the OASIS Security Assertion Markup Language (SAML) V2.0", March 2005. |
| [RFC4926] | Kalin, T. and M. Molina, "A URN Namespace for GEANT", July 2007. |
| [RFC6973] | Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M. and R. Smith, "Privacy Considerations for Internet Protocols", July 2013. |
| [SAML2Int] | Solberg, A., "Interoperable SAML2.0 Web Browser SSO Deployment Profile" |