Expert Demo

arrow To be better able to understand this technical introduction, we strongly recommend you to read the easy demo and the medium demo first.
The content of this introduction is aimed at technicians and therefore quite detailed.

Overview

Tech Overview

Figure 1: Situation overview

The following explanations and protocol snippets serve as a more example based version of the official Shibboleth specifications.
As shown in Fig. 1 the scenario is the same as in the easy demo and the medium demo but in this introduction background processes and interacting components are also considered.
In the following, it is distinguished between the data sent from the user's web browser to the web server and the data received by the user from the web server. Sometimes important information is emphasized using bold text. For better readability the data is shown in URL decoded form, e.g. a '://' would be '%3A%2F%2F' in the real data. For layout reasons long lines were split and a backslash ('\') was inserted at the end of the line where this was the case. In some protocol samples some less relevant information was omitted. In that case this usually is shown with '[...]'.

Phase 1 - User connects to Resource and is redirected

Resource Request

Figure 2: User is redirected to WAYF

Step 1:
The user opens a web browser and accesses the resource located at https://kohala.switch.ch/secure. His web browser sends the following request:
GET /secure/ HTTP/1.1
Host: kohala.switch.ch
Step 2:
Since this user is not (yet) an authenticated Shibboleth user, the web server answers with an HTTP Redirect to the WAYF server located at wayf-test.switch.ch. Since the WAYF server needs to know from where (which resource) the user came, the relevant information is provided as GET parameters:

HTTP/1.x 302 Found
Location: https://wayf-test.switch.ch/SWITCHaai/WAYF\
?shire=https://kohala.switch.ch/Shibboleth.shire\
&target=https://kohala.switch.ch/secure/\
&providerId=https://kohala.switch.ch/shibboleth
Consequently, the web browser sends a new request to the WAYF: 

GET /SWITCHaai/WAYF\
?shire=https://kohala.switch.ch/Shibboleth.shire\
&target=https://kohala.switch.ch/secure/\
&providerId=https://kohala.switch.ch/shibboleth HTTP/1.1
Host: wayf-test.switch.ch\
Step 3:
The WAYF server answers with the web page that allows the user to select his Home Organization: 

HTTP/1.x 200 OK
Set-Cookie: JSESSIONID=ABA262C37103B02AB65D16B1D0EB3359; Path=/SWITCHaai; Secure
Content-Type: text/html;charset=ISO-8859-1

[... HTML Code ...]

Phase 2 - Home Organization Selection

WAYF selection page

Figure 3: WAYF webpage

On the WAYF page, the user selects his Home Organization. The selection gets stored by means of a Session Cookie in the browser. So the selection has to be done only once per web browser session unless the user deselects the checkbox.

Phase 3 - User Authentication at his Home Organization

Authentication at Home Organization

Figure 4: User authenticates at his Home Organization

Step 4:
The user submits his selection with the following request: 

GET /SWITCHaai/WAYF\
?shire=https://kohala.switch.ch/Shibboleth.shire\
&target=https://kohala.switch.ch/secure/\
&action=selection\
&origin=urn:mace:switch.ch:aaitest:aaitest.switch.ch\
&cache=TRUE HTTP/1.1
Host: wayf-test.switch.ch
Cookie: JSESSIONID=ABA262C37103B02AB65D16B1D0EB3359
Step 5:
After the user submits his WAYF selection, the WAYF web server answers: 

HTTP/1.x 302 Moved Temporarily
Set-Cookie: edu.internet2.middleware.shibboleth.wayf.selectedHandleService=\
https://dukono.switch.ch/shibboleth-idp/SSO; Path=/
Location: https://dukono.switch.ch/shibboleth-idp/SSO\
?target=https://kohala.switch.ch/secure/\
&shire=https://kohala.switch.ch/Shibboleth.shire
The cookie is set in order to remember the user's choice for the checkbox 'Remember my selection for this browser session'. As the text states, the cookie is only available during the current web browser session.
The user's web browser subsequently sends the following HTTP request to the Shibboleth Handle Server (dukono.switch.ch) of his Home Organization (aaitest.switch.ch):

