Skip to main content
Skip table of contents

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”.

1. All services.png

Next, type “subscriptions” into the search box and click “Subscriptions”.

0. Subscriptions.png

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”.

1. All services.png

Next, type “enterprise” into the search box and click “Enterprise applications”.

2. Enterprise applications.png

On the “Enterprise applications | All applications” page, click the “New application” button.

3. New application.png

You will now arrive in the “Microsoft Entra Gallery”. However, instead of searching for an existing application, click “Create your own application”.

4. Create your own application.png

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”.

5. Non-gallery application.png

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”.

6. Users and groups.png

Next, click the “Add user/group” button.

7. Add user-group.png

On the “Add Assignment” page, click “None selected”.

8. Add Assignment.png

Another panel will open on the right side of the screen. Select the users you wish to add and click “Select”.

8.5 Select.png

To finalize, click “Assign”.

9. Assign.png

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”.

10. Single sign-on.png

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.

11. Basic SAML Configuration.png

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”.

12. Basic SAML Configuration - pt.2.png

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”.

13. Test single sign-on with Declaree.png

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.

14.1 Test single sign-on with Declaree - pt.2.png

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

14.2 Test single sign-on with Declaree - pt.2.png

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:

  1. In the Azure Portal, scroll down to step 5 and click “Test”

  2. 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.

15.1 Owners.png

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.