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.
What the Application Needs to Know
The Shibboleth URL
If the user will go to the application first, and the application will generate a Request form and post it to Shibboleth, then the application needs the URL to which the Request form will be posted. This is:
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:/profile/SAML2/POST/SSO
If the application does not need to send a request and will accept an unsolicited SAML Reply form from Shibboleth, then the application does not need to be configured with any Shibboleth URL. Instead, the URL can be turned into a hyperlink in a Yale Web page. For example, the Yale Portal menu that points to Hewitt ("My Benefits") is a hyperlink direct to Shibboleth that provides the Hewitt login URL as the "target" parameter and the Hewitt SAML providerId as another parameter:
/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%2FytrThere is a component of Shibboleth listening at the "/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://auth.yale.edu/idp/profile/SAML2/UnsolicitedRedirect/SSO"/>
So if the application uses POST protocol, it needs the URL from the first line and when it gets an HTTP GET of this form it generates a dummy SAML Request using these two parameters and then transfers to the normal request processing.
The Yale Certificate
The SAML generated by Shibboleth has been 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. The Relying Party 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
With most applications we have encountered, you typically open these links with a text editor, cut the text version of the certificate, and paste it into a multiline text box in the application SAML SSO configuration form.
Yale Metadata (Everything you could possibly need to know)
Rather than configuring just the information that the application requires to operate, SAML provides a file format for Metadata. Metadata is a complete description of the Shibboleth capability including all the URLs for all the SAML protocols that Shibboleth supports, plus the Certificate. Of course, the application has to understand the format of this file, and since it typically only needs one URL and one Certificate, most applications prefer to just consume the data listed above. However, if you need Yale Shibboleth's own Metadata, it is at:
Prod Metadata
Test Metadata
Dev Metadata
What Yale Shibboleth Needs to Know
Anonymous (No Configuration) Netid only
Yale's Shibboleth will transmit a digitally signed SAML Response object to any partner login URL. No configuration is required in Shibboleth as this is the default for any unconfigured providerId.
By definition, any non-anonymous partner either generates a signed SAML Request that Shibboleth must process (and therefore Shibboleth requires the Certificate of the partner to validate the request) or else the partner requires other attributes that Shibboleth will not release unless configured to do so.
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.
If a Relying Party does not send digitally signed Requests, and it accepts the usual SAML 2 Response formats, and the only thing special is a list of special attributes, it may not be necessary to provide a Metadata file (Shibboleth has a default for everything and if the partner requirements match all the defaults you are in luck).
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 the "eduPersonEntitlement" attribute. A large number of the attributes used in SAML started out in one or more LDAP directory standards. LDAP has a "Person" which is extended with additional attributes by the "OrganizationPerson" standard which is then extended with more attributes by the "InetOrgPerson" standard which (for universities) is extended by the "eduPerson" standard. So if you happen to choose any attribute name in one of these standards, these LDAP standards carry along all the information ID Management needs to format the attribute Response.
However, LDAP is based on formats and ideas that predate the Internet, so if someone needs an attribute that is not in any of these standards, there is some uncertainty. Typically the attribute has a simple name like "clientId" and then a very long and complex unique identifier. When the unique identifiers are not specified by LDAP standards, Microsoft strongly advocates that they be identified with a Web URN. Fortunately, almost nobody actually cares about the long unique identifier and partners typically process only the unstandardized short simple name and ignore the rest of the XML boilerplate.
If the partner provides documentation on the attributes and their formats, include a reference to it in the Change Request.
The Netid
The most common information, the Netid, has a special feature. A SAML statement is a set of "Assertions" about a "Principal". Some of the Assertions are "Authn" statements about how the Principal authenticated, and the rest are attributes about the Principal.
The Netid is simultaneously the Principal name and also one or more Attributes about the Principal. Some Relying Parties who are looking for the Netid may expect it to be the Principal name, while others may expect it to be a specific Attribute with a specific attribute name. If it is an Attribute, then it is just like all the other attributes described above. Although we will give out the Netid to anyone who asks, we will not name it "bizzareAttributeName" unless we are configured to call it that. If the partner will use the Principal name, then that typically involves configuration of the remote applicationBecause 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.