Shibboleth User Verification

Customer Implementation Guide

Version 2.1 January 31, 2012 e-academy Inc [CONFIDENTIAL]

TABLE OF CONTENTS
INTRODUCTION ................................................................................................................................................................ 3 PURPOSE AND TARGET AUDIENCE ................................................................................................................................................. 3 ABOUT THIS DOCUMENT ............................................................................................................................................................. 3 COMMONLY USED TERMS ........................................................................................................................................................... 4 OVERVIEW OF SHIBBOLETH SIGN ON PROCESS ................................................................................................................. 5 WHAT IS SHIBBOLETH? ............................................................................................................................................................... 5
E-ACADEMY CUSTOMER IMPLEMENTATION SCENARIOS ..................................................................................................................... 5

HOW SHIBBOLETH WORKS .......................................................................................................................................................... 6 Customer Experience Diagram ......................................................................................................................................... 7 NEXT STEPS .............................................................................................................................................................................. 8 CONFIGURING YOUR IDENTITY PROVIDER ........................................................................................................................ 8 METADATA AND E-ACADEMY ENTITY IDS ....................................................................................................................................... 8 ATTRIBUTES.............................................................................................................................................................................. 8 ELMS CONFIGURATION ................................................................................................................................................... 12 ACCESSING ELMS ADMINISTRATION ........................................................................................................................................... 12 FINDING YOUR ACCOUNT NUMBER ............................................................................................................................................. 12 TURNING ON SHIBBOLETH FOR YOUR WEBSTORE ...................................................................................................................... 13 Defining the Verification Type ........................................................................................................................................ 13 Configuring Shibboleth ................................................................................................................................................... 14 TESTING YOUR INTEGRATION ......................................................................................................................................... 15 TESTING YOUR INTEGRATION ..................................................................................................................................................... 16 Test using e5Demo Entity ID .......................................................................................................................................... 16 Test using e5 Production Entity ID .................................................................................................................................. 16 TESTING THE WORKFLOW ......................................................................................................................................................... 16 VALIDATION ........................................................................................................................................................................... 17 SUPPORT ........................................................................................................................................................................ 17
Page 2 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

INTRODUCTION
This section covers the following areas:

Purpose and Target Audience About this Document Commonly Used Terms

PURPOSE AND TARGET AUDIENCE

Only authenticated users can order software in your WebStore. The ELMS Administrator must define how their users are authenticated referred to as methods of verification. There are many methods of verification that can be used to authenticate users including email domain, user import, Integrated User Verification (IUV) and Shibboleth (from a Federated Identity Program). This document gives you detailed instructions for establishing a single sign-on mechanism between an e-academy customers existing Shibboleth identity provider and an e-academy ELMS WebStore. This document is aimed primarily at ELMS Administrators or web developers who have been assigned to the IUV Administrator role in ELMS or who manage identity services for their institution.

ABOUT THIS DOCUMENT

Read this document in conjunction with the online help available in the e5 Administration website. The following is a list of the chapters in this document with short descriptions of their contents:

Overview of the Shibboleth sign on process o What is Shibboleth? o e-academy Customer Implementation Scenarios o How it works Configuring your Identity Provider o Metadata and e-academy Entity IDs o Attributes ELMS Configuration Testing your Integration Support

Page 3 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

COMMONLY USED TERMS

Term ELMS / e5 Customer Definition/description e-academy License Management System An e-academy customer (such as a college or university) that is using IUV to authenticate shoppers to use an ELMS WebStore. In the ELMS Administration website, a customer is defined as an Organization. User that is being signed in to an ELMS WebStore.

Shopper

WebStore

An e-academy ELMS e-commerce website that provides products for sale on behalf of the customer.

ELMS Administration

Secure administration module in ELMS that contains functions to manage a WebStore as well as set up IUV. This module is accessible by authorized users only.

Shibboleth

From http://shibboleth.internet2.edu: The Shibboleth System is a standards based, open source software package for web single sign-on across or within organizational boundaries. It allows sites to make informed authorization decisions for individual access of protected online resources in a privacy-preserving manner.

Identity Provider (IdP)

The software used by an organization with users wanting to access a restricted service.

Service Provider (SP)

The software run by the provider managing the restricted service (for example, eacademy).

EntityID

Unique name of an identity (IdP) or a service provider (SP) within a Shibboleth deployment. e-academy has both testing and production EntityID values. - Testing: https://e5demo.onthehub.com - Production: https://e5.onthehub.com

Metadata

Configuration data used by identity (IdP) and service providers (SP) to communicate with each other.

Attributes

Assertions made by an identity provider about a person, such as an email address or a unique identifier.

