Eduphoria supports Secure Assertion Markup Language (SAML), which lets you provide single sign-on (SSO) access to Eduphoria staff and student accounts. With SSO, users can sign in once using their company sign-in form to gain access to multiple systems and service providers, including Eduphoria products.
You can enable SAML single sign-on for staff members only as well as for staff and students, but not for students alone. Staff members include teachers, principals, and administrators.
As an Eduphoria System Administrator, your role consists of enabling the SAML SSO options. See the following topics:
- How SAML SSO for Eduphoria Works
- Requirements for Enabling SAML SSO
- Enabling SAML SSO
- Managing Users in Eduphoria after Enabling SAML SSO
- Switching Authentication Methods
The district’s IT team is usually responsible for setting up and managing the company's SAML authentication system. Their role is to implement SSO for Eduphoria on the system. Refer the team to the following worksheet and troubleshooting information:
SAML single sign-on is available for all organizations. You can also set up single sign-on using ClassLink remote authentication.
How SAML SSO for Eduphoria Works
SAML for Eduphoria works the way SAML does with all other service providers. A common use case includes an organization that manages all user authentication using a single authentication system such as Active Directory or LDAP (generically referred to as an identity provider, or IdP). Eduphoria establishes a trust relationship with the IdP and allows it to authenticate and sign in users to Eduphoria accounts.
Another common use case would be a user who signs in to their district system at the beginning of the school day. Once signed in, they have access to other district applications and services (such as email or Eduphoria applications) without having to sign in separately to those services.
If a user attempts to sign in directly to an Eduphoria account, they are redirected to your SAML server or service for authentication. Once authenticated, the user is redirected back to their Eduphoria account and automatically signed in.
Giving students access to Eduphoria for online testing and individual data access is another supported workflow. When a student attempts to sign in, Eduphoria will redirect the request to the identity provider to validate the student. The IdP then forwards the successful result to Eduphoria, which grants a session to the student.
Requirements for Enabling SAML SSO
Meet with your organizational team responsible for the SAML authentication system (usually the IT team) to ensure your organization meets the following requirements:
- The organization either has a SAML server with provisioned users or is connected to an identity repository such as Microsoft Active Directory or LDAP. Options include using an in-house SAML server such as RapidIdentity or ADFS, or a SAML service such as Azure Active Directory Domain Services, Okta, OneLogin, or Ping Identity.
- If using an Active Directory Federation Services (ADFS) server, forms-based authentication must be enabled. Eduphoria does not support Windows Integrated Authentication (WIA).
- Eduphoria-bound traffic is over HTTPS, not HTTP.
Request the following information from the team:
- The remote login URL for your SAML server (sometimes called SAML Single Sign-on URL).
- The remote logout URL where Eduphoria can redirect users after they sign out of Eduphoria (Recommended).
- The SHA2 fingerprint of the SAML certificate from your SAML server. X.509 certificates are supported and should be in PEM or DER format. There is no upper limit on the size of the SHA fingerprint.
The next step is to enter the information in the Eduphoria Admin Center to enable SSO.
The IT team may require additional information from Eduphoria to configure the SAML implementation.
Enabling SAML SSO
You can enable SAML single sign-on for all staff and teachers only, or for all staff and students. When signing into Eduphoria, users will see a button that will redirect them to your primary sign-in page.
Before you start, obtain the required information from your organization’s IT team.
You must sign in to Eduphoria as a system administrator to follow these steps to enable SAML single sign-on.
Step 1: From the Eduphoria applications screen, select Management.
Step 2: From the Organization tab within Management, click the Directory Services & Student Sign-On button in the left side bar, then click on the SAML tab.
Step 3: For SAML2 Single Sign in URI, enter the remote login URL of your SAML server.
Step 4: For SAML2 Single Sign out URI, enter a logout URL where Eduphoria can redirect users after they sign out of Eduphoria (Recommended).
Step 5: As a requirement for Eduphoria to communicate with your SAML server, enter the SAML2 Public Signing Certificate.
Step 6: Once your SAML SSO configuration is set, check the box to Enable SAML2.
Note: You will not be able to check this box if any other single sign-on method is currently configured.
Step 7: When you are done making changes, click Save.
Managing Users in Eduphoria after Enabling SAML SSO
After enabling SAML single sign-on in Eduphoria, changes made to users outside Eduphoria sync to your Eduphoria account on next sign in. For example, if a user is added to your internal Active Directory or LDAP system, then the user is automatically added to your Eduphoria account on sign in. If a user is deleted in your internal system, then the user will no longer be able to sign in to Eduphoria. However, their account will still exist in Eduphoria.
By default, the only user data stored in Eduphoria when single sign-on is enabled is the user's given name, surname, persistent ID, and email address. Eduphoria does not store passwords.
To support authenticating student accounts as well, you will need to specify some additional attributes.
Switching Authentication Methods
Note: If you use a third-party SSO method to create and authenticate users in Eduphoria and then choose to switch to Eduphoria authentication, these users will not have a password available for login. To gain access, ask these users to reset their passwords from the Eduphoria sign-in page.
Technical Implementation Worksheet
This section is for the team in the company responsible for the organization’s SAML authentication system. It provides details about the Eduphoria SAML SSO implementation.
Topics covered:
- Required User Data to Identify the User Being Authenticated
- Configuring the Identity Provider for Eduphoria
- Configuring the SAML Server for Eduphoria
- Troubleshooting the SAML Configuration for Eduphoria
Required User Data to Identify the User Being Authenticated
When you implement SAML SSO access to Eduphoria accounts, you specify certain user data to identify the user being authenticated.
These topics describe the data you need to provide:
- Specifying a User’s Persistent ID in the SAML Subject's NameID
- Specifying Required User Attributes in the SAML Assertion
- Additional User Data Required for Student Accounts
Specifying a User Persistent ID in the SAML Subject's NameID
You should specify a persistent ID for the user in the SAML subject's name ID in SAML Assertions.
| Concept | Where Specified | Description | Example Value |
| persistent | <saml:Subject> <saml:NameID> | Persistent ID to identify the user. Used to uniquely identify the user in Eduphoria. | m_H3naDei2LNxUmEc |
Persistent ID example:
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">m_H3naDei2LNxUmEcWd0BZlNi_jVET1pMLR6iQSuYmo</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2014-04-23T21:42:47.412Z"/>
</saml:SubjectConfirmation>
</saml:Subject>
If the givenname, surname, and email attributes aren't provided, Eduphoria will not create or authenticate a user on login. Details on the required attributes are provided below.
Specifying Required User Attributes in the SAML Assertion
A SAML assertion contains one or more statements about the user. One statement is the authorization decision itself: whether or not the user was granted access. Another statement can consist of attributes describing the signed-in user.
When specifying the required user attributes, you should specify the attributes with the full namespace. For example, where the friendly attribute name might be 'surname', the actual value you should use for the attribute is: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname. Eduphoria will attempt to read the following attributes by their friendly names, if required.
| Concept | Attribute | Abbreviated Name Values | Full Namespace Value |
| first name | givenname | givenname |
|
| last name | surname | surname |
|
| email address |
emailaddress |
|
A user in Eduphoria is created or updated in accordance with this user's given name, surname, and email. See example below.
Required attributes example:
<saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
<saml:AttributeValue xsi:type="xs:anyType">Jeff</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
<saml:AttributeValue xsi:type="xs:anyType">Connors</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
<saml:AttributeValue>Jeff.Connors@eduphoria.net</saml:AttributeValue>
</saml:Attribute>
Eduphoria requires additional user attributes when supporting student accounts. See the section below for details on required attributes for students.
Additional User Data Required for Student Accounts
The only user data required by Eduphoria from your authentication system is the user's given name, surname, persistent ID, and email address. The given name and surname are the only attribute names you should use to capture information about a user's name. However, if you want to support student sign-on through SAML as well, you will need to include some additional attributes.
Eduphoria supports the following additional user attributes for student authentication. Define your data requirements in Eduphoria, then meet with your IT team to discuss adding user attributes to the SAML assertions.
| Concept | Attribute | Required Value | Full Namespace Value |
| role | role | Must specify “student” for any student authenticating to the system. | http://schemas.microsoft. |
| student local id | upn | The student’s local ID number as specified in the roster import. | http://schemas.xmlsoap. |
Configuring the Identity Provider for Eduphoria
| Attribute | Value |
| entityID | eduphoria.schoolobjects.web
|
| AudienceRestriction (Not required) | eduphoria.schoolobjects.web
|
Eduphoria does not enforce the AudienceRestriction attribute.
Configuring the SAML Server for Eduphoria
Some SAML servers may require the following information when configuring an integration with Eduphoria:
- Access Consumer Service (ACS) URL: Specify https://<<organization prefix>>.schoolobjects.com/AuthHosted/Saml2/AssertionConsumerService (case sensitive), where <<organization prefix>> is your Eduphoria subdomain
- Redirects to Eduphoria SAML Single Sign-on URL: Use HTTP POST
- Hashing algorithm (ADFS): Eduphoria supports the SHA-2 algorithm when using Active Directory Federation Services (ADFS)
Troubleshooting the SAML Configuration for Eduphoria
Here is Eduphoria's SAML 2.0 metadata. If your identity provider supports directly importing metadata URIs, it is available at https://<<organization prefix>>.schoolobjects.com/AuthHosted/Saml2/Metadata:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="urn:eduphoria.schoolobjects.web">
<md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>MIIDFTCCAf2gAwIBAgIIMbLXn67WX1swDQYJKoZIhvcNAQELBQAwITEfMB0GA1UEAxMWRWR1cGhvcmlhIEluY29ycG9yYXRlZDAeFw0xOTExMDcyMDM2MjlaFw0yMjExMDcyMDM2MjlaMCExHzAdBgNVBAMTFkVkdXBob3JpYSBJbmNvcnBvcmF0ZWQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDDrCYn23bWzgsrrmeYbmLfFcZtgxQYyVPKSB4idpJpMIc0oyuz6OtI2NhGgpyD0hH8B32BhpzFNP15uy77q0VOE4eZssx8QWk6TaPQrQRColV9G333AqwxP1OQk0A/tvrGw2JSYrk0DLLUAZPO7O7qBLF3ENF4WK9F2c/kL/aE54Ycnk8yK5X6islP/MgN4Xlu6TmcYQtYD1zYWkMnd++OPIOcRuFFqQIMbOgGC9mqgkMYqRw46uf9T5pFKRmlMHylV2so3KqJF3vpBEzEnhB1fo49gZoojKZAE/MfEkRuY95z/0v6pEwfcQDJnia9mBrfpVSBPiFn6cyOmQYUw0atAgMBAAGjUTBPMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgbAMBYGA1UdJQEB/wQMMAoGCCsGAQUFBwMIMB0GA1UdDgQWBBQXUP0YLg9aH12wNUr0+b/J1N74ETANBgkqhkiG9w0BAQsFAAOCAQEALEdbfPYgReeQ5VXPUqyw1ZGwDtY8+akqMiI9SFLKpUFpZi6nbaxdPL1Mn28dXd6XIuoUptzII5KbNHdQt9KVujCnNMr4gwFBQ3iMMM7VkCAa3ylGPAYw2X2m6ScrCYxgx/WGToqoZxmEFCKH6EMePqQRlaXXJIveOQjzCs+EqwpVb6oLyTzvhh/FKEsRUyP2pPP86NLQCorw2/Op2YgEqVTpjUtWuzSdt5lq+GqYrCHUJ2xwpgwT5UU2TFUA1AgXGDYwhtQjo+l+SlZTiAdZfZt0WZpLDmJKz+/rmQ94L0UCu3Xr26W3fmyuzWbw4TLVrXt15SQRhJxN0CWPWUfS3g==</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<<organization prefix>>.schoolobjects.com/AuthHosted/Saml2/LoggedOut"/>
<md:AssertionConsumerService index="0" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<<organization prefix>>.schoolobjects.com/AuthHosted/Saml2/AssertionConsumerService"/>
</md:SPSSODescriptor>
</md:EntityDescriptor>
Eduphoria expects a SAML assertion that looks as follows:
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="_86d1888b-f371-4b76-8aef-1ae7cba3717c" Version="2.0"
IssueInstant="2022-04-29T17:29:22.443Z" Destination="https://<<organization prefix>>.schoolobjects.com/AuthHosted/Saml2/AssertionConsumerService"
InResponseTo="_b2eacb00-16dd-4ce7-8218-51f851ddb76b">
<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">myidp.entity.id</Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
</samlp:Status>
Note: Replace <<organization prefix>> in the Destination attribute with your Eduphoria subdomain.
Eduphoria expects user attributes to be specified in an assertion's attribute statement (<saml:AttributeStatement>).
For the names and descriptions of the user attributes supported by Eduphoria, see the table in Specifying Required User Attributes in the SAML Assertion. Users will not be authenticated if emailaddress, givenname, or surname attributes are missing.
Attribute names are case sensitive and should be all lowercase.
The subject name Id should only be persistent, though an email address name Id will not prevent login. Persistent name Id is preferred to prevent the creation of duplicate user accounts if the user’s email address changes.
Decoding SAML Messages for Debugging
The following procedures describe how to view the SAML response from your service provider within your browser when troubleshooting a SAML 2.0–related issue.
For all browsers, go to the page where you can reproduce the issue. Then follow the steps for the appropriate browser:
Google Chrome or Microsoft Edge
These steps were tested using version 54.0.2840.87m. You may need to adjust the steps accordingly if you use another version.
- Press F12 to start the developer console.
- Select the Network tab, and then select Preserve log.
- Reproduce the issue.
- Locate a SAML Post in the developer console pane. Select that row, and then view the Headers tab. Locate the SAMLResponse attribute containing the encoded request.
Mozilla Firefox
This procedure was tested on version 37.0.2 of Mozilla Firefox. You may need to adjust the steps accordingly if you use another version.
- Press F12 to start the developer console.
- Click Options (the small gear icon) in the developer tools window. Under Common Preferences, select Enable persistent logs.
- Select the Network tab.
- Reproduce the issue.
- Locate a POST SAML in the table. Select that row. In the Form Data window, select the Params tab and find the SAMLResponse element.
Apple Safari
These steps were tested using version 8.0.6 (10600.6.3). You may need to adjust the steps accordingly if you use another version.
- Enable Web Inspector in Safari. Open the Preferences window, select the Advanced tab, and then select Show Develop menu in the menu bar. Now you can open Web Inspector.
- Select Develop, then select Show Web Inspector.
- Select the Resources tab.
- Reproduce the issue.
- Locate a saml-signin.aws.amazon.com request.
- Scroll down to find Request Data with the name SAMLResponse. The associated value is the Base64-encoded response.
What to Do with the Base64-Encoded SAML Response
Once you locate the Base64-encoded SAML response element in your browser, copy it and use your preferred Base-64 decoding tool to extract the XML tagged response.
Note: Because the SAML response data might contain sensitive security data, we recommend using a tool installed on your local computer that does not send your SAML data over the network. An online base64 decoder isn’t guaranteed to be secure.
Built-in option for Windows systems (PowerShell):
PS C:\> [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String("base64encodedtext"))
Built-in option for MacOS and Linux systems:
$ echo "base64encodedtext" | base64 --decode
Comments
0 comments
Article is closed for comments.