This article describes how SSO (via Microsoft OpenID Connect OAuth2) can be achieved to power authentication and authorisation for your users with the SimplyDo platform.

Whilst most SimplyDo functionality can (and usually will) be set-up for you by your account manager during onboarding, it may be worth taking a look through this guide in case there are other options you may wish to take advantage of.

This document covers the SimplyDo setup in addition to settings you may wish to change on your Active Directory tenant.

1. Introduction

SimplyDo has an app registered and verified with Microsoft Azure. This means that if your organisation already uses services like Office365 and Microsoft Teams, then there is usually very little to do other than provide your users with the ability to grant consent to connect to the SimplyDo app - or, alternatively, allow an Active Directory administrator to grant consent on behalf of your tenant.

Login with Microsoft is available to all SimplyDo organisational accounts.

The Login with Microsoft OpenID Connect OAuth2 flow involves the following steps:

  • The user arrives at the SimplyDo platform (web or mobile app);

  • The user is redirected automatically to login with your tenant on a Microsoft login page;

  • Upon successful login, the user provides consent that allows SimplyDo to access their basic profile information (this only occurs during the first login if consent is not already granted);

  • The user is redirected back to the SimplyDo platform with a special code;

  • SimplyDo exchanges the authorization code for an access token;

  • SimplyDo accesses the Microsoft Graph API, using the access token, in order to read the user’s basic profile information (leveraging the `User.Read` permission);

  • The user is then logged-in to SimplyDo and is returned to the web or mobile app they started from.

These steps are handled automatically in concert between SimplyDo and Microsoft systems.

2. Useful information

The following information may be useful when configuring your systems to work with SimplyDo OAuth2 authentication (e.g. granting consent to staff).

Application ID: dbf692fe-35c1-4511-9178-9131e6511712

Callback URL: https://login.simplydo.co.uk/auth/oauth/microsoft/login/callback

3. Enabling Microsoft authentication in SimplyDo

This section describes how the SimplyDo platform can be configured to allow Microsoft authentication for your organisational account.

Please note: these steps will likely be carried out by your account manager on your behalf.

3.1. Turn on Login with Microsoft

In your SimplyDo account navigate to the Sign-on tab of your organisational Settings.

Here toggle on the option for “Microsoft”.

Login with Microsoft OAuth2 single sign-on is now enabled for your organisation.

When visitors arrive at your login page on SimplyDo they will now be given the option to “Login with Microsoft”.

3.2. Set-up auto-login (optional)

SimplyDo can automatically redirect visitors to your chosen login system. This means that they can bypass the SimplyDo login selection screen and be taken straight to the Microsoft login page.

To do so, navigate to the Sign-on tab of your organisational Settings (as above).

On this tab, choose “Login with Microsoft” in the Auto sign-on dropdown.

3.3. Configure Microsoft authentication (optional)

SimplyDo supports a number of additional configurations and tweaks to tailor Microsoft login for your organisation’s particular needs.

For example, you can configure the set of API permissions requested of your users, create attribute mappings, and more.

To access these settings, first navigate to the Sign-on tab of your organisational Settings (as above). Once here, select the “Manage” link next to the “Microsoft” option.

On this tab a number of options are presented, as described below.

3.3.1. Tenant ID

Enter your Active Directory’s Tenant ID into the Tenant ID field to take users directly to the branded version of your organisation’s login screen.

3.3.2. Permissions scope

In the Permissions scope field you can enter a number of Microsoft Graph permissions to request of the user during the login process. This forms part of the user login consent process.

The permissions are documented on the Microsoft Graph permissions webpage.

The SimplyDo defaults should be sufficient in most cases, but if you want to include more, they can be added in this field space-separated. For example, if you want to use the User.Read and User.ReadBasic.All permissions, then enter these as “User.Read User.ReadBasic.All”.

Please note that in all cases SimplyDo will also request the openid, email, and offline_access permissions, which are required as a minimum to allow sign-in.

3.3.3. Attribute mappings

In most cases, you will not need to change these. However, in some cases, Active Directories are setup such that user profile attributes (and email addresses) are presented with different keys.

For example, if your users have several email addresses associated with their Active Directory profiles, and are included in an “emailAddress” field (rather than the default “mail”) in Active Directory, and the required email is the one ending in @company1.com then you could set this up as follows.

Please note that any number of additional and custom mappings can also be included. This might be useful for allowing SimplyDo to understand your organisational structure in order to automatically assign roles, and more. Please speak to your account manager for more information on this.

4. Managing the SimplyDo app in Active Directory

Please note: This section assumes that you are using the Microsoft Azure version of Active Directory.

You can configure the SimplyDo app in Active Directory according to your needs.

To get started, you need to find the app in your Active Directory tenant.

In the Azure portal, navigate to your tenant and then find the Enterprise applications link.

On the Enterprise applications page, find the “Simply Do” app in the list or by filtering by application name.

Click on the application name link to open up its management panel.

Please note: if the SimplyDo app is not listed in your Enterprise applications page, you may first need to “trigger” the app to appear by initiating a login from SimplyDo first. Please get in touch with your account manager if you need support with this.

From the app’s management panel, a number of options are available depending on the needs of your organisation and IT and information security teams. Below we include instructions on some example configurations.

4.1. Grant admin consent (optional)

By default, users accessing SimplyDo for the first time via Microsoft login will be asked for consent to access their work profile via the Microsoft Graph API.

You may wish to grant consent to all users by default on behalf of your organisation, so that users themselves do not need to do so.

To grant admin consent, navigate to the Permissions tab of the SimplyDo management panel, and click the “Grant admin consent for <tenant name>” button.

4.2. Configure app properties (optional)

On the Properties tab, a number of other options are available.

The Enabled for users to sign-in toggle can be used to enable or disable the SimplyDo app for your organisation.

The Assignment required toggle can be used to limit the application to specific users or groups in your organisation. If this is set to “Yes”, then you will need to choose specific groups or users by visiting the Users and groups tab in the app’s management panel.

The other settings on this tab allow you to change the name, logo, and other information to be presented to users at sign-on time.

5. Conclusion

In this document we have outlined the process for configuring SimplyDo single sign-on via Microsoft authentication.

If you have any questions or problems with this setup, please just get in touch with your account manager.

Did this answer your question?