WAYF

Where Are You From discovery services

Page 4 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

OVERVIEW OF SHIBBOLETH SIGN ON PROCESS

This section covers the following areas:

What is Shibboleth? e-academy Customer Implementation Scenarios How Shibboleth Works o Customer Experience Diagram Next steps

WHAT IS SHIBBOLETH?
Shibboleth is a single sign-on (SSO) system that has achieved widespread adoption in academic communities worldwide. Reasons for this range from its academic and open source origins to its model of privacy protection that gives individuals and institutions a great deal of control over what personal information is released to external parties. Shibboleth is often used by a federation or group of institutions. For example, InCommon is a federation of organizations in the United States. The Canadian Access Federation is a group offering Shibboleth services to Canadian educational institutions. For those requiring background information about Shibboleth, refer to the projects website at http://shibboleth.internet2.edu/, Step-by-step demos of the sign on process are available at http://www.switch.ch/aai/demo/easy.html.

E-ACADEMY CUSTOMER IMPLEMENTATION SCENARIOS

Customers using Shibboleth with ELMS must be members of a federation of which e-academy is a Service Provider (see Table 1: Federation List below). Scenario 1: ELMS WebStore for a SINGLE federation member This scenario involves a single e-academy customer (or organization) belonging to a federation being deployed their own WebStore and is directly integrated to the federation without users having to choose their organization through the use of discovery services (WAYF). Scenario 2: ELMS WebStore for ALL members of a federation This scenario involves the deployment of an ELMS WebStore for ALL members of a federation. During the sign on process, the WebStore points the user to a discovery services website (WAYF) where they choose the organization they belong to.

Page 5 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

Scenario 3: ELMS WebStore for a SUBSET of federation members This scenario involves the deployment of an ELMS WebStore for a subset of federation members. This scenario requires custom development by e-academy.
Table 1: Federation List

Federation InCommon WAYFDK Canadian Access Federation (CAF) SWITCHaai UK Federation SWAMID Haka Belnet RCTSAAI Edugate DFN-AAI RENATER IDEM

Country United States Denmark Canada Switzerland

Supported by ELMS? Yes Yes Yes Yes Yes

Sweden Finland Belgium Portugal Ireland Germany France Italy

Yes Future Future Future Future Future Future Future

HOW SHIBBOLETH WORKS

The following are typical steps in a Shibboleth sign on to an ELMS WebStore: Shopper arrives at ELMS WebStore: When the shopper clicks the link to sign in or performs an action that requires authentication (for example, adding an item to a shopping cart), the Shibboleth Service Provider (SP) software integrated with the ELMS WebStore redirects the shopper the customers site or to a remote discovery service (WAYF) if necessary. Shopper chooses home organization: This step is not usually necessary, but is available for cases when more than one member of a federation accesses the same ELMS WebStore. The discovery service provides the shopper with a list of
Page 6 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

organizations from which the shopper chooses his or her home organization and subsequently redirects the shopper to the customers site. Customer site authenticates shopper: The customers site prompts the shopper for his or her credentials, and authenticates the user. This authentication is coordinated by the customers Shibboleth Identity Provider (IdP) software. The IdP builds a minimal set of attributes for the shopper that are required by e-academy. The site then redirects the shopper back to the ELMS WebStore. ELMS WebStore authenticates shopper: The attributes released by the customers IdP are used to create a set of credentials on the ELMS WebStore (user account). This action completes the verification process and the original page requested by the shopper is displayed.

CUSTOMER EXPERIENCE DIAGRAM

ELMS

Discovery (WAYF)

Customer IdP

Shopper clicks Sign In link

Shopper chooses home organization (if required) ELMS processes shopper attributes

Shopper enters username and password

Shopper begins shopping!

Page 7 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

NEXT STEPS

+
Configure your IdP (Identity Provider) Release attributes to e-academy Entity IDs Configure ELMS to communicate with your IdP

TEST YOUR INTEGRATION

CONFIGURING YOUR IDENTITY PROVIDER

This section covers the following areas:

Metadata and e-academy Entity IDs Attributes o Attribute List Attribute Reference

METADATA AND E-ACADEMY ENTITY IDS

If your organization is an Identity Provider in a federation that has accepted e-academy as a Service Provider, then each will be found in the metadata published by the federation.

e-academy Entity IDs

The following are the entity IDs used by e-academy: Production: Testing: https://e5.onthehub.com https://e5demo.onthehub.com

ATTRIBUTES
The minimum set of identity assertions required by e-academy is the following: a unique identifier for a shopper o this allows the shopper to be identified across multiple logins a list of group affiliations

