How Shibboleth Logins Work
Shibboleth has two major halves: an identity provider (IdP), and a service provider (SP). The identity provider supplies information about users to services, and the service provider gathers information about users to protect resources. In the typical use case, a web browser accesses a protected resource, authenticates at their identity provider, and ends up back at the resource logged in. -- Shibboleth Wiki: Flows and Configs
Terms Used
Identity Provider (IdP) - The Shibboleth software that verifies the login for a user, and passes attributes about that user back to the Service Providers.
Service Provider (SP) - The Shibboleth software that runs on each protected website. This collects the login and attribute statements from the IdP and shares them with the website.
Protected Resource - This is content on a website. It can be a directory of files, or a web application.
Attributes - Information about an individual user. Such as:
- Name: Robert A User
- Userid: rauser
- Affiliation: member@ncsu.edu
- email: nobody@ncsu.edu
- List of Attributes
SAML message - Security Assertion Markup Language (SAML) is an open standard data format for exchanging authentication and authorization data between parties. Shibboleth uses SAML messages to communicate between its IdPs and its SPs.
Before We Begin
Shibboleth uses Public-key cryptography to establish a web of trust between the IdP and SP entities. Each entity has to generate its own public/private key-pair. The public portion of this key-pair must be shared with the other entities to establish trust between them.
Messages sent from an SP to an IdP can be cryptographically signed with the SP's private key. The IdP can then use the SP's public key to verify that signature.
Messages sent from and IdP to an SP can be cryptographically signed with the IdP's private key, and encrypted with the SP's public key. The SP (and only the SP) will use its private key to decrypt the message. The SP can also use the IdP's public key to verify the signature on the message.
Shibboleth uses a Federation to collect and distribute these public keys. An entity will register with the federation, and submit their public key. The federation places all of the entity keys in one document, signs it with it's own private key, and distributes the collection back to all of the member entities. Each member entity will periodically retrieve the federation collection, verify that the signature is genuine, and then trust that the keys in the data belong to their respective entities.
Login Flow
A user tries to visit a protected resource on a website.
The SP on that website issues a SAML message, encodes it in a URL, and redirects the user's browser to the IdP with that message.
The IdP verifies the SAML message that it received and allows the user to perform a login.
Once the user logs in, the IdP generates an IdP session, and refers to its Attribute Release Policy (ARP) to see what attributes it is permitted to send back to the SP.
The IdP constructs a SAML reply message for the SP and instructs the user's browser to return to the SP.
The browser posts the SAML message to the SP.
The SP decodes the SAML reply, verifies the IdP signature, and uses that to generate an SP session on the website.
The SP then sends the user back to the original protected resource. That resource will lookup the SP session, permit the access, and retrieve the user's attributes.
For more details, see this trace of a Shibboleth login.
Shibboleth as a Single-Sign-On (SSO) Provider
Every time a user visits a different SP, that SP must send the user to an IdP to establish their identity.
The first time the user visits the IdP, it generates an IdP session that is used to remember that the user has previously authenticated.
When the user visits a second SP, they get directed to the IdP as before (steps 1-2 in the diagram above).
On step 3 above, the IdP session is checked. So long as it has not expired, the user will not be prompted to login again. Instead, they will quietly be redirected through the remaining steps.
On shib.ncsu.edu, the IdP session idle timeout is one hour.
Additional Steps
Discovery Services
If the SP knows that only one IdP will ever provide authentication then it can immediately send the user to that IdP. However, some SPs will need to be able to handle users authenticated by different IdPs. At that point they have no option but to ask the user to select an IdP. This is usually done by a Discovery Service. It fits in between steps 1 and 2 in the diagram above.
A user tries to visit a protected resource on a website.
Discovery Service asks the user "Where Are You From?" It usually provides some sort of list of available IdPs.
User replies by selecting an IdP.
SP issues a SAML message for the selected IdP, and redirects the user's browser to the IdP with that message.
Attribute Release
Attribute Release (AR) is an extension that we use on the shib.ncsu.edu Identity Provider. It allows us to get the user's consent before we release their attributes to a Service Provider. It fits in between steps 3 and 4 in the diagram above.
After the user has authenticated to the IdP, the AR module is called.
AR checks for a cookie to see if this user has previously visited the target SP, and to see if they have consented to release the same list of requested attributes. If they have, the flow continues with step 4, passing the SAML message back to the SP.
If they have not granted consent, AR prepares a page that shows a list the attributes that will be returned to the SP. It asks the user to agree to send this information to the SP.
The user can agree to this release. Their consent will be recorded in a cookie for future transactions with the same SP. Their login will proceed with step 4, passing the SAML message back to the SP.
If the user does not agree to the consent, they are asked to stop the login and close their browser. AR does not give the user the ability to cherry-pick which attributes will be released. We have already negotiated the list as part of our registration process. The only options are to allow the release, or not to login at all.
AR used to be provided by a third-party module called uApprove. The flow is essentially the same, except that uApprove stored releases in a database, and not in browser cookies.
