Microsoft / Azure AD
Last updated
Last updated
Curiosity supports User Management via Microsoft Azure Active Directory Single Sign-On (SSO). Rather than maintaining names, email addresses, and passwords for Users that may log into the application, you can connect with accounts that already exist in your Microsoft organization directory (meaning that Users are not burdened with yet another password to remember).
To do so, you require three pieces of information:
a "Tenant ID" (also known as a "Directory ID")
a "Client ID" (also known as an "Application ID")
a "Client Secret"
These need to be associated with a Microsoft Azure "application" that is configured to work with Curiosity. To create one, follow the instructions below.
It is presumed that you have administrative privileges to make the changes to your Azure organization. It is also presumed that you have an administrator account for your Curiosity application.
Go tohttps://portal.azure.com and ensure that you are logged in with an account that has access to make changes. If you are uncertain then try to follow the steps below and talk to your administrator if any of them result in any "unable to access" or "access denied" error.
Click into the search bar at the top of the page and starting typing "app registrations" until the autocomplete box shows "App registrations" and as an option.
Click on the "App registrations" button and then click "+ New registration".
Enter a name such as "Curiosity SSO".
Leave the "Who can use this application or access this API?" option as "Accounts in this organizational directory only".
Ensure that "Web" is selected in the drop-down list under "Redirect URI (optional)".
You need to tell the SSO process how to get back to Curiosity after a successful login, which is the purpose of the Redirect URI. The format of the URI is:
{domain}/api/microsoftsso/completed-login-attempt
If your Curiosity application is hosted by us then it will look something like this:
https://acmecompany.curiosity.ai/api/microsoftsso/completed-login-attempt
If you have installed a local instance of the application with the default settings then it will look like this:
**http://localhost:8080/api/microsoftsso/completed-login-attempt**
Click the "Register" button at the bottom of the page.
The "Overview" page that is shown next has the first two pieces of information that you require, the "Application (client) ID" and "Directory (tenant) ID" -
Both consist of five sections of alphanumeric characters, separated by hyphens.
Generate a Client Secret by clicking on "Certificates & secrets" in the menu on the left and then clicking on "+ New client secret" in the "Client secrets" section.
Enter a description - it's fine to use something like "Curiosity SSO" again here.
Select an "Expires" value. It is considered a security best practice to choose the shortest duration offered (one year, in this case) but the cost is that each year you will have to generate a new client secret (and update the Curiosity configuration with this new secret). If you are experimenting with test data then you may consider the "Never" option so that you do not need to worry about this.
Click "Add". There will now be a new row in the "Client secrets" section that shows the description, expiration date, and the secret's "Value" - this is a long piece of text consisting of upper and lower case letters, numbers, and symbols.
Important: Copy the value now because you will not be able to see it again!
Click "Expose an API" in the menu on the left and then "+ Add a scope".
This will tell you that:
"You'll need to set an Application ID URI before you can add a permission. We've
chosen one, but you can change it."
Leave it as the auto-generated value and click "Save and continue".
Populate the following values:
"Scope name" of "SSO"
"Who to consent?" to "Admins and users"
"Admin consent display name" and "User consent display name" to "Log in with your Microsoft Account"
"Admin consent description" and "User consent description" to "This allows the application access to your name and email address and enables logging into Curiosity"
(All of the above are advisory defaults but you can enter any text that you want should you wish to customize them or make them more descriptive)
Click "Add scope".
Finally, click "Token configuration" in the menu on the left and then "+ Add optional claim". Set the "Token type" to "ID" and then tick the "email" box.
Click "Add". You will see a message that says:
"Some of these claims (email) require OpenId Connect scopes to be configured
through the API permissions page of by checking the box below"
Tick the "Turn on the Microsoft Graph email permission" box and then click "Add".
Double check that the token configuration has the email configured.
Double check that the correct permissions are set.
(Optional: You can click "Branding" in the menu on the left and change the name that will appear on the Microsoft Azure login page and specify a logo, terms of service, etc.. but if you may want to do this then it makes sense to complete the other steps in this article to see how it looks and come back to this section to customize later)
Click the menu button at the top left, then click "Settings", then "Accounts" and then "Single Sign-On".
(If you don't see a "Single Sign-On" option and the only item under "Accounts" is "Profile" then you are not logged into Curiosity with an administrator account)
Click "Microsoft" and then enter the three pieces of information that you generated above. Be careful to enter them in the correct order as the Azure "Overview" page displays the "Application (client) ID" above the "Directory (tenant) ID" but the Curiosity form has the fields ordered as:
Tenant ID
Client ID
Client Secret
Click "Save".
Microsoft Azure SSO is now configured for this application.
To test it, log out (by clicking the user name at the top right and then clicking "Logout" in the panel that appears). The log in screen will now present a "Log in with Microsoft" option.
Click "Log in with Microsoft" and you will be redirected to a Microsoft page where you can provide an email address. This email address must be one that is associated with your Azure organization. If you have previously logged in with one of these email addresses in the browser that you are using then you will see this as an option or you can click "Use another account". If you have not previously logged in with any of the emails for your Azure organization then you will be prompted to type in an email address to sign in as.
Once you have selected an account (and password, if required—if you have previously logged in with an applicable account and you are still logged in to that account then you may not be prompted for a password) then you will be asked for your permission to "Sign you in and read your profile". Click "Accept" and you will be redirected back to the Curiosity application as a logged-in User relating to the email address that you specified.
If a User account does not exist in Curiosity for the email that you chose then one will automatically be created (so that the Curiosity application administrators can set access rights and permissions). The email and name details from the Microsoft account will be used to populate the account in the Curiosity application. If a User account already existed for the specified email then any permissions that have been set will not be altered but the name will be updated if the name in the Microsoft account does not match the name in the Curiosity User account.
If you wish to remove Microsoft Azure SSO as an option for your Curiosity application then go back to Menu / Settings / Accounts / Single Sign-On / Microsoft, clear the "Tenant ID" text and click Save. This will remove all three pieces of SSO configuration from the Curiosity application and the "Log in with Microsoft" option will no longer be presented.
You must enter the three configuration values correctly. If any of them are wrong then you may experience one of the following:
If the Tenant ID is wrong then you will be shown an error from Microsoft as soon as you are redirected from Curiosity to Microsoft.
If the Tenant ID is correct but the Client ID is wrong then you will successfully be redirected to the Microsoft account selection screen but you will be shown an error after selecting an account (and entering the password, if prompted).
If the Tenant ID and Client ID are correct but the Client Secret is wrong then you will be able to select an account but you will receive an error when you are redirected back to Curiosity.
It is also of vital importance that the "Redirect URI" that you set in the Azure Portal earlier was correct. If this is not correct but everything else is right then you will be able to select a Microsoft account but, instead of being redirected back to Curiosity, you will receive an error:
To check (or to correct) the "Redirect URI" go back to the Azure Portal and click "Authentication" in the menu on the left and ensure that there is an entry in the "Web" section with a Redirect URI that is correct.
