Microsoft Single Sign-On (SSO) Setup Guide
This guide walks through registering an application in Azure (Microsoft Entra ID), granting it the correct permissions, handling admin consent, and configuring the resulting credentials in the application’s Single Sign-On settings.
#1:
Open the Azure Portal (https://portal.azure.com) and go to the Azure services home page. From here, click on App registrations to begin creating the application that will be used for SSO.
#2:
This is the App registrations page. Click + New registration to register a new application.
#3:
On the Register an application page:
-
Enter a Name for the application (this is just a display name and can be changed later).
-
Under Supported account types, choose the appropriate option (typically “Single tenant only” for internal use).
-
Under Redirect URI, select Web from the dropdown and enter the callback URL that the application will use to receive the authentication response, in the format https:///msauth.
-
Click Register.
#4:
After registration, you land on the Authentication page for the new app. This confirms the redirect URI you entered has been configured under the Web platform. This is also where you would come back to later if you need to add or edit redirect URIs.
#5:
If the application needs to be reachable from more than one address (e.g. a different server IP or domain), click Add Redirect URI and select the platform type - choose Web again.
#6:
Enter the additional redirect URI (again in the format https:///msauth) and click Configure to save it. You can repeat this for as many addresses as required.
#7:
Next, go to Certificates & secrets in the left-hand menu. This is where you generate the Client Secret the application will use to authenticate itself. Initially this list will be empty. Click + New client secret.
#8:
In the Add a client secret panel:
-
Enter a Description (e.g. the app name).
-
Choose an Expires duration (the recommended default is fine, but note the expiry date for renewal later).
-
Click Add.
#9:
The secret’s Value column shows the actual secret string immediately after creation - copy this value straight away, as it will not be shown again once you navigate away from this page. This value is what gets entered as the Client Secret in the application’s SSO settings later.
#10
Go to API permissions. By default, a new registration only has Microsoft Graph > User.Read (Delegated), which allows the app to sign in and read the user’s profile. This is normally sufficient as a starting point.
#11:
Once users have signed in and consented (or an admin has granted consent - see the request/approval process below), additional delegated permissions such as email, openid, and profile appear under “Other permissions granted for [organization]”, each marked with a green check and “Granted for [organization]” status. These are the standard OpenID Connect scopes needed for SSO sign-in.
Admin Consent - Request and Approval Process
If the person signing in for the first time is not an admin, they won’t be able to consent to the app’s permissions themselves. Instead, they’ll be prompted to send an admin consent request. The following screenshots illustrate that flow.
#12:
When a non-admin user first attempts to sign in via SSO, they’re shown an “Approval required” prompt from Microsoft, listing the permissions the app is requesting (e.g. “View users’ basic profile”, “Maintain access to data you have given it access to”). They can optionally enter a justification and click Request approval.
#13:
On the admin’s side, this request appears in the Azure Portal under Enterprise applications > Admin consent requests > My Pending. The admin can see the app name, application ID, and the date the request was created/last updated.
#14:
Clicking into the request opens the Details panel, showing the application name and configured Reply URL. From here the admin selects Review permissions and consent to see exactly what the app is asking for.
#15:
This opens the standard Microsoft “Permissions requested” consent screen, showing the requesting user, the app name/domain, and the specific permissions being requested. Since the app is not published by Microsoft, a warning to that effect is shown. The admin reviews the permissions and clicks Accept to grant consent for the whole organisation (so individual users won’t be prompted again).
#16:
After the request is submitted, the user sees a “Request sent” confirmation, letting them know their admin has been notified and they’ll be informed by email once it’s been reviewed.
Configuring SSO in the Application
Once the app registration, client secret, and permissions/consent are all in place in Azure, the final step is to enter those details into the application itself.
#17:
In the Amethyst Webadmin interface, go to Settings and click on Single Sign-On.
#18:
On the Single Sign-On Settings page, under the Microsoft section, fill in:
-
Client ID - the Application (client) ID from the Azure app registration’s Overview page.
-
Tenant ID - the Directory (tenant) ID from the same Overview page.
-
Client Secret - the secret value copied in step 10 (once saved, this field will show “(unchanged)” on future visits).
-
Redirect URI - must exactly match one of the redirect URIs configured in Azure (steps 3/6), e.g. https://yourserver.example.com/msauth.
-
Enabled - tick this checkbox to activate SSO.
Click Save to apply the settings.