Vocabulary.com offers single sign-on authentication via SAML 2.0 to school districts as a means of simplifying user sign-up. This authentication method enables your students, teachers and administrators to use their familiar secure login on your school/district website to gain seamless access to Vocabulary.com without having to create another username or password. SSO also allows you to provide user details to us for pre-population in each user's Vocabulary.com profile.
Advantages
- Students can use their existing username and password to access Vocabulary.com. If you are using Single Sign On for other resources, and your students and teachers know how to use the SSO portal, they don't have to learn a new username and password to access Vocabulary.com.
Disadvantages
- Longer Implementation Time. We must work with your IT department, and there is a certification process before Vocabulary.com can enable SSO for your account.
- Requires District IT Resources. You must provide access to an administrator at the district level that is familiar with SAML 2.0 and has the necessary permissions to add a SAML service provider to your system.
Requirements
- Technical Point of Contact. Provide name and contact of technical resource to help with set-up and administration.
- Certification Process. Before we can enable SSO via SAML, you must provide Vocabulary.com with a test student and a test teacher account. Once you have completed the certification process, we can enable your account for SAML SSO.
- Access to Vocabulary.com must be restricted to the licensed users of your Vocabulary.com subscription. If other schools have access to your SSO system that are not part of your license agreement with Vocabulary.com, you must take steps to ensure that they may not log on to Vocabulary.com through your SSO server.
- A SAML 2.0 identity provider that is accessible from both inside and outside your network. Examples of these include Active Directory Federated Services and Shibboleth.
- Your Identity Provider must be configured to pass the following fields to us:
|
Students
|
Teachers and Administrators
|
Getting Started with SAML SSO
Go to https://www.vocabulary.com/account/authentication and click the Request SAML Integration button. Fill out the form with the required information and a technical support agent from Vocabulary.com will get back to you to begin the SAML 2.0 setup process.
Logging in with SAML SSO
After the initial setup, it’s easy for your users to log in to Vocabulary.com with their web browser. Typically, your school or district will place an icon on your website (intranet, extranet or portal) that links to a special SSO login URL on Vocabulary.com.
When a student or educator clicks the icon:
- If they are not logged in, they are redirected to your secure login page hosted on your server.
- If the user has already logged in to your system, they are redirected to Vocabulary.com
- If it’s their first time visiting Vocabulary.com, a profile is created for them and they are shown a welcome screen
- If they’ve already visited Vocabulary.com, their profile is loaded and they are redirected to the Vocabulary.com home page
How To Configure SAML Authentication to Vocabulary.com
Terminology
Identity Provider (IDP): Your school’s SAML authentication server
Service Provider (SP): Vocabulary.com
Step 1: Metadata Exchange
IDP Metadata
You need to provide your SAML IDP metadata, either via URL or emailed to us as an attachment.
If you can provide a metadata URL, we will regularly check for updates to your certificates and authentication URL and automatically re-import the data into our system.
If you provide the metadata via email, you will need to send us updated metadata every time you update your SAML certificates or authentication URL.
SP Metadata
After we have imported your metadata, we will provide you with our SP metadata. You will be given a Vocabulary.com URL specific to your school from which you can download our metadata.
Step 2: Attribute Mapping
Your SAML server (IDP) allows you to configure what user details you share with Vocabulary.com when authenticating with us. This process is called attribute mapping. We will provide an attribute mapping form which must be completed. On the attribute mapping form you can specify which attributes you can provide and their custom names if needed.
There are certain attributes which are required to create a profile on Vocabulary.com. Some attributes are not strictly required but highly recommended. The more attributes you can map, the fewer fields the user will be asked to complete at a later point, and the more features will be enabled immediately on Vocabulary.com.
In addition to the many default attribute names that are listed below, we can also map any custom attribute name you provide on the attribute mapping form.
Attribute: User ID (Required)
This is a unique identifier we will associate with your user and it should always match their unique identifier used in your system.
Default Names: “uid”, “urn:oid:0.9.2342.19200300.100.1.1”, “mail”, “urn:oid:0.9.2342.19200300.100.1.3”
Attribute: First Name (Required)
Names are required because teachers need to be able to identify which students are in their Vocabulary.com classes.
Default Names: “givenname”, “urn:oid:2.5.4.42”
Attribute: Last Name (Required)
Names are required because teachers need to be able to identify which students are in their Vocabulary.com classes. Last names are not shared with anyone outside of your organization.
Default Names: “sn”, “urn:oid:2.5.4.4”
Attribute: Email Address (Required for Teachers / Highly Recommended for Students)
Providing an email address is highly recommended, especially for teachers. If your users already have a login on Vocabulary.com with the same email address, their SSO created account will be linked to their pre-existing account. Linked accounts retain all play history, wordlists and other user-generated content created previous to SAML authentication. Profiles created via SAML authentication without email addresses are treated as new Vocabulary.com users.
Default Names: “mail”, “urn:oid:0.9.2342.19200300.100.1.3”
Attribute: Role (Highly Recommended)
If you provide a role attribute, we can seamlessly promote your teachers to the Vocabulary.com teacher role. If a role is not provided, all profiles are initially created at the student level and teachers will need to be invited by administrators to elevate their permissions. The default values listed below also accept your custom values for their role. Specify any custom attribute name or values for a role on the attribute mapping form.
Default Names: “edupersonaffiliation”, “urn:oid:1.3.6.1.4.1.5923.1.1.1.1”
Default Values: “staff”, “faculty”, “employee”
Attribute: NCES or MDR School ID (Highly Recommended)
Providing your MDR or NCES School ID means your users will not have to pick their school from a menu on Vocabulary.com. Students will be assigned consistently to their school. When a student is correctly assigned to their school, the school will get credit for points added towards the Vocabulary.com Bowl and leaderboards.
Default Name: ncesschoolid, mdrschoolid
Attribute Name: Graduation Date (Optional)
Providing the graduation date for students helps teachers sort through the list of authenticated students in My Account. Users who have graduated will be filtered from the list.
Default Name: graduationdate
Format: yyyy-mm-dd (4 digit year-2 digit month-2 digit date)
Step 3: Testing & Certification
Before publishing the link to authenticate to Vocabulary.com to your users, we require a brief testing phase. We can enable your authentication immediately following testing. In order to test we require either of the following:
A technical contact at the school who we can work with to confirm attributes are mapped correctly. They should be familiar with your single sign-on system and should have the appropriate permissions to add service provider metadata and provide test accounts.
Test logins/passwords on your SAML server (IDP)
test student account
test teacher account