Shibboleth Developers

[Tom Scavo <>]

Enhanced WAYF

- Characteristics of SAML2 IdP Discovery profile:

 + The preferred IdP is based on past history.
 + The user authenticates at the IdP before visiting the SP (otherwise
there is no history).
 + By authenticating at the IdP, the user declares his/her preferred IdP.
 + The cookie writing service is invoked by the IdP.
 + The cookie reading service is invoked by the SP.

- Guiding principles of this profile:

 + The user's preferred IdP should be on a per-SP basis.
 + Each user has an associated IdP history list (which is what the
common domain cookie really is), which may be used to initialize form
controls and silently redirect the client (if desired).
 + For a given user, for every SP there is a preferred IdP, that is,
there is a list of (SP, IdP) ordered pairs associated with each user.
 + Every SP has access to its corresponding preferred IdP, that is, by
default a user is silently redirected to the same IdP used the last
time the SP was visited.
 + A GUI can be constructed to allow the user to modify the IdP
history list.  Likewise, the user may also modify the (SP, IdP)
ordered pairs.  The GUI is hosted by the WAYF.
 + No DNS trickery is required.  All profile functionality is
localized on a central WAYF.  The SP and IdP need not implement
anything beyond simple redirects and (optional) "return" endpoints.
 + No client-side functionality beyond basic cookie handling is assumed.

- Give each SP its own (virtual) directory on the WAYF server:

 https://wayf.internet2.edu/InQueue/WAYF/sp1.edu
 https://wayf.internet2.edu/InQueue/WAYF/sp2.edu
 etc.

This is the same InQueue location URL used today except for the "extra
path" information "/sp1.edu", "/sp2.edu", etc.

- An SP redirects a client to its instance of the WAYF server (with
parameters target, shire, time, and providerId).  The WAYF server does
the same thing it does today, that is, it prompts the user for their
preferred IdP.  Once that is obtained, the WAYF server writes a
persistent cookie called _shib_idp with the following properties:

 Name:    _shib_idp
 Value:   urlencode( <SP providerId> + <space> + <IdP providerId> )
 Path:    none
 Domain:  none
 Secure:  true

For example, a request to 

 https://wayf.internet2.edu/InQueue/WAYF/sp1.edu 

causes a cookie with value

 https://sp1.edu/ https://idp1.edu/

to be written on the client.  At the same time, the client is
redirected to the corresponding SSO service at the IdP.

- As a result, each SP has its own cookie named _shib_idp (i.e., each
SP is associated with a preferred IdP).  A user will have many such
cookies in the browser's cookie store.  Each cookie is distinguished
by its path, which is unique since SP domains are unique.

- The next time the SP redirects an authn request to the WAYF, the
client is silently redirected to the SSO service of the preferred IdP
stored in cookie _shib_idp.

- As mentioned above, before the WAYF server writes cookie _shib_idp
for the first time, it needs to know the user's preferred IdP for the
SP in question.  The WAYF prompts the user for this information and
asks if the choice is to be remembered.  If so, the WAYF writes the
_shib_idp cookie as outlined above.  At the same time, another
persistent cookie with the following properties is written:

 Name:    _shib_idp_history
 Value:   urlencode( <IdP providerId> + <space> + <IdP providerId> + ... )
 Path:    /InQueue/WAYF
 Domain:  none
 Secure:  true

This cookie is visible to all SPs (so to speak) and can be used to
initialize the form control presented to the user the first time
around.

- As specified in the current draft of the Shib Architecture doc, the
SP may make a request as follows:

 https://wayf.internet2.edu/InQueue/WAYF/sp1.edu?return=...

The WAYF responds by appending a providerId parameter to the return
URL.  The value of the providerId parameter is the complete value of
the _shib_idp_history cookie.  The SP may use this list of providerIds
to interact with the user or it may redirect the client to one of the
IdPs in the list.

- Cookie _shib_idp_history is similar to _saml_idp except

 + The name has the suffix "history", which accurately reflects the
value of the cookie.
 + The IdP providerIds are not base64 encoded.
 + The path is explicitly set to the base path of the WAYF.
 + The domain is not set.

(Note: All of the above are bugs in the SAML2 IdP Discovery profile.)

- A more complicated but slightly more accurate approach is to require
the IdP to invoke a cookie writing service that modifies
_shib_idp_history (similar to SAML 2.0 IdP Discovery profile) after
the user has authenticated.  For our purposes, it is adequate for the
WAYF to update the cookie in the process of redirecting the client to
the IdP's SSO service.

- Similar to _shib_idp_history, a cookie called _shib_sp_history might
be maintained by the WAYF.  A use for this cookie has not been
determined, however.

- Now let's consider what might happen when the user requests

 https://wayf.internet2.edu/InQueue/WAYF

Cookie _shib_idp_history is sent to the WAYF server along with this
request.  Subsequently, the user is presented with form controls that
allow the history list to be modified.  Upon submission, the WAYF
overwrites the value of cookie _shib_idp_history.  All this does is
change the initial value of subsequently presented form controls.

- More importantly, when the user requests

 https://wayf.internet2.edu/InQueue/WAYF

all cookies named _shib_idp are likewise sent along with the request
(since each of the virtual directories is in the appropriate subtree).
 The WAYF iterates over all the cookies and builds another form
control that allows the user to modify the preferred IdP of any SP
(one at a time).  To change one of the _shib_idp cookies, the user
makes a request (via the form control) to

 https://wayf.internet2.edu/InQueue/WAYF/sp1.edu?providerId=...

As a result, the WAYF modifies cookie _shib_idp for sp1.edu and
redirects the client back to /InQueue/WAYF.

- Let's summarize.  

1) To invoke the WAYF Cookie Manager page, a user requests

 https://wayf.internet2.edu/InQueue/WAYF

The WAYF returns a form with a control to modify _shib_idp_history and
another control to modify the preferred IdP of any SP.  In either
case, upon submission the server responds with the WAYF Cookie Manager
page.

2) To modify the preferred IdP of a particular SP, a user requests

 https://wayf.internet2.edu/InQueue/WAYF/sp1.edu?providerId=...

This request could be typed directly into the user's browser, but more
likely the user will interact with the Cookie Manager (as outlined in
step 1).

3) An SP (e.g., sp1) always redirects authn requests to its instance
of the WAYF server:

 
https://wayf.internet2.edu/InQueue/WAYF/sp1.edu?target=...&shire=...&time=...&providerId=...

As a result, the client is redirected to the user's preferred IdP
stored in cookie _shib_idp.  If the SP wishes to override the User's
preferred IdP, the SP simply redirects the user to the desired IdP.

4) As specified in the current draft of the Shib Architecture doc, the
SP may instead make a request as follows:

 https://wayf.internet2.edu/InQueue/WAYF/sp1.edu?return=...

The WAYF responds by appending a providerId parameter to the return
URL.  The value of the providerId parameter is the value of the
_shib_idp_history cookie.