PingPong IdP Discovery Protocol
draft-efazendin-pingpong-idp-discovery-00

Abstract

This specification defines an Identity Provider Discovery profile using long-term cookies in the user's browser, which are associated to the user's Identity Provider domain, and an iframe and javascript solution to reveal the existence of those cookies to Service Providers.

Status of this Memo

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 June 11, 2011.

Copyright Notice

Copyright (c) 2010 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.

Table of Contents

1.  Introduction
2.  Notational Conventions
3.  Terminology
4.  Processing Overview
5.  Identity Provider
    5.1.  Preparing for PingPong
        5.1.1.  Enabling Service Providers
        5.1.2.  Authentication Tracking
    5.2.  Ping Requests
    5.3.  Pong Responses
    5.4.  P3P
6.  Service Provider
    6.1.  Preparing for PingPong
        6.1.1.  Enabling Identity Providers
    6.2.  Ping Requests
    6.3.  Pong Responses
    6.4.  PongStatus
    6.5.  Implementation Considerations
        6.5.1.  Remembering IdP
        6.5.2.  Limits
        6.5.3.  Paging
        6.5.4.  Prioritization
        6.5.5.  Timeout
        6.5.6.  IdP Discovery Fallback
7.  Security Considerations
    7.1.  Whitelisting SPs
    7.2.  Protecting Sensitive Cookies
8.  IANA Considerations
9.  References
    9.1.  Normative References
    9.2.  Informative References
Appendix A.  Contributors
§  Author's Address

1.  Introduction

PingPong IdP Discovery is a protocol to discover an end-user's Identity Provider (IdP). An IdP is an entity, or security domain, that is an authority for representing a user's identity. They authenticate users and have records of users. A Service Provider (SP) is an entity, or security domain, with web applications that end-users want to access but for which they don't have credentials registered to authenticate. An IdP Discovery protocol is needed when a user attempts to access a protected resource at an SP, which supports Single Sign-on (SSO) with a trusted set of IdPs, and that user is unauthenticated to the SP and does not provides an SSO credential in the HTTP request. In this scenario, the SP needs to discover the IdP that is the authority of the user to initiate an SSO transaction with that IdP. This document describes an IdP Discovery protocol to support this use case.

PingPong IdP Discovery is designed for use cases where there is a finite quantity of IdPs. Although there are other potential terminating events, the user's browser may query, and therefore send an HTTP request to, every possible IdP for a given SP. With a large number of IdPs, the end-user may find the amount of time required to query all IdPs to be unacceptable. The number of SPs in a given SSO network (federation) does not impact the runtime processing of PingPong IdP Discovery.

Solutions to IdP Discovery have been addressed in previous protocol definitions. These designs typically address the challenge by introducing a common domain. Section 4.3 of [OASIS.saml‑profiles‑2.0‑os] (Hughes, J., Cantor, S., Hodges, J., Hirsch, F., Mishra, P., Philpott, R., and E. Maler, “Profiles for the OASIS Security Assertion Markup Language (SAML) V2.0,” March 2005.) defines using DNS to establish a common DNS domain to let IdPs and SPs share cookie information by reading from and writing to sub-domains of the common domain. [SSTC‑IdP‑Discovery] (OASIS Standard, “Identity Provider Discovery Service Protocol and Profile,” March 2008.) defines a framework for redirecting a user's browser to a 3rd party hosted domain to perform IdP Discovery. PingPong differs from these primarily by not requiring a common domain. This model may be useful in use cases where the infrastructure requirements for managing a common domain is not possible or is something that would not easily scale as a federation grows.

2.  Notational Conventions

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

Unless otherwise noted, all the protocol parameter names and values are case sensitive.

3.  Terminology

Ping request

The request sent from the IdP to the SP to query whether or not a user in the given browser context has authenticated at that IdP previously.

Pong response

The response returned from the IdP to the SP indicating whether or not the IdP has previously authenticated a user in the given browser context.

PingHandler

The HTTP service endpoint at the IdP to which Ping requests are sent.

PongHandler

The HTTP service endpoint at the SP to which Pong responses are sent.

PongStatus

The HTTP service endpoint accessed by the browser to determine the status of PingPong IdP Discovery and what action the browser should take next.

4.  Processing Overview