GET /shibboleth-idp/SSO\
?target=https://kohala.switch.ch/secure/\
&shire=https://kohala.switch.ch/Shibboleth.shire HTTP/1.1
Host: dukono.switch.ch
Step 6:
Because the user is not authenticated yet, the web server protecting the access to the Handle Server redirects the web browser to the webpage of the local web single sign-on authentication system. For our demo we have chosen CAS but one could also use Pubcookie or similar products: 

HTTP/1.x 200 OK
Set-Cookie: JSESSIONID=C5766808E41D3C64BFBD3839D6701730; Path=/shibboleth-idp; Secure
                                       [...]
Location: https://dukono.switch.ch/cas/login
?service=https://dukono.switch.ch/shibboleth-idp/SSO.shire
&https://kohala.switch.ch/Shibboleth.shire
&target&https://kohala.switch.ch/secure
&providerId=https://kohala.switch.ch/shibboleth
Hence, the web browser requests the login page: 

GET /cas/login
?service=https://dukono.switch.ch/shibboleth-idp/SSO.shire
&https://kohala.switch.ch/Shibboleth.shire
&target&https://kohala.switch.ch/secure
&providerId=https://kohala.switch.ch/shibboleth HTTP/1.1
Host: dukono.switch.ch
Cookie: _saml_idp=dXJuOm1hY2U6c3dpdGNoLmNoOlNXSVRDSGFhaTp1bmlnZS5jaA&&+
Step 7:
The single sign-on authentication system (in our demo CAS) sends the login page and sets its cookie: 

HTTP/1.x 200 OK
Content-Type: text/html; charset=iso-8859-1

[... HTML Code ...]
The user sees the login page of his Home Organization, in our demo this is the Test Home Organization @SWITCHaai as shown in Fig. 5.
Authentication dialog

Figure 5: User authenticates at his Home Organization

Phase 4 - Access to Resource

Access Granted

Figure 6: User gets authenticated and redirected to web server of resource

Step 8:
Once the user provided his credentials, in this demo user name demouser and password demo, he submits the form and his web browser sends such a request back to the single sign-on authentication system:

/cas/login
?service=https://dukono.switch.ch/shibboleth-idp/SSO
&shire=https://kohala.switch.ch/Shibboleth.shire
&target=https://kohala.switch.ch/secure
&providerId=https://kohala.switch.ch/shibboleth HTTP/1.1
Host: dukono.switch.ch
Cookie: cas_pre_s=rcAHSqG62uVW7zGdRxKtnpdIWg7IFiwXihvObdaYa7mFI3qR4RYfm6F\
                                       [...]
hSNjSOxMUT68kuDApIWngwxPfVaggG; cas_g_req=clear
Content-Type: application/x-www-form-urlencoded
Content-Length: 61
username=demouser&password=demo<=LT-27-3fKACnZWQlYd8T4Md08p
The single sign-on authentication system, which is independent of Shibboleth, checks the credentials against the local user directory.
 
Step 9:
After successful authentication, the web browser receives a redirect and cookies for the single sign-on system:

HTTP/1.x 302 Moved Temporarily
Set-Cookie: CASTGC=TGC-13-jpZHue4IXosIiVGyy6vrGcj3YOO0H3mRvjcpEqMK0EU8gFS6RC; Path=/cas;
Location: https://dukono.switch.ch/shibboleth-idp/SSO
?shire=https://kohala.switch.ch/Shibboleth.shire
&target=https://kohala.switch.ch/secure
&providerId=https://kohala.switch.ch/shibboleth
&ticket=ST-17-lGFPJrLWJva134whvhxZ
Set-Cookie: CASTGC=TGC-13-jpZHue4IXosIiVGyy6vrGcj3YOO0H3mRvjcpEqMK0EU8gFS6RC; Path=/cas; Secure
Therefore, the web browser sends a new request to the Handle Server on 'dukono.switch.ch': 

