Configure a New Shibboleth Client (Relying Party)

If you have a new instance of a service that already has a Shibboleth connection, say a new Salesforce application, then look at the pages documenting that particular service. This describes what you need for completely new applications.

Shibboleth creates a "letter of introduction" from Yale to an application or external service. Computer services exchange information in XML format, and for this subject matter they use a particular form of XML called "SAML". Shibboleth generates a SAML Response (to a Request that may have come from the service or may have been internally generated). The application or remote service is called a Relying Party (RP) because it relies on the information supplied by Shibboleth to accurately represent what Yale knows about the user. The SAML response is most commonly written to the Browser and then immediately POST-ed to the login page of the Relying Party.

Shibboleth needs to know a unique identifier (the providerid) for the Relying Party and the URL of the login page. Shibboleth will supply the user's Netid to anyone and can be configured (based on the providerid) to include additional attributes, most commonly a first name, last name, and email address, if configured to do so. The Relying Party needs the URL of Shibboleth to redirect the Browser, and it needs an X.509 Certificate containing Shibboleth's Public Key so it can verify that any Response it gets actually came from Yale's Shibboleth and that the information in the Response has not been altered.

What the Application Needs to Know

Yale Metadata

There is a standard SAML configuration file with all the information you need to configure the Yale Shibboleth Identity Provider. This Yale Metadata file can be downloaded from Shibboleth itself, and many systems that support SAML login will accept this file (or the URL to load the file) in their configuration forms or files. During initial setup, we recommend using the TEST Shibboleth server until we both verify that your system is getting the data it needs to complete the login. Then you should reconfigure your application to use Production. The URLs for getting the Metadata file from Shibboleth are:

Production - https://auth.yale.edu/idp/shibboleth

Test - https://auth-test.yale.edu/idp/shibboleth

If the Application Doesn't Read Metadata

A Metadata file contains three important pieces of information in a mass of unimportant XML boilerplate. Some applications will not process the entire Metadata file, but require you to extract just the information they need. This is annoying, but you may have to accommodate them.

The EntityID

Each Identity Provider has a unique character string identifier. Because it has to be globally unique, it is often in the form of a URL. The EntityID is at the start of the Metadata file, but not surprisingly you already know it because it is the URL listed above that use use to access the Metadata file itself. The Production EntityID is:

The Shibboleth SSO URL

Some Applications present a link or button that the user presses to login to Yale Shibboleth. Some present a dropdown list of colleges, and you have to select Yale from the list. Once the Application knows that you are trying to login to Yale, it will need to send your Browser to Shibboleth to do the login. For that, it needs a URL.

Unfortunately, there are two SAML protocols that Applications can use to send the Browser to the Identity Provider. In one protocol, the Application writes a Form to your Browser with the fields already filled in, and then uses JavaScript to instantly press the "Submit" button. This happens so quickly the user never sees the form. This is called "POST Protocol". In the other approach, the Browser is redirected to Shibboleth and the application provides its data to Shibboleth by adding a long string on the end of the Redirect URL (as a parameter following the "?" that starts the "Query" part of the URL). This is called "Redirect Protocol". The Shibboleth Metadata that you can access by clicking on the two links above contain the Shibboleth URL for both protocols. From the production metadata:

So if the application uses POST protocol, it needs the URL from the first line and if it uses Redirect protocol it needs the URL from the second line. If the application is not smart enough to read Metadata and its documentation is not smart enough to tell you which protocol it uses, then we find that most applications use Redirect, so that is probably the first thing to try.

The Shibboleth Signing Certificate

The data Shibboleth sends to the application is digitally signed using a private key that only the Yale Shibboleth Identity Provider knows. Because the TEST Shibboleth sometimes sends TEST data that does not represent real people at Yale, it has its own separate key. To validate the signature, the Application needs a Public Key. The most common way to distribute Public Keys is to embed them in a dummy X.509 Certificate (because the Public Key by itself does not have a standard file format, but a Certificate containing the Public Key does have a standard format and is, therefore, easier to transfer).

