- SSO Basic Settings
- SAML Settings
- CAS Settings
- JWT Settings
- OAuth Settings
- Mapping Your Attributes
- Testing Your SSO Configuration
- Branding the SSO Button (optional)
- Embedding into External Website
- Frequently Asked Questions
This article describes the process of setting up single sign-on (SSO) on your PeopleGrove site. This allows your end-users to log in to your site using their school account login credentials and will pull any data associated with that account on your end into the system during sign up.
Before getting started you will need:
- A site-wide admin account with access to the Single Sign-On (SSO) module via the Technical Setup
- Your organization's metadata
- Configured attributes or claim rules for user email, first name, last name, and database key
Note: A copy of our metadata is available at metadata.peoplegrove.com.
Lost? Site-Wide Admin → Technical Setup → Single Sign On (SSO)
The Single Sign On (SSO) page contains all settings related to SSO; There are no settings that only PeopleGrove can edit.
First, we'll need to set some basic SSO settings.
Toggle Enable Single Sign On? on once you're ready to launch SSO on your site. You can complete SSO setup before enabling.
Set your SSO Type to:
Set your SSO Logout Url. This is the URL your users will be redirected to after logging out.
SAML stands for Security Assertion Markup Language. It is an out-of-the-box, industry standard for SSO, and it's the easiest and most secure way to set up SSO on your PeopleGrove site. This is our preferred method for implementing SSO.
If you're setting up your SSO via SAML, you'll need to complete the following fields:
The Entity ID is in the first line of your metadata, as shown in the image below:
SAML Redirect is the SAML HTTP Redirect URL. In the metadata, it is often referred to as 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect' and normally ends in '/SAML2/Redirect/SSO'. In the example below, the SAML redirect is the URL on the highlighted "Location" line. Only include the URL starting with 'https://...' and do not include quotes or any other characters:
In this example, we would enter the following into the SAML Redirect field:
Your SAML Certificate is the signing certificate from the SAML metadata. There may be multiple certificates in your metadata file, so search for "signing" in the metadata to find the correct section. Once you've found it, copy-and-paste the entire string. Whitespace will not matter. If the certificate you have is in a file, simply open the file with a text editor.
The ADFS toggle is an optional setting. Only enable this setting if you are using Active Directory Federation Services with SAML. Note: ADFS may be included in the entity ID.
Disable AuthnContext toggle is also an optional setting. We normally recommend keeping this setting disabled, but if you experience any issues with your login page, try enabling this setting to disable the AuthnContext being passed from the PeopleGrove request.
Leave the Advanced: Accepted Clock Skew (Ms) field blank. If your SSO is set up correctly but your end users are encountering errors, our support team may use this field to resolve the issue.Now that your SAML settings are set, jump down to the Mapping Your Attributes section of this support article by clicking here.
CAS stands for Central Authentication Service. It is similar to SAML but is an older standard. Otherwise, there isn't much difference between SAML and CAS.
If you're setting up your SSO via CAS, you'll need to complete the following fields:
- CAS Server Address
- Version Of CAS
- All CAS requests will be redirected to
Enter the base URL of your CAS server into the CAS Server Address field. Do not include /login in the URL. An example of this is https://login.test.edu/cas.
Next, set the version of CAS you're using in the Version of CAS dropdown menu. We support CAS 1.0, CAS 2.0, and CAS 3.0. If you're unsure of which version you're using, you're most likely using CAS 2.0.
Now that your CAS settings are set, jump down to the Mapping Your Attributes section of this support article by clicking here.
If you're setting up your SSO via JWT, you'll need to complete the following fields:
- Login URL
- JWT Secret
- URL where all requests are redirected (though not specifically a field)
The Login URL should be the URL of the SSO login page. If an end-user clicks the SSO button from your PeopleGrove site's landing page, they'll be brought to the URL entered here.
Once you've set your SSO type settings and generated your attributes, you'll need to map them to their corresponding PeopleGrove fields. We support mapping to the following fields:
- SSO ID
- Database Key
- First Name
- Last Name
- Custom Fields
- Education Records
You'll want to create attributes for the first five fields. While it's possible to pull additional data via SSO, the final three fields are optional.
When a user logs in via SSO, the system will check your PeopleGrove site for an associated user account. The system checks for accounts with a matching SSO ID, then Database Key, then Email, so make sure to create attributes for each of those.
Note: While we highly recommend creating unique attributes for each of these fields, it is possible to assign the same attribute to multiple fields. If, for example, your organization does not have a dedicated ID to use for SSO ID, you can set users' database keys as their SSO IDs.
Be aware that all users must have a value set for SSO ID. If you do not map any attributes to this field, it will prevent your users from logging in.
In order for a new user account to be created, the system requires a first name, last name, and email address. This is the minimum amount of information required to create a new account, so make sure to include attributes for these fields in your metadata if you expect any users who have not been imported to sign up via SSO.
Keep in mind that you must create separate attributes for First Name and Last Name. If you create one attribute that pulls the user's full name and add it to both fields, the user's full name will appear twice on their profile (e.g. "John Smith John Smith").
Once you have entered values for the required fields, click the Save button, then continue on to testing the SSO configuration. If you would like to map attributes to the optional fields, though, proceed to the next section.
Affiliations allows you to prevent your users from signing up as the wrong user type.
You'll need to create an attribute that pulls what the user's user type should be (for example, student, alumni, etc.) and map it to the Affiliations field. Then, you'll need to reach out to our support team (by clicking the green question mark in the bottom right-hand corner of the SSO page on your PeopleGrove site) and let us know which affiliations you've set up. Our team will map those to the correct user types.
Once that's set, a user can select any user type they want during sign up, but if they select a user type other than the user type you've assigned to them (in the SSO), they will be placed in the approval queue and will require admin approval before accessing the site.
Please keep in mind that this does not assign user types.
If you wish to pull user data from your end to answer any Custom Fields, enter the attribute in the field on the left, and select the corresponding custom field question from the drop-down menu on the right.
If you would like to map Education Records via SSO, toggle Enabled Education Mapping on. This will bring up some new fields:
Once you have entered values for each field, click the Save button, and continue on to testing the SSO configuration.
Once you have completed setting up your SSO instance, we highly recommend testing your configuration. To do so:
- Toggle Enable Single Sign-On? on, if you haven't already, and click Save
- Open an incognito or private browser window, visit your site's landing page, and log in via the SSO option
- Once you have attempted to log in via SSO, return to the Single Sign-On (SSO) module
- Scroll down to Test Configuration, and click on View Mappings
This will show you all of the attributes which were pulled for this user (SSO Attribute), the data that was pulled for each attribute (Sample Data), and the PeopleGrove field that data was mapped to (Mapped PG Field). All rows shown in green have been successfully mapped. Grey rows have not been mapped. As you can see in the example above, it is possible to map a single attribute to multiple fields.
If any data is not being mapped correctly, check here to confirm that the correct attribute and associated data is mapped to the correct field.
If you scroll down, you'll see the full, raw SSO response:
If any data is missing for a user who signed up via SSO, check here to confirm whether or not that data was included in the SSO call.
Congratulations! SSO setup is complete. You're now ready to launch with single sign-on as a sign up/login option.
By default, the SSO button will be blue and say SSO. If you would like to customize this, you can adjust the branding of your SSO button from the SSO Branding Settings section of the Single Sign On (SSO) module.
To customize the text on the SSO button, enter the text you would like to display on the button in the Button Text field.
To customize the button background color or button text color, click the checkered square in the Button Background Color or Button Text Color field, and select you colors. Alternatively, you can enter a valid hex code.
Embedding into External Website
You can embed your PeopleGrove login with SSO to an external website.
The process is simple.
- Start with your PeopleGrove URL
- add the following to the end of your URL: /api/auth/sso/
- after the final forward slash add the method of SSO you use (ex. saml, cas, jwt, oauth)
You can now use this link to embed in your external sites.
Can I use X service to set up my SSO integration?
As long as the system you use supports SAML, CAS, JWT, or OAuth you should have no trouble integrating with your PeopleGrove site.
When I attempt to log in via SSO, I encounter this error message: "missing saml id". What does that mean?
This error message indicates that the user logging in does not have any data pulling for the SSO ID field. This typically means that no attributes were mapped to this field. Please make sure to map an attribute to the SSO ID field to avoid this error.
I have everything set up correctly, but I don't see any attributes when testing the SSO.
Depending on your institution, there may be additional attribute release requests that must be submitted before your institution will trust PeopleGrove. Often with InCommon, we get a few attributes back by default, but for sensitive data such as ID number, we may need to be authorized.
When I click the SSO button, I'm not brought to the SSO login page.
If clicking the SSO button does not bring you to your SSO login page, there may be an error in your metadata inputs. Try updating the settings and re-copy and paste from your metadata.
If using JWT, check the URL entered into the Login URL field as well.
I'm being asked to confirm my name and email even when I create an account with SSO. Is that right?
Yes, by default, we still ask users to confirm their name and email when signing up. This is often beneficial because users can use their preferred or personal email. Users can also sign up using a preferred name or a maiden name, if desired.
Can I set up SSO after I launch my site?
While we recommend setting up SSO before launching, it is possible to set up afterwards.
If I set up and enabled SSO after launch and some users have already signed up via the Email option, how do the users who already signed up continue to sign in if it's required for their user type?
The SSO requirement is only enforced during sign up, so these users may continue to log in via whatever method they originally signed up with. If they would like to log in via SSO, they can link their PeopleGrove account with their SSO account from the My Profile page at any time.
If I set up and enabled SSO after launch and a user who previously signed up via another sign up option logs in using SSO, will this create a duplicate account for the user?
Any time a user logs in via SSO, the system will run a check to determine if that user already has an account on your site. The system checks the data pulled for SSO ID, Database Key, then Email (in that order) and compares it to the data you have for all users. If it finds a match in any field, the user will be logged in to the matching PeopleGrove account. If not, the system will prompt the user to create a new account.