...
What the Application Needs to Know
The Shibboleth URL
If the user starts with the application URL and the application sends the user back to Shibboleth, then the application needs to know the Shibboleth URL. In almost every case the applications build a SAML (XML) Request identifying their organization and asking Shibboleth to send the data. When this request is POST-ed to Shibboleth, the application needs the URL of the Shibboleth function that handles a posted request:
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:/profile/SAML2/POST/SSO
There is an alternate mechanism in the SAML standard where the application redirects the browser to Shibboleth with the request encoded as a parameter on an GET request, but because the Web standards limit the maximum legal size of a GET URL, this is a dangerous technique and the POST is universally preferred.
Although the SAML protocol requires a Request, the only information that Shibboleth needs from the request is the providerid and the URL to which the Response is to be sent. Some Relying Parties send an Request ID and require that it be included in the Response, but most programs don't require this. If the application doesn't care about Request ID, then you can save a few milliseconds of time and simplify use and testing by asking Shibboleth to generate a dummy Request internally. All you have to do is to supply the providerid and login URL to Shibboleth at the URL below:
/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:
<EntityDescriptor entityID="https://auth.yale.edu/idp/shibboleth">
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:
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://auth.yale.edu/idp/profile/SAML2/UnsolicitedPOST/SSO?providerId=hewitt.com:saml2.0&target=https%3A%2F%2Fsso.hewitt.com%2Fytr
This is an example from portal.yale.edu where a Portal menu triggers login to the My Benefits application supplied by external vendor hewitt.com. If Yale is going to generate the Request, then the vendor really doesn't need to know the Shibboleth URL, but it will almost certainly require you to provide it because it doesn't know you are really going to bypass its own Request generation.
The Yale Certificate
The SAML generated by Shibboleth has been "/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://auth.yale.edu/idp/profile/SAML2/Redirect/SSO"/>
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. The Relying Party (application) has to be configured with an X.509 Certificate containing the public key that can be used to validate the SAML message to ensure that it was really sent by Yale and has not been altered. There are separate Certificates for dev, test, and prod:
Prod: auth.yale.edu
Test: auth-test.yale.edu
Dev: auth-dev.yale.edu
These are not the SSL certificates used by the Web server. They are self-signed Certificates that simply act as a wrapper for the public key. They have no "root CA" and do not depend on a certificate chain. They have to be manually distributed from Yale and installed in the configuration files of the remote Relying Party. This is the usual convention with SAML IDPs.
A Certificate file is a text file that encodes a binary format as text. You might download the file and then upload it to the SSO configuration form of a Relying Party application, but because it is text the most common mechanism is open the file in a text editor, select all, copy to the clipboard, then paste the text into a multiline text box in the SSO configuration form of the remote application.
Every X.509 Certificate contains data fields in a special encoding format. There is a Distinguished Name, Common Name, Issuer, and so on. Even though the remote application can get all this information from the Certificate, it sometimes requires you to enter some of this data into other text fields on the form. It then checks to verify that the content of the text fields matches the content of the Certificate. If you simply click on the certificate file in Windows you will launch a special Certificate Viewer dialog which allows you to display all the data in the Certificate. You typically do not, however, want to install this Certificate in your Windows store unless your Relying Party application is a Windows program that requires it to be installed on that server.
Yale Metadata
SAML has a standard configuration file format with all the data for an Identity Provider (Shibboleth) and all the data for a Relying Party. SAML calls this Metadata. Technically an RP only needs the Shibboleth URL and Certificate, and sometimes you just past these two pieces of data into two fields of some configuration form. But sometime the RP will prefer to consume the entire Metadata file and pull these two pieces of information out of it. If you need Metadata, you can get it from the following locations:
Production - https://auth.yale.edu/idp/shibboleth
Test - https://auth-test.yale.edu/idp/shibboleth
What Yale Shibboleth Needs to Know
Anonymous (No Configuration) Netid only
Shibboleth will transmit a SAML Response containing your Netid to any Relying Party. If that is the only piece of information you need, then all Shibboleth requires is a providerid, typically the name of a company or a computer.
Relying Party Metadata
As with the Yale Metadata described above, the simplest thing to configure (although the most complicated thing to understand) is for the Relying Party to provide its own Metadata file. This file will contain its Certificate (to validate the digital signature of a request), its SAML login URL (to which Shibboleth sends the SAML Response message), and a list of attributes that the partner may require.
Typically Metadata is published at a URL. Obtain the URL (or a copy of the Metadata file) and put it in your Change Request addressed to ITS ID Management.
Attributes
Typically the Metadata file will contain a list of the required attributes. For example:
| Code Block |
|---|
<md:AttributeConsumingService index="1"
isDefault="true">
<md:ServiceName xml:lang="en">Mediasite</md:ServiceName>
<md:RequestedAttribute isRequired="true"
Name="urn:mace:dir:attribute-def:eduPersonEntitlement" />
</md:AttributeConsumingService>
|
In this example, Mediasite requires an attribute named "eduPersonEntitlement".
There are a few attributes that everyone understands (first name, last name). Unfortunately, these attributes are so well known that they have been used down through the years and have several different names in different standards. First name is "givenName" and last name is "sn" (short for surname) in some international standards. So Shibboleth needs to know not only the attribute, but also the name the attribute should be given.
SAML also defines a set of named attribute formats. The problem is that a simple attribute like Netid can be reported to have format "unspecified", or it can be "a character string", and frequently someone will want it to claim to be in the format of "an E-Mail address" even when it isn't a real E-mail address. Each attribute is sent with a name and a format id, so if the Relying Party wants the format id to be a specific value Shibboleth needs to know to generate that specific format name.
The partner Metadata (or a written specification) will tell ITS just exactly how to generate the SAML boilerplate for an attribute. It does not, however, tell us which value to plug into the Attribute assertion. That requires a real discussion with a real person.
Some Relying Parties ask for "mail", the standard name for E-Mail address. Unfortunately, someone at Yale may have more than one E-Mail account (netid@pantheon.yale.edu, netid@connect.yale.edu, firstname.lastname@bulldogs.yale.edu) and may have more than one E-Mail alias (Firstname.Lastname@yale.edu, Firstname.Lastname.eliapps@yale.edu) where the alias is configured to point to a specific account. Over time, the alias may be redefined to point to a different account (if a user's mail migrates), and the alias name may change. Most people at Yale have no idea how complex this can be, and yet when you are making decisions about how Yale interacts with an external partner you have to configure a result that will work for everyone, not just for the simple cases. This is why even seemingly simple attributes sometimes have to be discussed with ITS Identity Management to choose the right value to release from the set of available options.
...
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. Unless requested otherwise, Shibboleth will automatically include the Netid of the user as the SubjectThe 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.