Single Sign-On - SAML 2.0

Requirements

The Google Identity Platform supports Service Provider Initiated Single Sign-On (SSO) for the Web Browser profile at this time. It does not support Identity Provider initiated SSO.
The student must exist in Regent via the Student Batch Load process for Single Sign-On to be successful.
1. For optimal user experience, it is recommended that customers only present Student Experience links to students who exist in Regent.
The customer must provide the student's ExternalId1 or ExternalId2, which are sent in the Student Batch Load file, as an attribute in the SAML Assertion. The ExternalId1 or ExternalId2 provided must be unique in the Regent system. If two students have the same ExternalId2, and that is sent in the SAML Assertion, Single Sign-On will fail.
The customer must sign SAML Assertions.
The customer is responsible for providing updated public signing certificates in case of expiration or rollovers. These should be submitted via Customer Zone well before any certificate expiration/rollover occurs.

Self Service

Regent Award contains several self-service features related to Single Sign-On. These settings can be managed in Institution setup in Regent Award, in the Portal, Account Mgt sub-tabs. This includes:

Login Method Selection - whether Student Experience will use Single Sign-On or Password authentication for students.
ExternalId1 or ExternalId2 validation.
The name of the attribute containing the students ExternalId1/ExternalId2 which the customer will send in the SAML assertion (see #2 under 'Common Questions' below if the attribute name is not configured).
Logout Redirect - The URL the student should be redirected to after clicking the logout link in Student Experience (see #1 under 'Common Questions' below if URL is not set).
1. IMPORTANT - Given that the Google Identity Platform does not support Single Logout (see below), this should be configured to a page where the student can clearly see if they are still logged into the customers system and can log out from customer system as well.

Google Identity Platform Feature Limitations

The Google Identity Platform does NOT support the following SAML 2.0 features at this time:

Assertion encryption
Identity Provider Initiated SSO
Authentication request signing
Single Logout
Automatic metadata monitoring/configuration updates

Initial Configuration and Setup

Configuration and testing will first be performed in a customer QA Student Experience instance. After QA is confirmed then production configuration will occur.

Step 1 - Regent supplies the following SAML Service Provider related information:

Entity Id of the Regent SAML Endpoint
Assertion Consumer Service URL

Step 2 - The customer configures SSO using Regent supplied information from Step 1. The customer ensures the students External Id1 or External Id2 will be sent as a named attribute/claim in the SAML assertion (See Requirements / Step 4 for more info). Also, the customer should send the students email address as the "username" (NameID SAML attribute). Customer supplies the following SAML Identity Provider related information to Regent. Alternatively the identity provider metadata may be supplied.

Entity Id of the Customer SAML Endpoint
SSO URL
Public Certificates used for Assertion Signing
1. The public certificate(s) should be supplied in PEM format (base64 encoded text).
  1. For example:
    -----BEGIN CERTIFICATE-----
    MIIDATCCAemgAwIBAgIQdPDr/iI1jbhDMTj5VYya+TANBgkqhkiG9w0BAQsFADAW
    MRQwEgYDVQQDEwt3d3cuaWRwLmNvbTAeFw0xMzExMjIwODIwNTJaFw00OTEyMzEx
    NDAwMDBaMBYxFDASBgNVBAMTC3d3dy5pZHAuY29tMIIBIjANBgkqhkiG9w0BAQEF
    AAOCAQ8AMIIBCgKCAQEAi0XJRLDrcbSyqUd8XG4BgxObQMYLAkENlmJOsAEpl1xM
    abUiq1X4v0Fc8ZaCpUE3fFGENMEWgBjnQUUE0WtVUh5JPMsukolf9qljbJkCkvHX
    H3O4Uen7vA2oNQWt4bK96SpXADpZKFvpk4D7btKOgU/NamjiqwHI4fI8kFJKwKBJ
    chRPUQdC4ljRRmGIrSnpY+t25/d3KGXwbe9Z2MGGy2hyA0tgOWuchIK+1vAKKBUh
    9nDEXfr80+xW680w5TqHyDcqbWvQsXXhH0yZLfINKNS6/IojHPsBy7tf36Ck9H5P
    w+1PPu6NzBFSz5ZkC8KzrS6vuZXc/ImYrnheMQsqqQIDAQABo0swSTBHBgNVHQEE
    QDA+gBD4dY4MCPEmG4sxZrcni8vtoRgwFjEUMBIGA1UEAxMLd3d3LmlkcC5jb22C
    EHTw6/4iNY24QzE4+VWMmvkwDQYJKoZIhvcNAQELBQADggEBABhak2aR84MCdyXO
    4AKOQvZybsCMdhRq2i1i0WhD4/xe7Ry5haC6TeXIp8Q4cC3MzsrDal74xHI714BW
    0loafpHAsXfd9EvkKTVaJ+1Zpe16+SsTL4upS1cGydigqwUzsdpGck4wI1moJ947
    7O+46If2gF27u9Cdk7Onxe/5dwLIxWmkVRdbQIH5GsKUeAjOdRQmy+X1MX6KyRoa
    CwWGYwxi5Sa+r+3AtDvD4BX0EJGKFZeeM3J/yMpYh/75aN0cFQfDEdJ7C5NE0von
    idE0QtIFvsoWtZUtur2fiW7yBxse38TPQsi2r6A6c/TZsZ5bq31yh3gr3kSN62H8
    iVKLQLA=
    -----END CERTIFICATE-----

Step 3 - Regent processes the SAML information from Step 2 and completes SSO configuration on Regent side.

Step 4 - Customer configures SAML in their Identity Provider and in Regent Award under the Portal, Account Mgt sub-tabs.

The customer can complete this step immediately after Step 2 is completed. However, SSO will not work until Regent completes Step 3.

This MUST include sending the student's ExternalId1 or ExternalId2 as detailed above, ensuring the attribute name exactly matches the Single Sign-On configuration in Regent Award.
The customer should also send the students email in the normal "username" ("NameId" portion) of the SAML assertion.
Regent Award Portal, Account Mgt sub-tabs:
1. Login Method Selection
2. Set ExternalId1 or ExternalId2 (not both).
  1. Please note there is a 500 character limit on this value.
3. Configure the name of the attribute which the customer will send in the SAML assertion
4. Logout Redirect URL - This should be configured to a URL where the user can clearly see if they are logged into the customers portal and can easily choose to log out of the customer system as well in case they are on a public or shared computer.

Step 5 - Validate Single Sign-On is successful for a student that exists in Regent's system.

Please note that Google Identity Platform does NOT support Identity Provider Initiated SSO at this time, it only supports Service Provider initiated SSO. Therefore you should ensure you are testing SSO by navigating to the Student Experience web site.

Common Questions and Troubleshooting:

#	Question	Answer
1	What happens if the Logout Redirect configuration is not set?	If the Logout Redirect configuration is not set and the user clicks logout, StudentX will redirect the user to the root directory of the site, which will trigger Single Sign-On. If the user is still authenticated with the Identity Provider, then the user will be logged back into StudentX again. RS-17967 - Getting issue details... STATUS is an upcoming scheduled enhancement ticket that will present a basic logout page that will indicate that the session has expired if the Logout Redirect configuration is not set.
2	What happens if a user does not configure External ID1 or External ID 2 Attribute Name fields?	The attribute name must match what is sent from the customer in the SSO configuration. If the attribute name is not set to the correct value, SSO will fail. Note: Either External ID 1 or External ID 2 can be chosen, but not both.
3	Why am I seeing an "Invalid response: has no assertions" error?	This commonly occurs when the customer has configured the Identity Provider to encrypt assertions. Do not encrypt assertions.
4	Why am I seeing an "Error when parsing certificate: Could not parse certificate: java.io.IOException: Incomplete data" error?	This will occur if the customer's signing certificate configured in Google Identity Platform does not have the appropriate line breaks as is present in the public certificate PEM format example above. This may happen if the certificate provided to Regent was missing these line breaks and Regent staff did not identify the missing line breaks. Please contact Regent if this error is occurring and reference this condition.
5	Why am I seeing an error notification in the top right corner of the screen similar to: "Unable to login. Please contact the [Office Name] at [Office Phone] or [Office Email]."?	This may occur under one of the following conditions: Most likely scenario → Regent does not contain a unique student record with a matching External ID - ID 1 or 2 as per published configuration as documented in Step 4 of Initial Configuration and Setup. This may be due to an incorrect value being provided in the external id attribute. The External ID attribute in the assertion attribute does not contain a value. Solution: Enable SSO logging in your system, or use tools/processes, to determine of the exact claims and values within the SAML Assertion, which should allow you to identify the value being sent and determine root cause (value is correct but no matching student, value is incorrect, value has unexpected formatting or other data appended, etc).
6	Why am I seeing either: A. A blank screen after authenticating with the Identity Provider, where the browser has a URL in the address bar like "https://xxxxxxxx.firebaseapp.com/__/auth/handler"? B. OR the following message "Unable to process request due to missing initial state. This may happen if browser sessionStorage is inaccessible or accidentally cleared"	This may occur under one of the following conditions Customer is attempting SSO via Identity Provider initiated SSO which is not supported. SSO must be initiated from the browser loading the Student Experience web site.
7	Why am I seeing an "Unable to login. Missing expected attribute XXXX' Please contact the Financial Aid Office at..." error?	The customer SSO configuration is not sending the expected attribute name containing the students ExternalId1 or ExternalId2. The attribute may be missing, or the name may not match what is configured in REM. Please note that it is possible the customer system may be sending a fully qualified name such as "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/id", instead of just "id". Also note that there is a 500 character limitation on the ExternalId1 and ExternalId2 attribute name fields.
8	Why am I seeing an "The SAMLResponse does not match Rp Entity id in storage" error?	There is a mismatch in the Entity Id's defined in the customer system and Regent system. Typically these are in the format of a URL and there could be a minor difference such as a trailing slash, http vs https, etc. (Note: Regent will automatically trim leading/trailing spaces in the name of the externalId attribute to compare to attribute name received in SSO. The comparison check is not case sensitive.) Regent / customer technical staff should review and resolve the config issue in coordination as appropriate.

Customer Zone Knowledge Base