PingPong IdP Discovery is designed to direct the user's browser to query IdPs to determine whether or not they have ever authenticated this user or, at least, a user in the given web browser context. IdPs can determine the answer to this query quickly if they store a long-term cookie [httpstate] (Internet Engineering Task Force, “HTTP State Management Mechanism,” December 2010.) in the browser whenever it authenticates a user. When the browser is directed to query the IdP, it will include this cookie in the HTTP request, so the IdP simply needs to look in the request to determine the answer. Since a cookie can only be read by the domain from which it was written, the SP cannot read the IdP's cookie directly. PingPong IdP Discovery defines the mechanism, using a combination of iframes [html5‑iframe] (World Wide Web Consortium, “The iframe element,” December 2009.) and javascript [ecma‑262] (ECMA International, “ECMAScript Language Specification,” December 2009.), for directing the browser to perform these queries to, potentially, all possible IdPs for a given SP and processing the responses.

When an SP needs to determine the IdP of a user, the SP loads a series of iframes into the users browser. The src of each iframe is to a particular IdP's PingHandler. When an IdP receives an HTTP request to their PingHandler, they check to see if the request includes the cookie indicating a user in the given browser context has authenticated at that IdP in the past. The IdP then responds with an HTTP 302 redirect back to the SP's PongHandler. Included in the query string of the redirect URL is a parameter which indicates whether or not that IdP saw their cookie indicating the previous authentication. Both the Ping request and the Pong response are executed within the iframe, so the user's main browser window is never navigated away from the SP's web application. Each Pong response is recorded server side at the SP and indexed using the user's browser session.

While each iframe processes the Ping requests and the Pong responses, javascript in the browser periodically sends HTTP requests to the SP's PongStatus endpoint to determine what the browser should do next. The response can indicate to the browser that it should wait, load more iframes, or present a link to the user's IdP. Since all the Pong responses are recorded server side, the SP is in full control of the next logical step the browser should take.

Here is a high level overview of the PingPong IdP Discovery protocol:

 +----+                                            +----+
 | B  | ----------------(1) Init PingPong -------> | SP |
 | r  | <---------------(2) iframes -------------- |    |
 | o  |                                            |    |
 | w  |                                            |    |
 | s +----------+                       +-------+  |    |
 | e | iframe 1 | ------(3) Ping -----> | IdP 1 |  |    |
 | r |          | <-----(4) Pong ------ |       |  |    |
 |   |          |                       +-------+  |    |
 |   |          | ------(5) Pong ----------------> |    |
 |   +----------+                                  |    |
 |    |                                            |    |
 |   +----------+                       +-------+  |    |
 |   | iframe n | ------(n) Ping -----> | IdP n |  |    |
 |   |          | <-----(n+1) Pong ---- |       |  |    |
 |   |          |                       +-------+  |    |
 |   |          | ------(n+2) Pong --------------> |    |
 |   +----------+                                  |    |
 |    |                                            |    |
 |   +----------+                                  |    |
 |   | ajax     | <-----Pong Status -------------> |    |
 |   +----------+                                  |    |
 |    |                                            |    |
 +----+                                            +----+

The request/response flow illustrated in Figure 1 (PingPong IdP Discovery Protocol Overview) includes the following steps:

(1)

A request is made to initiate PingPong IdP Discovery.

(2)

The SP returns html containing the iframes for each IdP.

(3)

The browser sends a Ping request through the iframe to the first IdP. Included in the request is the long-term cookie, if it exists, indicating the user has authenticated there previously.

(4)

The IdP returns a Pong response, indicating the previous authentication status, as an HTTP 302 with the location set to the SP's PongHandler.

(5)

The Pong response is delivered to the SP's PongHandler.

(n, n1, n2)

Indicates the PingPong process occurs with n IdPs.

Pong Status

The browser repeatedly checks back to the SP to determine what action it should take next. Responses can indicate to check back again in a short period of time, present a link to the user as the user's IdP was found, or fallback to a secondary IdP Discovery method as the user's IdP was not found.

5.  Identity Provider

The main responsibility of the IdP in PingPong IdP Discovery is to receive Ping requests and to return Pong responses. The Pong response indicates whether or not this IdP has previously authenticated a user in this browser context.

