SAML SSO - I'm using Azure AD (Microsoft, Cloud)

Before you read these instructions, make sure you've read our guide: How can I setup SSO between my school and Grok?

The below information is designed to help you set up SAML2 SSO if your identity system is Azure AD. If you are not using Azure AD, go back to the FAQ above and select the instructionsyour identity system. 

Guide for setting up SAML2 SSO: using Azure AD

Steps to setting up SAML2 SSO with Grok 

1. Create the application in your identity provider 2. Send Grok the information we need to set you up on our side 3. Test the integration on staging 4. Get Grok approval for deployment to production 5. Re-test on production to confirm it's working

1. Create the application in your identity provider

1.1. Create the application

Login to your Azure Portal. Click on Azure Active Directory on the far left, and then click on Enterprise Applications:

Click on New Application at the top of the pane:

Click 'Create your own application' up the top:

Then select 'integrate any other application you don't find in the gallery' It's probably best to use 'Grok Learning (staging)' here for the initial setup to keep the apps distinct.

Or in 'legacy view', click on Non-gallery application:

Enter the Name of the application. Use a name like "Grok Learning (staging)" for when setting up staging, and "Grok Learning" when setting up production. This will allow you to distinguish between the two different apps. Click on the Add button at the bottom of the pane once the name has been entered:

1.2. Configure SAML as the SSO source to the application

Once the application has been created, click on Single Sign-on on the left hand side of the application pane:

Click on SAML as the SSO method:

Click up Upload metadata file at the top of the page.

Upload the appropriate Grok Learning SAML metadata file you downloaded earlier. For the staging application, upload our staging metadata. For the production application, upload our production metadata:

Once you click on Add, the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) fields will be auto-populated. For the staging application, the URLs will start with https://dev.groklearning.com. For the production application, the URLs will start with https://groklearning.com.

After talking to the Grok Learning SSO team (see later), they will provide you with a URL to use in the  Sign on URL section. This will allow your students and teachers to initiate a SSO session to Grok without having to visit Grok Learning first -- they can launch the website directory from their list of available applications.

Click on Save at the top of the SAML Configuration pane.

After clicking save, you might be prompted to validate the application. Click on No, as we have not finished setting up the application yet.

1.3. Setup claim rules to send user data over SAML

Scroll down to section 2: User Attributes & Claims. Click on the edit button on the right.

Here is where we configure what attributes get sent to Grok Learning so SAML SSO. Azure AD has placed some default claim rules in the application. We want to delete all of them except for the nameidentifier one. To delete a claim rule, click on the triple dots icon next to the claim rule, and then click on Delete.

Repeat this process until all of the default claim rules have been removed, apart from nameidentifier.

Now, we want to add the claim rules Grok Learning wants. Click on Add new claim at the top of the pane:

We want to setup the following claim rules:

All of these claim rules do not have a Namespace set and are of Source type "Attribute". For example, adding the preferred first name claim rule:

Repeat this process for all of the above claim rules. The resulting claim rules page should look like what's shown below.

Next, we want to change the Name Identifier Value and add Groups to our claim rules. These are the two edit buttons at the top of the pane:

Click on the edit button for the Name Identifier Value. We want to change the name identifier format to "Persistent" and change the Source attribute to "user.objectid". Click on Save at the bottom of the pane.

Next, click on the edit button for the Group claim rules. You need to configure your groups claim rules such that the scholastic year and teacher/student groups are sent across to Grok. You can do this however you'd like, but the simplest is to send across All groups to Grok.