Page 8 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

This gives the shopper access to products that are restricted to members of specific (academic) groups. For example, a product may only be available to faculty or staff members of a university.

Further identity assertions may be made (passed during integration) to further personalize the ELMS WebStore for your users. For a list of attributes, see Table 2: Attributes below.
Table 2: Attributes

Attribute

Description Unique identifier for a user. If opaque, it may be desirable to use the Hide Username setting (see Table 3: Settings). Unique identifier for a user.

eduPersonTargetedID
urn:mace:dir:attribute-def:eduPersonTargetedID: urn:oid:1.3.6.1.4.1.5923.1.1.1.10

persistent ID (SAML 2.0)

urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

uid
urn:mace:dir:attribute-def:uid urn:oid:0.9.2342.19200300.100.1.1

Unique identifier for a user.

SwissEP_UniqueID
urn:mace:switch.ch:attribute-def:swissEduPersonUniqueID urn:oid:2.16.756.1.2.5.1.1.1

Unique identifier for a user (SWITCHaai).

eduPersonPrincipalName
urn:mace:dir:attribute-def:eduPersonPrincipalName urn:oid:1.3.6.1.4.1.5923.1.1.1.6

Unique identifier for a user. Can be used in combination with other unique IDs in which case eduPersonPrincipalName will be a users username, and the other ID will be captured as the member identifier on a user verification. Grants eligibility to a user through user group membership. Attribute value maps to user group as follows: Student -> Students Faculty -> Faculty Staff -> Staff Employee -> Faculty/Staff Member -> Students/Faculty/Staff

eduPersonScopedAffiliation
urn:mace:dir:attribute-def:eduPersonScopedAffiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.9

eduPersonAffiliation
urn:mace:dir:attribute-def:eduPersonAffiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.1

Grants eligibility to a user. Same mapping as scoped attribute. Grants eligibility to a user. Same mapping as scoped attribute. Used for custom user group or organization mapping. Multi-value, use comma or semi-colon delimiters. Values may be qualified, for example,
Page 9

eduPersonPrimaryAffiliation
urn:mace:dir:attribute-def:eduPersonPrimaryAffiliation urn:oid:1.3.6.1.4.1.5923.1.1.1.5

isMemberOf
urn:mace:dir:attribute-def:isMemberOf urn:oid:1.3.6.1.4.1.5923.1.5.1.1

Shibboleth User Verification: Customer Implementation Guide v2.1

e-academy CONFIDENTIAL

urn:mace:example.edu:groups:groupCode. The last portion of the qualified values are used when matching against system codes.

For user groups, values will be matched against User Group Code fields found in the e5 Administration website under Users User Groups section. The value grad_students might be the code for a custom user group and, when matched, the user will be granted membership in the group. For organizations, values will be matched against External Organization Code field found in the e5 Administration website under Organization for the WebStore organization or any of its affiliated organizations. When a match is made, a user verification will be created for the user linking them to the organization with any corresponding user groups. This can be used, for example, to specify that a user is a student in a specific department.

eduPersonEntitlement
urn:mace:dir:attribute-def:eduPersonEntitlement SAML2: urn:oid:1.3.6.1.4.1.5923.1.1.1.7

Used for custom user group or organization mapping. See isMemberOf for details on how values are mapped. Values are URIs of the form http://[SP]/eligibility/[IdP]/[code]. Example: http://eacademy.com/eligibility/example.edu/compSciSoftware.

The value is expected to be a resource, true to the purpose of the attribute, but currently these can only be mapped to organizations or user groups.

ou
urn:mace:dir:attribute-def:ou urn:oid:2.5.4.11

Used for organization mapping. Multi-valued, comma or semi-colon delimiters are expected. Values will be matched against External Organization Code field found in the e5 Administration website under Organization for the WebStore organization or any of its affiliated organizations. When a match is made, a user verification will be created for the user linking them to the organization with any corresponding user groups. This can be used, for example, to specify that a user is a student in a specific department.

eduPersonOrgUnitDN
urn:mace:dir:attribute-def:eduPersonOrgUnitDN urn:oid:1.3.6.1.4.1.5923.1.1.1.4
Page 10 Shibboleth User Verification: Customer Implementation Guide v2.1

The distinguished name (s) of the directory entries representing the users organizational unit. Used for organization mapping. Multi-valued, pipe (|)

e-academy CONFIDENTIAL

characters are expected as delimiters. Values are expected in the DN form, e.g. ou=Potions, o=Hogwarts, dc=hsww, dc=wiz. In the example case, Potions would be the parsed value and would be matched against External Organization Code fields (see ou).

