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 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:
https://auth.yale.edu/idp/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.
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 this:
Replace the providerid= and the target= with appropriate values.
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:
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 (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:
<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 application.