|Table of Contents|
1. User Accesses Protected Resource
A user tries to access a protected resource, causing the SP to intercept the request. The resource locations to protect can be defined in the web server configuration itself, such as
httpd.conf, or in
shibboleth2.xml (or a separate file) using the
2. SP Determines IdP and Issues Authentication Request
The SP will select a SessionInitiator to use based on this protection configuration, which in turn is responsible for determining which IdP the user will be referred to and what protocol to use. The providers signal their profile preferences to one another through the exchange of SAML metadata.
The process of determining the IdP to use is called IdP Discovery and can include a combination of configuration options, various web-based interactions, cookies, and other techniques. A SessionInitiator might supply a text entry box, refer the user to a locally or remotely deployed discovery service (DS), or select a fixed IdP based on the resource requested.
During this step, the SP will preserve the original resource requested by the browser using a "relay state" mechanism, which is configured by a
The IdP examines the request and decides how it would like to authenticate the user based on rules established for the SP in
relying-party.xml and authentication in general in
login.config. The user is redirected to the selected login handler, authenticates (or tries to) using the method selected, and eventually control passes back to the profile handler with their username set.
First, the IdP gathers a set of attributes for the user using the attribute resolver. It collects user data from all the backend sources, transforms it if necessary, and attaches encoders to each attribute.
These attributes are passed through the attribute filter, which may pare down the information to be included in the response. The set of attributes released most often depends on the SP and the principal. This protects the user's privacy. The resulting information could be as little as "someone authenticated successfully", or reveal any attribute you can imagine.
The user's information is packaged into a form suitable for the eventual response using the encoders attached earlier, typically in a SAML assertion. This assertion may be signed with the IdP's key and, in the case of a SAML 2.0 assertion, encrypted with the SP's key for security and privacy. The assertion (or a reference to it called an artifact) is placed into a response that is passed through the client browser for delivery back to the SP to an endpoint called an Assertion Consumer Service.
5. Back to the SP
The browser delivers the response from the IdP to an Assertion Consumer Service endpoint at the SP. The ACS implementation decodes the message, decrypts the assertion if necessary, and performs a variety of security checks. If everything is in order, then the SP will create a new user session after extracting attributes and other information from the message. Attributes are translated into a cacheable form using the SP's AttributeExtractor, passed through an AttributeFilter, and cached in the new session along with other relevant information.
The "relay state" information returned by the IdP, if any, will have been created by the SP and by default if using a cookie, will point to a specially named cookie that should accompany the authentication response supplied to the ACS endpoint in this step. This is the cookie set in Step 2 above. If this cookie is missing (or if no relay state exists at all), the associated application's
The SP will associate the browser with the newly created session by sending a cookie containing a session key to the client as part of the redirection to the resource.
6. Back to the Protected Resource
In the final step, the browser is redirected to the protected resource accessed in Step 1, but this time the access occurs in the context of a session stored within the SP's SessionCache.
The cookie containing the session key set in the previous step is expected to accompany all subsequent requests for protected resources. This is why it's essential that the ACS endpoint and resource location share a virtual host; if they do not, the session cookie set in the previous step won't be returned by the browser, and looping typically results.
Assuming the session is recognized and validated by the SP, any applicable AccessControl plugins will be enforced, and assuming access is granted, the request will proceed, with any cached attributes attached to the request.