Surname
urn:mace:dir:attribute-def:sn urn:oid:2.5.4.4

Users surname.

givenName
urn:mace:dir:attribute-def:givenName urn:oid:2.5.4.42

Users given name.

mail
urn:mace:dir:attribute-def:mail urn:oid:0.9.2342.19200300.100.1.3

Users email address.

homeOrganization
urn:mace:switch.ch:attribute-def:swissEduPersonHomeOrganization urn:oid:2.16.756.1.2.5.1.1.4

The organization the user belongs to (SWITCHaai).

homeOrganizationType
urn:mace:switch.ch:attribute-def:swissEduPersonHomeOrganizationType urn:oid:2.16.756.1.2.5.1.1.5

The type of organization the user belongs to. A value of university or uas is required for the user to be granted academic eligibility (SWITCHaai).

Page 11 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

ELMS CONFIGURATION
This section covers the following areas:

Accessing ELMS Administration Finding Your Account Number Turning On Shibboleth for your WebStore o Defining the Verification Type o Configuring Shibboleth

To configure Shibboleth verification in ELMS, you must be a registered and active ELMS Administrator or web developer who has been assigned to the IUV Administrator role in ELMS.

ACCESSING ELMS ADMINISTRATION

Before you configure Shibboleth, e-academy recommends that you access the ELMS Administration website from the WebStore. To access the ELMS Administration website from the WebStore : 1. 2. 3. 4. 5. Enter the URL of your WebStore into your browser. Click the Sign In link in the top right corner of the page. Enter your Username. Enter your Password. Click the Sign In button.

Once you are successfully authenticated, you will be signed into your WebStore. At the top of the screen, multiple links are displayed. Click the Administration link to access the ELMS Administration website. A new window opens.

FINDING YOUR ACCOUNT NUMBER

The ELMS account number is a unique identifier for your organization. This number is required to sign into the ELMS Administration website without going through the WebStore. If you set up Shibboleth and it is configured incorrectly, you will not be able to access the ELMS Administration website through the WebStore to make the necessary changes to correct the configuration. You can access the ELMS Administration website via a special sign in page. When you sign out of the ELMS Administration website, you see a different Sign In page. This sign in page is not branded. See below:

Page 12 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

This page requests your Account Number and username/password. It provides quick access to the ELMS Administration website without having to go through the WebStore. To find your Account Number: 1. 2. 3. 4. Sign into your WebStore. Click the Administration link. On the main menu, go to Organization. Note the Account Number displayed on the Details page.

Using this information, you can now sign in directly to the ELMS Administration website by going to https://e5.onthehub.com/admin.

TURNING ON SHIBBOL ETH FOR YOUR WEBSTORE

To turn on Shibboleth integration in ELMS, you must first have Shibboleth set up as a verification type.

DEFINING THE VERIFICATION TYPE

You must be signed into the ELMS Administration website. To set up Shibboleth as the verification type: 1. 2. On the Main menu, go to WebStore. Click the Verification tab. The list of currently configured verification types are displayed on the page. By default, User Import or a different verification type may have been configured for your WebStore when it was deployed. Click the checkbox beside any verification type that is not Shibboleth and then click the Delete button. Click the Add button. A new window opens. Click the check box beside Shibboleth. Click the OK button to save your selection.

3. 4. 5. 6.

Page 13 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

CONFIGURING SHIBBOLETH
Once Shibboleth has been defined for your organization, you need to configure it. To configure Shibboleth: 1. 2. 3. On the Main menu, go to WebStore . Click the Verification tab. Click the check box beside Shibboleth. A new window opens with two tabs: Details and Settings.

DETAILS TAB
Use care if you want to change the default values for Sector and Verifications Expire In. Changing these values could break your implementation resulting in your end-users not being able to sign into the ELMS WebStore.

SETTINGS TAB
The Settings page defines all of the customer (organization) information that is required by e-academy. See Table 3: Settings.
Table 3: Settings

Information Relying Party

Required? Yes

Description List of Shibboleth identity providers that the ELMS Shibboleth Service Provider has been configured to work with. This list is made up of federations that e-academy is a member of (for example, InCommon, SWITCHaai) along with individual organizations that have custom implementations. Typically, you will be choosing the federation with which your organization has membership.

Identity Provider EntityID

No

Federation discovery services (WAYF) can be bypassed by providing a value for this setting. If the WebStore is specific to a single IdP, then this value should be considered as required. The value should be exactly as it is found in metadata. For example: urn:mace:incommon:myorg.edu or https://shibboleth.myorg.edu

IUV Administrator Email Address

No

Email address of individual (or distribution list) who will receive error messages from ELMS.