GET /shibboleth-idp/SSO\
?target=https://kohala.switch.ch/secure/\
&shire=https://kohala.switch.ch/Shibboleth.shire
&ticket=ST-17-lGFPJrLWJva134whvhxZ HTTP/1.1
Host: dukono.switch.ch
Cookie: JSESSIONID=C5766808E41D3C64BFBD3839D6701730; _saml_idp=dXJuOm1hY2U6c3d
Step 10:
Based on the cookies, the web single sign-on system protecting the Handle Server knows that this user is properly authenticated. Therefore, the Handle Server generates a Handle for the user: 

HTTP/1.x 200 OK
Set-Cookie: cas_g=; domain=.switch.ch; path=/; expires=Fri,\
11-Jan-1990 00:00:01 GMT; secure
Set-Cookie: cas_pre_s=; path=/; expires=Fri, 11-Jan-1990 00:00:01 GMT; secure
Set-Cookie: cas_s__SWITCHaai_=C3kMOhoDCJrHivwK00FZP+8xhPFjyPVq3J8nlluLPO9\
                                       [...]
5/xSuon/ryauQAcKHz95IQQwe4l3eEvKRfVs; path=/; secure
Set-Cookie: JSESSIONID=4878F247EDBE5313C35397B5670413EF; Path=/SWITCHaai; Secure
Content-Type: text/html;charset=ISO-8859-1

[... HTML Code ...]

<form name="shib"  action="https://kohala.switch.ch/Shibboleth.shire" method="POST">
<input type="hidden" name="TARGET" value="https://kohala.switch.ch/secure/">
<input type="hidden" name="SAMLResponse" value="PFJlc3BvbnNlIHhtbG5zPSJ1cm46\
                                       [...]
QXNzZXJ0aW9uPjwvUmVzcG9uc2U+">
<noscript>
<input type="submit" value="Continue">

[... HTML Code ...]

The web browser briefly shows a page that should look like Fig. 7.
The handle to be sent to the resource is embedded in a hidden form element. If JavaScript is enabled in the web browser, the form gets sent automatically via a redirect. Otherwise, the user has to manually click on a submit button to send the form and get redirected.

Authentication dialog

Figure 7: Handle redirection dialog

The handle is embedded in a hidden form element that is automatically sent by web browsers with enabled javascript. On other web browsers the user manually has to send the form to get redirected.
The web browser sends the request with the handle to the web server where the resource is located: 


POST /Shibboleth.shire HTTP/1.1
Host: kohala.switch.ch
Content-Type: application/x-www-form-urlencoded
Content-Length: 16859
TARGET=https://kohala.switch.ch/secure/\
&SAMLResponse=PFJlc3BvbnNlIHht\
                                       [...]
0Pjwv%0D%0AQXNzZXJ0aW9uPjwvUmVzcG9uc2U%2B

Because the user sent the handle generated by his Home Organization to the resource, the resource can now determine whether this user shall have access to the resource.

Phase 5 - Attribute Request

Access Granted

Figure 8: User is granted access to resource

To decide whether a user is allowed to access a resource, the mod_shib module embedded in the Apache web server examines the Shibboleth access rules. The following code snippet shows the Apache configuration for the test resource, including some additional commented out lines.
The 'require valid-user' grants access to any Shibboleth authenticated user without any further requirement. The other examples are pretty self-explanatory: 


<Directory /var/www/secure>
    AuthType shibboleth
    ShibRequireSession On
#   require affiliation staff
#   require homeOrganization aaitest.switch.ch
#   require uniqueID 498752@switch.ch
    require valid-user
</Directory>
Step 11:
Because the test resource can be accessed by every Shibboleth user, it can be used to display all the user's attributes. Therefore, the Home Organization is requested to provide all available attributes for this user referred to by the handle.

This request is directly handled by the Shibboleth daemon (actually it is the process named 'SHAR', the Shibboleth Attribute Requestor) and the Attribute Authority (AA) on the Home Organization side. To request a user's attributes the Shibboleth daemon sends the same handle it received from the user in step 10. It is a SAML 'Attribute Request' message.
The request looks like this:


