NSDL, Explore Share Learn Create with the National Science Digital Library National Science Digital Library
 

Community Sign-On Implementation Roadmap for NSDL Sites

This document gives an overview of the steps it takes for a website to enable NSDL community sign-on. Some steps only apply to sites with an existing user registration system.

  1. Contacting the NSDL Access Management People

    The folks responsible for NSDL Community Sign-On are at Columbia University.

    • Rob Lane <[email protected]> (your main contact)
    • Carol Kassel <[email protected]>
    • Andrew Johnston <[email protected]>
    • David Millman <[email protected]>

    We hope and expect to be in regular contact with you throughout your process of joining Community Sign-On. We can offer you whatever level of support you need. At a minimum we'll add your site to the federation, issue you a certificate, and answer any questions, but we can go as far as to install all the software and configure it, test and debug. Once Shibboleth works, integrating it properly into your site will generally fall to you, though we will of course help you understand (and decide) how to do it.

  2. Registering Your Site

    The websites that support NSDL community sign-on comprise what's called a federation in Shibboleth. The federation entails trust relationships among the sites, and standardizes a user attribute vocabulary. For more on Shibboleth federations, see http://www.switch.ch/aai/federation/.

    We operate a test NSDL federation alongside the real production one. The federation sites metadata is hosted centrally at https://registry.auth.nsdl.org/nsdl-fed/test/shib-1_2/nsdl-sites.xml, and the trust metadata at https://registry.auth.nsdl.org/nsdl-fed/test/shib-1_2/nsdl-trust.xml. Sites, including yours, check automatically every half-hour for updates, which allows new sites to join the federation on the fly.

    Once we've established the url's of your services and we've issued certificates (as discussed for the Service Provider and Identity Provider respectively below), we'll add your information to the federation metadata.

  3. Setting Up Your Shibboleth Service Provider

    A website that uses shibboleth for access control is called a Service Provider (SP). The shibboleth SP software includes a web server module, for Apache or IIS, and an executable daemon called the shibboleth attribute requester (shar).

    1. Policy

      You'll need to decide what level of access to grant users from other Identity Providers (IdP's). Most sites give all users full access. But if, for instance, your site requires a paid subscription, you'll only want to let in people who've paid.

    2. Getting the Software

      If binaries are available for your platform you can use those; if not, you'll need to build shibboleth and its dependencies. You can download shibboleth from https://wayf.internet2.edu/shibboleth/. The shibboleth and opensaml packages include pretty good build instructions. If your platform offers packages for any of the dependencies, you should use them.

    3. Configuration

      On unix-like systems we typically put the shibboleth configuration files in /etc/shibboleth. Among the things configured here are:

      • name of your site within the federation
      • log file location (typically /var/log/shibboleth on *nix)
      • certificate and private key for identifying self when making attribute requests
      • translation from shibboleth attribute names to pseudo http headers (your application can then retrieve the user attributes from the headers)

    4. The Shibboleth Attribute Requester

      The shar should not run as the superuser, it should have its own service user (typically "shib"). If your platform is *nix, we'll provide you with a /etc/init.d script. The startup script is responsible for switching to the service user and for pointing to the configuration (typically in /etc/shibboleth).

    5. Key and Certificate

      When the shar connects to an IdP to request attributes, it authenticates itself using SSL client auth. You'll create a private key and generate a certificate request, and we'll issue you a certificate from the NSDL certificate authority.

      The service user (shib) will need to have read access to the private key. Don't forget to be careful with your private keys.

    6. Web Server Configuration

      You'll configure your web server to load the shibboleth module and to activate shib for some or all url's.

      If your site doesn't already do https, you'll need to configure your web server for it, and you'll want to buy a cert from a commercial CA for it (https://yoursite.org/). You don't have to put your whole site behind https, but the page that users bounce to momentarily after signing in through shibboleth does have to be https.

  4. Setting Up Your Shibboleth Identity Provider (if applicable)

    Skip this section if your site doesn't have an existing user registration system.

    A website that has an existing user registration system typically will host its own Shibboleth Identity Provider (IdP). Your site's users will sign in to your site, as well as other NSDL sites, through your IdP.

    A Shibboleth Identity Provider consists of two services: the sign-on service and the attribute authority (AA). The sign-on service is where a user types his or her username and password to sign in. The attribute authority is the service that web sites query behind the scenes to get information about the user attempting to sign on.

    1. Privacy Considerations

      When your users sign in to other NSDL websites, your IdP provides information about them to these sites. You will need to decide how much of your users' information to release to other sites.

      The log files shibboleth produces can contain personal information about your users.

    2. Web Server Configuration

      The attribute authority uses SSL client certificate authentication to verify the identities of attribute requesters. If you are using Apache 2.0 you'll need two IP addresses assigned to the host, one each for the sign-on service and the AA. These two virtual interfaces will need names like signon.yoursite.org and aa.yoursite.org respectively.

      Since users will be visiting https://signon.yoursite.org/* in their browsers, you'll want to buy a certificate for it from a commercial cert authority.

      We'll issue you a cert for https://aa.yoursite.org/. We'll also provide you with the trusted CA bundle to be used for SSL client auth. Your webserver configuration will reference that file.

    3. Setting Up the Software

      The IdP software is a java web application. If your site has a servlet environment available you'll use that; if not you'll need to install Tomcat, an open source servlet container. If you use Apache, you'll hook it up to Tomcat with mod_jk.

      We'll provide you with a Shibboleth IdP software skeleton package customized for the NSDL. We have a Service Provider set up and available for you to test against.

      The IdP software package contains a number of configuration files that you'll need to customize for your site. Among the things these configuration files specify are:

      • name of your IdP within the federation
      • log file location
      • certificate and private key for signing assertions
      • how to connect to your user data backend
      • translation from your user attribute names to the NSDL controlled vocabulary (which is based on eduPerson)
      • your attribute release policy

      The IdP package also contains the login web page, which you'll want to customize for your site.

  5. Integrating Shibboleth Into Your Site

    1. Sign-On Flow

      Websites with existing user systems may have a login form on the front page or on more than one page in the website. Whatever the case, the login flow will have to be redone to incorporate shibboleth. A login flow incorporating shibboleth typically follows a combination of these two patterns:

      • some pages are open and some are protected; protected pages bounce unauthenticated users to shibboleth sign-on
      • the front page, or every page, has a "Sign In" link; users only get full access once they've signed in

    2. Handling Users from Other IdP's

      1. First-Time Users

        Your site will need to be able to handle users who sign in through Identity Providers other than your own. The first time such users arrive, you won't have any information about them in your user database. You'll need to create an entry in the user table when a new user from another IdP arrives for the first time.

      2. Data Backend

        It's likely that you'll need to modify the architecture of your user data backend. Typically it's sufficient to allow null passwords in the user table. The opaque id from shibboleth (eduPersonTargetedId) will go in the username field. Users from other IdP's will be distinguished by their null passwords. The null passwords will also serve to prevent these users from signing in through your IdP. If the other information you store in your data backend keys off the user table, it should work seamlessly for the new users.

      3. Attributes

        You'll get some information about the user from shibboleth. However, you may not get very much. You can expect at least to get an opaque persistent identifier called the eduPersonTargetedId (if you don't get that, you can deny access). You'll use the opaque id to recognize users when they return to your site.

        If there's a piece of user information that you use on your site, you may or may not get it from shibboleth for a given user. If you don't, you might ask the user for it, or you might fill it in with a sensible default.

  6. Deployment

    Once everything works in the test environment it's ready to move into production. This will entail some or all of the following for your site:

    • we'll put your site's production information into the production federation metadata
    • you'll point your configuration to the production metadata
    • if you've been using self-signed certificates up to this point, you'll want to buy your commercial certs now
    • you may have to add the second IP address on the production IdP box
    • some url's in your configuration files will change
    • if you've been using a test data backend, you'll need to modify the production backend as you did the test one, and then change your configuration to point to it