Configuring an SSO Integration

Getting started

SSO integration is only available with an Institutional license. If you have any questions about acquiring a license for your institution, fill out our demo request form.

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.

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.

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:
1. SSO Login URL - Users will be redirected to this URL when logging in to Gradescope via SSO.
2. 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 help@gradescope.com for assistance.
3. 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.

Need a copy of your full certificate? To view your certificate, select the one line preview. The full certificate will be revealed which will allow you to copy and paste when needed.

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.
1. Enter either Full Name or First Name and Last Name
2. Email Address
3. Unique Identifier - this should be a value that will remain unchanged for a user.
4. (Optional) Affiliations - used to identify users who should be provisioned with an instructor account, alongside the information provided in the Instructor Affiliations field.
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.

Some common SAML attributes include:

Attribute	Friendly Name	Shibboleth	Azure
Full Name	fullName, cn	urn:oid:2.5.4.3
First Name	givenName	urn:oid:2.5.4.42	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last Name	surname, sn	urn:oid:2.5.4.4	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Email	emailaddress, mail	urn:oid:0.9.2342.19200300.100.1.3	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Unique Identifier	eduPersonPrincipalName	urn:oid:1.3.6.1.4.1.5923.1.1.1.6	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Affiliations	eduPersonScopedAffiliation, eduPersonAffiliationisMemberOf	urn:oid:1.3.6.1.4.1.5923.1.1.1.9 urn:oid:1.3.6.1.4.1.5923.1.1.1.1 urn:oid:1.3.6.1.4.1.5923.1.5.1.1	http://schemas.microsoft.com/ws/2008/06/identity/claims/groups http://schemas.microsoft.com/ws/2008/06/identity/claims/role http://schemas.xmlsoap.org/ws/2005/05/identity/claims/affiliation

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.
1. 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.
2. To add additional domains that are used by your institution, contact help@gradescope.com.

Autolink Email Domain field is empty? Contact help@gradescope.com to add a domain, or individual users can link their accounts manually on their account settings page.

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 received a student account? Ask a colleague to enroll you as an instructor or TA in a course, then you can create courses of your own. Or contact help@gradescope.com to upgrade your account.

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.

Instructor-specific domain examples: @faculty.exampleuni.edu, @staff.exampleuni.com. This field is case sensitive so avoid using capital letters when listing your domains.

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.

Need specific data from your SP Metadata for your IdP? Contact help@gradescope.com.

You are now ready to test your configuration.

Your SSO integration has been fully configured but it has not yet been publicly deployed. We recommend testing your configuration before deployment.

Testing

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.

Testing new users? We recommend testing with student and instructor user types to ensure they are both provisioned with the appropriate account level.

If your tests have been successful, turn off Test Mode by unchecking the box.

Leaving Test Mode turned on after deployment will surface any debugging error messages to all users, including students.

Select Save.
You are now ready to deploy your SSO integration.

Testing unsuccessful? If your testing is unsuccessful, and you have followed all of the configuration and testing steps, contact help@gradescope.com for further assistance.

Deploying your SSO integration

After successful testing, turn off Test Mode at the top of the page by unchecking the box.

Leaving Test Mode turned on after deployment will surface any debugging error messages to all users, including students.

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.

Making changes to your integration? We recommend unchecking the Enabled setting to temporarily remove your institution’s SSO integration from Gradescope’s SSO login page, especially if Test Mode will be utilized once the changes are complete. You can activate the Enabled setting again once your changes have been made and Test Mode is turned off.

Configuring an SSO Integration