Hide Username

No

When checked, this setting prevents a user's unique identifier from being shown in several places in the WebStore user
Page 14

Shibboleth User Verification: Customer Implementation Guide v2.1

e-academy CONFIDENTIAL

Information

Required?

Description interface. This is useful when a screen-friendly username is not provided (e.g. a GUID) as part of the set of released attributes from the IdP.

Logout Redirect URL

No

The URL where a user will be redirected to when they sign out from the WebStore and the Shibboleth Service Provider. If left empty, on signing out the user will remain on the WebStore and will be shown a message similar to the following: You have been signed out of this website, but remain signed in to your Single Sign On system. If you want to log out completely, you MUST close your browser.

Restrict Eligibility Scope

No

If your WebStore is for one or more departments, this value should be checked to ensure that other users are not granted eligibility. If checked, eligibility attributes (e.g. eduPersonScopedAffiliation) will only be processed for users with accompanying attributes containing organization mapping information (ou, eduPersonOrgUnitDN, isMemberOf, eduPersonEntitlement). If unchecked, eligibility attributes will be processed for all users. If accompanying organization mapping attributes are present, users will be given member ship in the corresponding organizations. Otherwise, users will be given membership in the WebStore organization. This data can be seen, post-login, by examining the corresponding user verification records (Users > User Verifications).

TESTING YOUR INTEGRATION

Once your integration is complete, you need to test it! This section covers the following areas:

Testing Your Integration o Test using e5Demo Entity ID o Test using e5 Production Entity ID Testing the Workflow Validation

Page 15 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

TESTING YOUR INTEGRATION

One of the steps to set up your integration was to release your attributes to the e-academy Entity IDs. The two sections below provide information on testing against each of the Entity IDs.

TEST USING E5DEMO ENTITY ID

Use the e5Demo Entitiy ID https://e5demo.onthehub.com/admin if: You currently have an ELMS WebStore in production and are changing the existing verification method. Use the e5demo system to ensure the correctness of the implementation before performing the change in production. You are the first member of your federation to integrate with e-academy. You are not a member of a federation and will be performing a custom implementation.

If you need to test with the e5Demo Entity ID, contact e-academy (See the Support section below) to arrange the testing. This will require the creation of a demo WebStore. Upon completion, you must then set up your configuration in the ELMS production system on your ELMS production WebStore.

TEST USING E5 PRODUCTION ENTITY ID

Use the e5 production Entity ID if your implementation does not meet any of the criteria defined in Test using e5Demo Entity ID above. This will eliminate duplicate setup work and can be done without any contact with the e-academy Support team.

TESTING THE WORKFLOW

Below are the common steps required for testing your implementation, regardless of the target integration (testing or production): 1. 2. 3. Configure your IdP. Configure your ELMS WebStore. Trigger the authentication process from your ELMS WebStore. If you are already signed in to the administration site, you will have to sign out first or use a different browser. If the Shibboleth verification type is in Testing status, you will have to use the testing URL found in WebStore Verification that enables test verification methods when accessing your WebStore. Authenticate with your IdP and ensure that you are then successfully signed in to your ELMS WebStore. Validate the data created for the user in your ELMS WebStore as described in the next section. When everything works as expected, contact e-academy to proceed.

4. 5. 6.

Page 16 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL

VALIDATION
After successful authentication, it is helpful to view a users profile to ensure that all expected eligibility groups and personalization information has been set correctly. From the ELMS WebStore: 1. 2. 3. Click the Your Account link above the page banner. Click the Account Details link. Any personalization information that was passed is displayed. Return to the Your Accountpage and click the Your Eligibility link to view the eligibility groups that your account has been assigned to (for example, students, faculty, staff, etc).

From the ELMS Administration site: 1. 2. 3. On the Main menu, go to Users. Search for the desired user and click the Username to navigate to the details page. Any personalization information passed is displayed. Click the Verifications tab. For each successful authentication there will be an entry that contains the expected list of eligibility groups (students, faculty, staff, etc.)

SUPPORT
If you have any difficulties with configuring Shibboleth for ELMS or require technical assistance, send an email to one of the following addresses: Federation InCommon SWITCHaai Canadian Access Federation WAYF Denmark Other/General Include the following in your email: Customer Name Contact Name Contact Email Contact Phone ELMS Account Number Detailed description of the problem or request for information Email Address

InCommon@e-academy.com SWITCHaai@e-academy.com CAF@e-academy.com WAYFDK@e-academy.com shibboleth@e-academy.com

Page 17 Shibboleth User Verification: Customer Implementation Guide v2.1 e-academy CONFIDENTIAL