<samlp:request xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" 
issueinstant="2004-05-25T22:46:10Z" majorversion="1" minorversion="1" 
requestid="aaf2319617732113474afe114412ab72">
	<samlp:attributequery resource="https://kohala.switch.ch/secure/">
		<saml:subject xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
			<saml:nameidentifier 
				format="urn:mace:shibboleth:1.0:nameIdentifier" 
				namequalifier="http://idp.example.org/shibboleth">
				3f7b3dcf-1674-4ecd-92c8-1544f346baf8 
			</saml:nameidentifier>
		</saml:subject>
	</samlp:attributequery>
</samlp:request>
Step 12:

After the HTTPS session establishment from the SHAR to the AA, the AA verifies the identity of the SHAR based on the server certificate provided by the SHAR.

Once the AA receives the attribute request, it first examines the handle it contains. If it matches with a handle recently generated by the Handle Server it knows to which user it refers. Then the AA checks the Attribute Release Policy (ARP). This XML configuration file contains rules that determine whether an attribute of a specific user may be released to a specific resource or not.
Depending on the Home Organization there is a general site wide ARP file defining the default set of rules and a user customizable ARP file with the user specific set of rules. The user's rules have precedence over the site wide rules.
The AA answers with a Response message containing all user attributes allowed to provide to this resource according to the ARP evaluation.


<samlp:response xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
inresponseto="aaf2319617732113474afe114412ab72" 
issueinstant="2004-05-25T22:46:10.940Z" majorversion="1" minorversion="1" 
responseid="b07b804c7c29ea1673004f3d6f7928ac">
	<samlp:status>
		<samlp:statuscode value="samlp:Success" />
	</samlp:status>
	<saml:assertion xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" 
	assertionid="a144e8f3adad594a9649924517abe933" 
	issueinstant="2004-05-25T22:46:10.939Z" majorversion="1" minorversion="1" 
	issuer="https://idp.example.org/shibboleth">
		<saml:conditions notbefore="2004-05-25T22:46:10.939Z" 
		notonorafter="2004-05-25T23:16:10.939Z">
			<saml:audiencerestrictioncondition>
				<saml:audience>
					https://kohala.switch.ch/secure/
				</saml:audience>
			</saml:audiencerestrictioncondition>
		</saml:conditions>
		<saml:attributestatement>
			<saml:subject>
				<saml:nameidentifier 
				format="urn:mace:shibboleth:1.0:nameIdentifier" 
				namequalifier="https://idp.example.org/shibboleth">
					3f7b3dcf-1674-4ecd-92c8-1544f346baf8 
				</saml:nameidentifier>
			</saml:subject>
			<saml:attribute 
			attributename="urn:mace:switch.ch:attribute-def:swissEduPersonUniqueID" 
			attributenamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
				<saml:attributevalue xsi:type="xsd:anyURI">
					773443@aaitest.switch.ch
				</saml:attributevalue>
			</saml:attribute>
			<saml:attribute 
			attributename="urn:mace:dir:attribute-def:givenName" 
			attributenamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
				<saml:attributevalue xsi:type="xsd:anyURI">
					Demouser
				</saml:attributevalue>
			</saml:attribute>
			
			               [...] 
			               
		</saml:attributestatement>
	</saml:assertion>
</samlp:response>
Step 13:
Finally, the user receives a Shibboleth session cookie and gets redirected to the resource of this demo. The attributes received from the user's Home Organization are provided by the mod_shib module to the web application as web server environment variables. Therefore, the resource could also use these attributes to further restrict access. 

HTTP/1.x 302 Found
Date: Mon, 04 Apr 2005 10:30:28 GMT
Set-Cookie: _shibsession_default=b03871b42d188af4062e6fbd777550ad; path=/
Location: https://kohala.switch.ch/secure/
And the resource is finally accessed: 

GET /secure/ HTTP/1.1
Host: kohala.switch.ch
Cookie: _shibsession_default=b03871b42d188af4062e6fbd777550ad

The web page of the demo resource should look like Fig 9.

Result page

Figure 9: Successful login and access to test resource

Summary - Shibboleth Login Procedure

Full Demo

Figure 10: The whole login procedure

Subsequent accesses to the resource are granted directly until the Shibboleth session timeout requires a fresh handle to be issued by the Home Organization.

Medium Demo

arrow Take a look at the medium demo if you would like to see this login procedure in action.