5.1.  Preparing for PingPong

5.1.1.  Enabling Service Providers

The IdP MUST provide its PingHandler to each SP with whom it wants to support PingPong IdP Discovery.

PingHandler

The URL to the service endpoint at the IdP that receives Ping requests.

5.1.2.  Authentication Tracking

The IdP SHOULD track, for a relatively long period of time, that a user in a given browser context has authenticated. This SHOULD be done by setting a specific cookie in the browser when the user authenticates that will later be referenced during PingPong IdP Discovery. The expiration date on the cookie SHOULD be set far into the future to ensure the cookie's lifetime exceeds the expected frequency of user authentication events. This cookie SHOULD be renewed at every authentication event.

5.2.  Ping Requests

The user's browser will send an HTTP GET request to the IdP during PingPong IdP Discovery. Based on the request, the IdP determines whether or not it has previously authenticated a user within the context of this browser. This determination is done by checking for the existence of the long-term cookie it writes during authentication events, described in Section 5.1.2 (Authentication Tracking).

The Ping request is defined by the URI of the request and is of the form:

http://<DNS_to_IdP>/<path>?PongHandler=<SP_PongHandler_URI>

The PingHandler SHOULD NOT be accessed via SSL/TLS. The SSL negotiation process across a large number of IdPs could lead to an undesirable end-user experience due to the increased delay. All sensitive IdP cookies, for example those maintaining application session state with the IdP, SHOULD NOT be sent to the PingHandler. This can be implemented by setting the proper cookie parameters preventing a browser from sending cookies to the PingHandler, such as path and secure.

5.3.  Pong Responses

The IdP MUST respond to a Ping request by sending a Pong response to the SP's PongHandler. The IdP receives the PongHandler URI as a query parameter from the Ping request. The IdP appends a query parameter called authnedUser with a boolean value to complete the Pong response URI. The Pong response is delivered to the SP via an HTTP 302 response returned to the browser from the Ping request.

Since the Ping request is sent from the user's browser via an iframe, the main window of the user's browser will not be affected by the 302 redirect.

The Pong response is defined by the URI returned as the location header of the HTTP 302 response. The URI of the Pong response is the combination of the value received from the Ping request in the PongHandler query parameter plus an additional query parameter called authnedUser. The value of authnedUser is the literal true or false.

<SP_PongHandler_URI>[?|&]authnedUser=[true|false]

5.4.  P3P

The IdP MUST provide the appropriate [P3P] (World Wide Web Consortium, “Platform for Privacy Preferences (P3P) Project,” November 2007.) policy on their PingHandler service endpoint. The default security settings of certain browsers restrict the delivery of cookies through an iframe if a [P3P] (World Wide Web Consortium, “Platform for Privacy Preferences (P3P) Project,” November 2007.) policy isn't provided by the remote service. The specific [P3P] (World Wide Web Consortium, “Platform for Privacy Preferences (P3P) Project,” November 2007.) policy that should be implemented is outside the scope of this document.

6.  Service Provider

The main responsibilities of the SP during PingPong IdP Discovery is to direct the user's browser to query a set of IdPs to determine if they have previously authenticated the user by using Ping requests and to process the Pong responses returned from the IdPs.

6.1.  Preparing for PingPong

6.1.1.  Enabling Identity Providers

Before an SP can support PingPong IdP Discovery it will need to identify the IdP's it trusts as authorities of users of the SP's web applications. It will also need to receive the PingHandler URI from the identified IdPs and store it for runtime processing.

6.2.  Ping Requests

The SP creates and sends Ping requests through the user's browser. This allows for browser data to be transmitted directly to the PingHandlers at IdPs, and this method allows for sending the cookie, if it exists, to the IdPs to allow them to determine the value to provide in the authnedUser parameter of the Pong response. The SP does this by loading iframes in the user's browser. The src of each iframe is the PingHandler URI of each IdP.

The URL of the Ping request MUST include a query parameter of PongHandler. The value of the PongHandler MUST be a URI, which is URL encoded, to the SP's Pong Handler.

The PongHandler URI sent to the IdP is of the following format:

https://<DNS_to_SP>/<path><query_string>

