This is a guide designed for those using Microsoft Azure to configure a single sign on method to Digiexam from within the user's Microsoft Office Portal.
Step 1: Enable SAML Integration in Digiexam
Start by acting as account manager in Digiexam. This role gives you the ability to create integrations, and in this case you will enable a SAML integration.
Click the "Enable SAML Integration" button on the Integrations tab of your Digiexam Organization.
Figure 1
Step 2: Create an Enterprise Application in Azure
Navigate to your Azure Portal (https:portal.azure.com). You will be working with Microsoft Entra ID (formerly Microsoft Azure AD). Search for Entra ID or choose this from the Azure services in your Azure portal.
Once you have entered your Microsoft Entra ID service be sure to select "Enterprise Applications" from the portal management menu.
Figure 2
Choose "New Application" to create your Digiexam app that will eventually allow for SSO for your users.
Figure 3
You will now select "Create your own application" as opposed to choosing from Microsoft's App Gallery.
Figure 4
Name your application. This is the name that will display for users once the app is configured and enabled in their Office Portal. We suggest using "Digiexam" to ensure that users can easily search and find this entry point from within your Office Portal.
Figure 5
Choose "Create." This process may take several seconds to complete.
Step 3: Set up Single Sign On
With your Digiexam Entra ID application now created you will need to set up the single sign on method. Select the setup button in the Entra ID app and get started.
Figure 6
The single sign-on method used is SAML. Select this from the menu provided in the app configuration.
Figure 7
You will now be redirected to a configuration page for this single sign-on method, and it is here you will complete the remainder of the configuration of the Microsoft Entra ID application.
Step 4: Basic SAML Configuration
Begin by editing the basic SAML configuration for the application.
Figure 8
Use the Entity ID and the Assertion Consumer Service URL provided below when editing the basic configuration settings.
- Entity ID: https://app.digiexam.com/api/v1/saml/metadata
- Assertion Consumer Service URL: https://app.digiexam.com/api/v1/saml/login
Figure 9
Save these settings to return to the app configuration.
Step 5: User and Group Configuration
In order for users or groups of users in your organization to be able to access and use this application properly you will need to configure which users / groups should have access. Choose "Add user/group" in order to select from users or groups from within your Microsoft organization.
Figure 10
Save these changes and return to your Single sign-on configuration.
Note: When a user logs in using the SSO you are building it will provision their account in your Digiexam environment. The roles that these individuals have within the Microsoft environment will attempt to be attributed to the account created in Digiexam (administrator or teacher). All users receive a student role by default.
Step 6: Configure Attributes & Claims
The configuration of attributes and claims allows the Microsoft Entra ID app to communicate values from the app to your Digiexam environment. Navigate on the single sign-on configuration page to "Attributes & Claims," and begin editing.
Figure 11
The three values that are of importance are:
- FirstName
- LastName
- EmailAddress
Note: Each value should be copied and pasted directly into the "Name" field of its own unique claim. Ensure that the Namespace field is empty as this may cause the integration to produce an error when attempting to login.
Click on each claim so that you can edit it. Here is an example of how the EmailAddress claim could be managed.
Figure 12
You will need to edit each claim and attribute manually. Be sure to apply the correct source attribute to the claim. In the example in Figure 12 the UPN in the Microsoft environment is actually the email address of the individual. Map these attributes based upon your own organization.
Figure 13
Save each claim and return to the Single sign-on configuration settings.
Step 7: Download (and Upload) your SAML Certificate
You should now see that the SAML certificate field is filled in and updated hen looking at your single sign-on configuration settings in the Microsoft Entra ID application.
Download the Federation Metadata XML file as this is the file you will need to upload into your Digiexam environment.
Figure 14
Once downloaded, navigate back to your Digiexam environment and upload the XML file. If the file is correctly configured, a blue "upload" button will appear. Click this and complete the upload.
Figure 15
Step 8: Test the App
You can test the application from within your Microsoft Entra ID application using the "Test" button located at the bottom of the SSO configuration page. This will allow you to test the app during different parts of the configuration and setup.
Figure 16
Alternatively you can test the application by navigating to https://portal.office.com and choosing the Entra ID application that you just configured. It should be displayed under "other apps."
Figure 17
In the event that you should require assistance with this configuration please contact us at support@digiexam.com.
Comments