Setting up Single Sign-On with Microsoft Entra ID (formerly Azure Active Directory)
In this guide, we’ll explain how to set up Single Sign-On using Microsoft Azure.
While the screenshots in this guide are from the Azure portal, this guide also applies to the Microsoft Entra admin center.
1. Log in
Go to portal.azure.com and log in using your Microsoft account.
You can create a Microsoft account if you don’t have one.
2. The Azure Subscription
If you already have an active Microsoft Azure subscription, you can skip this step and go straight to 3. Setup a new Application.
To use Microsoft Azure services, you need an active Microsoft Azure subscription. You can try Microsoft Azure for free for a limited time. Once this trial period expires, you can choose to extend it on a “pay-as-you-go” basis.
If you don’t have an active subscription yet, you should see a link on the main page to acquire one. Otherwise, click the menu button in the top left corner and select “All services”.
Next, type “subscriptions” into the search box and click “Subscriptions”.
Once you’ve completed the registration process, continue with the following steps.
3. Setup a New Application
To connect to Declaree, you’ll need to create a new application. First, click the menu button in the top left corner and select “All services”.
Next, type “enterprise” into the search box and click “Enterprise applications”.
On the “Enterprise applications | All applications” page, click the “New application” button.
You will now arrive in the “Microsoft Entra Gallery”. However, instead of searching for an existing application, click “Create your own application”.
A panel on the right side of the screen will appear. Input the name for the app. You can choose any name you like, but for clarity, we will call it “Declaree”.
Make sure you’ve selected the bottom option, “Integrate any other application you don't find in the gallery (Non-gallery)”, and click “Create” at the bottom of the panel.
Once the “Declaree” application has been created, you’ll be transported to the Overview page. The next step is to add the users you want to give access to Declaree.
4. Adding Users
On the left side of the page, click “Users and groups”.
Next, click the “Add user/group” button.
On the “Add Assignment” page, click “None selected”.
Another panel will open on the right side of the screen. Select the users you wish to add and click “Select”.
To finalize, click “Assign”.
You’ll now have assigned the users who will be able to sign into Declaree using Single Sign-On. In the next section, we’ll set up a unique subdomain which we will link to your organization’s Azure directory.
5. Setting up a Subdomain in Declaree
Each organization within Declaree is provided with a unique subdomain. This subdomain will serve as the entry point for your users and ensures that Declaree connects to your Azure account specifically, preventing any mix-ups with other accounts.
To find your organization’s subdomain, log into Declaree and go to “Configuration” → “Single Sign-On”. You’ll find the subdomain under the “General” tab. If the subdomain is particularly long or otherwise unwieldy, you can choose to change it.
Once you’re satisfied with the subdomain, make note of it and continue to the next step where we will link the subdomain to Azure.
6. Setting up Single Sign-On in Azure
Return to the Azure portal. While still within your “Declaree” enterprise application, click “Single sign-on” in the menu on the left side of the page. You’ll be presented with several single sign-on methods. Declaree uses “SAML”.
You’ll now see the setup page for Single Sign-On using SAML. This process has been divided into several steps. We’ll only have to modify some of them.
Click the “Edit” button for step 1.
A panel will appear on the right side of the page. Fill in the following details (replacing “yourcompany” with the subdomain that you set in the previous step) and click “Save”.
Once the details are saved, you will be asked if you want to test the configuration. Since we still have to configure Single Sign-On on the Declaree side, select “No, I’ll test later”.
Now that everything is set up in Azure, we’ll move on to the last step and configure Declaree.
7. Setting up Single Sign-On in Declaree
While keeping the Azure portal open, return to Declaree. Go to “Configuration” → “Single Sign-On” and click the “SAML” tab. Here, you’ll find a collection of fields we’ll have to fill in. Start by ticking the “Activate SAML 2.0” checkbox.
In the Azure portal, scroll down to step 3. This box contains, among other things, the “App Federation Metadata URL”. Copy the URL and paste it into the “Metadata URL” field in Declaree. Click the reload button on the right end of the field and the values for the “Issuer ID” and “SSO login URL” fields and the certificate will be retrieved automatically.
If this fails, you can enter this data manually. The table below describes which details to fill in:
From Azure… | To Declaree… | Note |
|---|---|---|
Certificate (Base64) | Signing certificates | Download from Azure, upload to Declaree. |
Login URL | IdP SSO login URL | |
Microsoft Entra Identifier | Issuer ID | |
Logout URL | IdP SSO logout URL | In Declaree, click “Advanced” to reveal this field |
Next, set the correct value for the “NameID format” field in Declaree. In most cases, this should be “Email”. However, if you know this not to be correct (for instance, your users log in using a username) use your own judgment.
Finally, click the “Save” button at the bottom of the page. This should conclude the configuration. The next step is testing the connection to see if everything works.
8. Testing the Connection
The final step is to test the configuration. There’s two ways to do this:
In the Azure Portal, scroll down to step 5 and click “Test”
Go to yourdomain.declaree.com and log in
If everything was set up correctly, you should now be able to log in using SSO.
Troubleshooting
Solutions for common problems.
Signed-in User Not Assigned to a Role
The user receives a message like this:
AADSTS50105: Your administrator has configured the application Declaree ('XXX') to block users unless they are specifically granted ('assigned') access to the application. The signed in user 'XXX@XXX.XXX' is blocked because they are not a direct member of a group with access, nor had access directly assigned by an administrator. Please contact your administrator to assign access to this application.
To resolve this, add the user to the Declaree application. See 4. Adding users for instructions.
Application Not Found in Directory XXX
This error usually means that the user who created the enterprise application is not listed as the owner. To set a user as the owner, go to the Azure portal, find your Declaree app under “Enterprise applications” (see step 3) and open it. Then, navigate to “Owners” and click the “Add” button to add the owner.
401 - “Could not find user”
When a user receives this error, it could mean several things:
1. The user does not exist in Declaree
To resolve this, create the user in Declaree.
2. The user’s details in Declaree are incorrect
If the user does have an account in Declaree, check their details and correct any typos. Make sure that their email address in Declaree matches their email address in Azure.
3. Incorrect “NameID format” or “Username (uuid)” Details in Declaree
The “NameID format” and “Username (uuid)” fields in Declaree (“Configuration” → “Single Sign-On”, tab “SAML”) are used to map the login details of the user. If this is configured incorrectly, Declaree is not able to match a user in Declaree with its counterpart in Azure.