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
...
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.However, the application doesn't have to send a Request at all. Shibboleth will generate one if you give it just the "providerid" (the name of the application as it was configured to Shibboleth) and
the URL of the application's logon page. By example, the Yale Portal contains a link to the MyBenefits function provided by partner Hewitt. Yale generates a dummy Request from the parameters provided in the link, so the first time the user actually goes to the Hewitt server he already has the Shibboleth generate SAML Response with the data needed to logon to Hewitt. The Portal link looks like thisAlthough 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:
https://auth.yale.edu/idp/profile/SAML2/Unsolicited/SSO?providerId=hewitt.com:saml2.0&target=https%3A%2F%2Fsso.hewitt.com%2FytrReplace the providerid= and the target= with appropriate values
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 digitally signed using a private key that only Shibboleth knows. 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:
...
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
...
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 atSAML 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:
Prod Metadata
Test Metadata
Dev Metadata
...
Anonymous (No Configuration) Netid only
Yale's Shibboleth will transmit a digitally signed SAML Response object containing your Netid 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 soRelying 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.
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:
...
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. What is that??
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. Less commonly, it also needs to know the format, so Birth Date might be January 2, 1995 or 01/02/95, or 1995-01-02.
There are other attributes that can only be understood in the context of Yale University IT systems. If the other system needs your E-Mail address to send you messages, then probably Shibboleth will want to send what Yale calls your "Primary E-Mail Alias" which is frequently Firstname.Lastname@yale.edu. However, if a user has requested Privacy (an option required by Federal law) then the user will not be listed in normal Yale directories and releasing his secret E-Mail alias may require approval. There is also a system specific E-Mail address, such as Firstname.Lastname@bulldogs.yale.edu, which is different from the generic E-Mail alias. Also, your E-Mail alias can be changed, and this can confuse certain Relying Parties, although your Netid almost never changes.
So releasing additional attributes may require a discussion with Yale ITS Identity Management to make sure that the information is being released properly, with the right attribute name, and in the right format.
If the partner provides documentation on the attributes and their formats, include a reference to it in the ServiceNow 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 applicationIf 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 Subject.
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.