Shibboleth at NC State » Technical Documentation » How Shibboleth Logins Work

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

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

  1. A user tries to visit a protected resource on a website.

  2. 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.

  3. 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.

  4. The IdP constructs a SAML reply message for the SP and instructs the user's browser to return to the SP.

  5. The browser posts the SAML message to the SP.

  6. The SP decodes the SAML reply, verifies the IdP signature, and uses that to generate an SP session on the website.

  7. 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.

Shibboleth login diagram

For more details, see this trace of a Shibboleth login.

Shibboleth as a Single-Sign-On (SSO) Provider

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.

example Discovery Service page

Attribute Release

Attribute Release (AR) is an extension that we use on the 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.

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.

Shibboleth login diagram