The Source attribute should be "Group Ids" (send only the UUID's of the groups across via SAML). You want to specify a custom name for the name of the group claim, and this Name should be "group". Click on Save at the bottom of the pane.

Your claims rules should now look like the image below. If it all looks good, close the pane.

2. Send Grok the required information

Scroll down to section 3: SAML Signing Certificate. Copy the App Federation Metadata Url. You need to send this URL to the Grok Learning SSO team.

Now is the time to send an email to the Grok Learning SSO team at support@groklearning.com. In your email, make sure you include the following information:

• specify which school you're wanting to setup SSO for
• copy in the Metadata URL copied from above
• provide the group UUIDs that indicate which scholastic years and/or which roles. In most cases, this will mean one group for each year (e.g. group ID "ab1f3af2-28ae-46c4-8698-d130be435acc" maps to Grade 8 students) and a separate group for teachers.

Once the Grok team receives your email, we'll get started on setting up your integration on our side. In the first instance, we will set you up on our staging server, to make sure that everything works as expected before deploying to production. 

The SSO team might have some additional questions for you during this time, so please keep an eye on your emails. We'll email to let you know once the setup on our side is done. 

3. Test your integration on Grok staging

Once the Grok team has setup the integration on Grok staging, we will email you to confirm that it's set up. 

3.1. Set up SSO initiation URL

In the confirmation email, we will send a URL to start a SSO session to Grok via your application. This will be of the form " https://dev.groklearning.com/sso/saml2/login?idp=IDENTIFIER" for staging and "https://groklearning.com/sso/saml2/login?idp=IDENTIFIER" for production. 

This URL can be set at the Sign On URL for the application back in the Single Sign-on settings. This allows your teachers and students to initiate a SSO session to Grok Learning via your application. The Relay State and Logout URL fields should be left blank.

3.2. Assign application to user groups (or not require user assignment)

Once you have your SSO initiation URL, you are ready to test your staging application. To do this, you either need to assign the application to the appropriate users/groups, or you need to not require user assignment to the application. To not require user assignment to the application, click on Properties on the left pane, scroll to the bottom, and click on No next to User assignment required?. Click on Save at the top of the pane. If you instead want to assign the application to the appropriate users/groups, follow your normal process for doing this.

3.3. Test as a student user; test as a teacher user

Once you've allowed users access to the application, you need to test your application with a student account (who has a scholastic year) and a teacher account. These can be fake users or real users; doesn't matter as long as you can login as that user. We want to test that the user can log in, and that all their details (name, school, grade, email address, etc) are populated correctly in Grok. 

In an incognito/private window (this helps for testing things with a clean slate), navigate to the SSO initiation URL:

This should load your schools SSO sign in page. In our Demo School, we haven't done any company branding so we get the basic Microsoft default login screen. Yours is likely to show your school logo.

Enter the email address and password of your test student account. In our case, we're using a test student who is in grade 10:

If everything has been setup correctly (SAML claim rules and app assignments), then you should now be logged into the Grok Learning staging server as this student. To confirm this, click on your name in the top right corner of the page and go to your account settings. Under the Account Details tab, confirm that the Full name, Nickname, Family name, and Role are correct for the user you logged in as:

Under the Communication tab, confirm that the Email address is correct for the user you logged in as:

Under the Institutions tab, confirm that there is an entry for your Institution (school), and that the entry has the correct Role and Grade.

If all three of these sets of settings look correct, then the student integration should be working.

Next, logout of Grok or close the incognito/private window. Navigate to the SSO initiation URL again in a new private/incognito window and now login as a teacher account:

Run through the same checklist as testing the student account. Under the Institutions tab, the Role should be Teacher (verified) and there should not be a Grade set.

4. Get Grok approval for deployment to Grok production

Once you've checked that both the student and the teacher account are working, let the Grok Learning SSO team know and we'll double check on our side as well. Once we've confirmed this, we may have some additional questions for you before we set up the production change on groklearning.com. 

5. Re-test on production to confirm it's working

The Grok SSO team will confirm once we've deployed the production change. This should mean your SSO integration is working and ready for students and teachers to use! It's a good idea to re-test at this stage to confirm it's all working. You can follow the steps in section 3 above. 

You should also let the head of digital technologies or whomever is coordinating your school's use of Grok know that this is ready to use.