Skip to end of metadata
Go to start of metadata

You are viewing an old version of this content. View the current version.

Compare with Current View Version History

« Previous Version 6 Next »

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

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.

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:

https://auth.yale.edu/idp/profile/SAML2/Unsolicited/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 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

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:

Prod Metadata
Test Metadata
Dev Metadata

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:

      <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.

The Netid

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 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.

  • No labels