Configuring an SSO Integration
Before you can begin configuring your Single Sign-On integration, please contact your Account Manager so that we can enable the permissions to your account. Once you have received confirmation that your Gradescope account has been updated, you can continue to the first step.
Gradescope’s SSO configuration is known to support Shibboleth and Azure integrations. While it is designed to support as many SAML2 providers as possible, if you encounter any issues during your configuration, send us an email for assistance.
Configuring your SSO integration
Once you have had the SSO permissions added to your account:
- Log in to your Gradescope account.
- Select SSO Integrations from the left navigation menu.
- Ignore the Enabled and Test Mode settings for now.
- Enter a display name for your institution’s SSO integration. Students and instructors will search for this on Gradescope’s SSO login page, so it should be something that they will recognize as your institution.
- Enter the Metadata URL provided from your IdP into the IdP Metadata URL field and select Import Metadata. Importing the IdP Metadata should automatically populate the following fields:
- SSO Login URL - Users will be redirected to this URL when logging in to Gradescope via SSO.
- Logout Redirect URL - (Optional) Users will be redirected to this URL when they log out of Gradescope. If left empty, users will remain logged in to your institution’s SSO. If this field is required for your institution but remains empty after importing the metadata, enter the URL if you know it or email firstname.lastname@example.org for assistance.
- Certificates - You must have a valid signing certificate when configuring your SSO. To update your certificate, repeat this step and reimport your IdP Metadata URL. Any encryption certificates found in your Metadata URL will also be listed here.
- There are certain SAML attributes that Gradescope requires for a successful configuration:Note that Gradescope always expects
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>to be in the SAML response.
The user attribute table is prefilled with common Shibboleth attributes. Review each field to ensure that they are relevant to your Identity Provider and edit where necessary.
- Enter either Full Name or First Name and Last Name
- Email Address
- Unique Identifier - this should be a value that will remain unchanged for a user.
- (Optional) Affiliations - used to identify users who should be provisioned with an instructor account, alongside the information provided in the Instructor Affiliations field.
Some common SAML attributes include:
- The Autolink Email Domain field is read-only and automatically populated for you. Existing Gradescope accounts with the listed domain(s) will be automatically linked to your institution’s SSO instance when they first log in via SSO.
- This does not include new Gradescope accounts that are created when logging in through your institution’s SSO. These accounts are automatically linked to your SSO during creation, regardless of their email domain.
- To add additional domains that are used by your institution, contact email@example.com.
- The Instructor Affiliations field is automatically populated for you using Shibboleth’s eduPersonScopedAffiliation attribute. You can edit the provided affiliations if they are not applicable for your IdP or your institution. Users with your determined affiliations will receive instructor level Gradescope accounts, and will be able to create courses, enroll students, etc. You can add affiliations associated with instructors in your institution and separate the values with a comma.
- Instructor-Specific Domains is an optional field and should only be used in the absence of an affiliations attribute. To identify instructor-specific accounts, enter all email domains used exclusively by instructors at your institution and separate them with a comma.
- Select Save from the bottom-right corner of the page.
- An SP Metadata URL (service provider) will populate at the top of your page if your deployment was successful. Provide this URL to your IdP to complete your configuration.
- You are now ready to test your configuration.
We recommend testing your SSO configuration before publicly deploying it to your users.
You will want to ensure that:
- Users with existing Gradescope accounts are able to log in using your institution’s SSO
- Users who do not yet have a Gradescope account are automatically provisioned with one when they log in using your institution’s SSO
- Users are provisioned with the appropriate accounts.
- Ensure every field marked with an asterisk * is filled in.
- Ensure that you have provided your Identity Provider with the SP Metadata URL which appears at the top of the page after you have saved your integration.
- Scroll to the top of the page and select the Test Mode check box. This will surface any debugging error messages while you are testing.
- Select Save to fully enable Test Mode, and then Test from the bottom-right corner of the page when you are ready to begin testing.
- You will be directed to your institution’s login portal. You should be able to log in using your credentials.
- To test a user with an existing Gradescope account, or a user that does not already have an account, right click on the Test button and select the option to copy the link. This URL can be shared with other users to assist with your testing.
- If your tests have been successful, turn off Test Mode by unchecking the box.
- Select Save.
- You are now ready to deploy your SSO integration.
Deploying your SSO integration
- After successful testing, turn off Test Mode at the top of the page by unchecking the box.
- Select the Enabled check box. This will deploy your SSO integration to Gradescope’s SSO login page and allow it to be publicly viewed by instructors and students.
- Select Save from the bottom-right corner of the page.
- You’re done! Your SSO integration is now fully configured and available to be used.
Editing your SSO integration
When making any edits or changes to your SSO integration, don’t forget to select Save and do any necessary testing.
Any changes made to your SSO integration will be recorded within Recent Changes, and will list the user who made them.
A Notes field is available at the bottom of the page. Add any notes here for future reference. Notes will not affect your configuration but may help with troubleshooting.