The Certificate is a big blob of characters. It is the biggest thing in the Metadata, and is inside some XML tags that clearly identify it as a Certificate:

<ds:X509Certificate>
MIIDIDCC ...
... 3y2rHqF7/sm/aC
</ds:X509Certificate>

The Certificate is encoded as ordinary characters. If you have to provide just the certificate to an application, then you select and cut the characters inside the <X509Certificate> tag (do not include the tag itself) and then paste them into the multiline text box provided by the application.

There is a small chance the application will want to to create a file on disk. If so, then create an empty text with an editor and then past the text into the file. A text file that contains a Certificate typically has a file type of ".crt".

What Yale Shibboleth Needs to Know

Not surprisingly, Shibboleth needs to know the same three things about your application, with minor name changes.

Relying Party Metadata

Shibboleth has to have a Metadata file for your application. If your application doesn't provide one, then we have to make one up. Your Metadata will contain:

EntityID

Your application has to have a unique identifying string. The simplest thing to do is to use a URL, although some application use a computer name, and some just use their company name. Just because it looks like a URL doesn't mean it has to be a real URL. The EntityID has to match character for character, so once you set it you don't change it unnecessarily.

AssertionConsumerService URL

Shibboleth has to know the URL to which it is supposed to send the SAML login. From Shibboleth to the Application, there is only one protocol that anyone uses (POST Protocol). This URL is called the ACS URL.

Certificate

If the application sends data to Shibboleth to trigger the login, and if the application digitally signs that SAML Request message, then Shibboleth needs an X.509 Certificate to validate the signature. However, many applications do not send digitally signed Request objects (because the Application has no content that is particularly secure or needs to be validated) and if there is no signature then there is no need for a Certificate to validate it.

Attributes

Occasionally the Metadata contains a list of attributes. In most cases, however, the attributes will be requested informally by sending Email or by reference to a document on line that lists the attributes you need.

Unfortunately, down through the years many standards were developed to give alternate names to even the simplest attributes. For example, you may think that "firstname" is an obvious attribute. Unfortunately, we have different applications that have asked for "firstName", "FirstName", and "First_Name". The standards, however, tend to favor "givenName" or "GivenName" because in the West the family name is the lastname, but in the East the family name comes first. GivenName is the individual name, whether it comes first or last.

Up to this point I have been describing what is called the "friendlyName" (like FirstName) of the attribute. SAML also has a globally unique standards based "name" property which can be quite unfriendly ("urn:oid:2.5.4.42" or "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"). Even if the application is only interested in the friendlyName, we have to choose some globally unique standards based name as well.

Computers have to be told exactly what to expect. Shibboleth has the given name, family name, email address, and so on, but it needs to know what to call them when it sends that value to the application.

Applications also want a unique identifier, which at Yale is typically your Netid. However, some applications want the identifier to be globally unique, so we add "@yale.edu" to make the Netid globally unique.

Figure out what you need and what you want us to call it. There is now a formal approvals process to release information about people at Yale to particular application providers. You may need to fill out a form and get committee approval.

The Subject

If the Shibboleth SAML Response is a "letter of introduction", then it has a Subject. The Subject is an identifier for the individual, but it may be a meaningless string of numbers.

Some particularly uninformed Applications request us to provide some Attribute in the Subject field. For example, some applications have asked us to supply the Employee Number as the subject.

The problem with this is that the Subject has to have a unique value for every individual at Yale, and Students don't have Employee Numbers. So it is bad practice and we will strongly resist any request to provide individual data in the Subject field. Applications that ask for this do not understand SAML properly. If we have to provide a Subject, there are a few values that are unique and available for everyone who uses Shibboleth (the Netid, the UPI number). In a few cases we will generate a custom Subject field, but the Application has to be really important.

The Attributes are then "attributes about the person identified as the Subject". A lot of Relying Parties are programmed to ignore the Subject and only read the attributes, in which case the Netid may also have to be included as an Attribute even though this duplicates a piece of information already included in the Subject field.

Shibboleth