When the SP receives a Pong response from an IdP it will need to resolve from which IdP it was sent. The SP SHOULD include a query parameter in the PongHandler <query_string> indicating the IdP to which the Ping request was sent so, it will be able to identify the IdP when it sends the Pong response.

6.3.  Pong Responses

The IdP will determine whether or not it has previously authenticated a user in the given browser context and return a Pong response to the SP with the answer. This response will be delivered via a 302 redirect from the Ping request. Since these two HTTP requests happen within an iframe, the user's main browser window will not be affected. The answer is communicated via a query parameter called authnedUser, which is appended to the Pong Handler URI and is the literal true or false.

6.4.  PongStatus

While the browser is processing the iframes, it will need to periodically check back to the SP to determine what it should do next. This is done with requests sent back to the PongStatus service endpoint hosted by the SP. The requests are sent to the SP using an AJAX method via javascript. The response from the PongStatus can indicate to the browser that it should wait, load more iframes, or present a link to the user's IdP.

6.5.  Implementation Considerations

The following sections are considerations and recommendations for the SP implementation of PingPong IdP Discovery. Since these are implementation specific items and not directly related to the communication between IdPs and SPs, these items are not required for PingPong IdP Discovery conformance.

6.5.1.  Remembering IdP

After PingPong IdP Discovery completes, the user invokes an SSO transaction, and the user returns with a proper SSO credential, the SP SHOULD track this user's IdP for future reference. Tracking the IdP will prevent the need to perform PingPong IdP Discovery in the future when the user returns to the SP application unauthenticated. The SP will be able to lookup the user's IdP based on how it was stored after the user's last successful SSO transaction. The method for storing the user's IdP could be done in a variety of ways, but a cookie would be a valid method.

6.5.2.  Limits

There will be some quantity of IdPs where PingPong IdP Discovery may take longer than an acceptable amount of time for the end-user. The number of IdPs that are too many is subjective and will need to be determined by the SP, but given modern network speeds and end-user computing capacity it could be on the order of 100s or maybe even 1000s.

6.5.3.  Paging

In deployments where there is a relatively large number of IdPs, the SP SHOULD page through the list of IdPs until one or more Pong responses indicate the user's IdP(s). For example, if a given SP supports 100 IdPs, the SP could attempt PingPong IdP Discovery with the first 20. If none of the first 20 return a successful response, the next 20 are then queried. This paging would continue until a Pong response is received that indicates the user's IdP or until all IdPs have been queried and none have indicated they are the user's IdP.

6.5.4.  Prioritization

In deployments where there is a relatively large number of IdPs, the SP SHOULD establish a prioritization mechanism to increase the possibility that the user's IdP is found early in the PingPong IdP Discovery Process. Prioritization and Paging (Paging) are complementary.

6.5.5.  Timeout

In some situations it's possible an IdP does not respond with a Pong response. Given this possibility, the SP SHOULD implement a timeout period where it will treat the lack of response from an IdP the same as it would if the IdP responded with a 'authnedUser=false'.

6.5.6.  IdP Discovery Fallback

In the event that an SP does not receive a Pong response that indicates a user's IdP, the SP SHOULD fallback to a secondary method of IdP Discovery.

7.  Security Considerations

7.1.  Whitelisting SPs

Given the potential that a rogue SP could initiate PingPong IdP Discovery to determine a user's IdP, potentially for malicious reasons, the IdP SHOULD implement a whitelist of PongHandlers. If a whitelist is implemented, all Ping requests with a PongHandler value that is not included in the whitelist MUST be discarded. Responding to the Ping request with an HTTP 200 is an example method of discarding the Ping request.

7.2.  Protecting Sensitive Cookies

Both the IdP and SP SHOULD ensure that it is not possible for sensitive cookies, like a sessionid, to be sent through an unencrypted channel. This is especially important given that the IdP's PingHandler service should be accessed via an unencrypted channel, which is recommended to improve performance. The long-term cookie the IdP uses to track the browsers in which it has authenticated a user is not considered sensitive.

8.  IANA Considerations

This document has no actions for IANA.

9.  References

9.1. Normative References

9.2. Informative References

Appendix A.  Contributors

The following people contributed wording and concepts to this document: Patrick Harding, Paul Madsen, Pam Dingle, Brian Campbell, David Waite and Andre Durand

Author's Address