OpenID Connect for Microsoft Entra ID (formerly Azure AD) with User Sync

Goal

After completing this setup guide, you will have set up Microsoft Entra ID (formerly Azure AD) and your Atlassian product for the SAML SSO app and also User Sync, using the OpenID Connect protocol. Additionally, you will enable test the SSO.

Prerequisites

To use the SAML SSO app with Microsoft Entra ID (formerly Azure AD), you need the following:

  • An Microsoft Entra ID (formerly Azure AD) subscription

  • A (trial) subscription for the SAML SSO app

  • Admin access to your Atlassian product

Video Guide



Step-by-Step Setup Guide


Install the SAML SSO App


In your Atlassian product, open the in-product marketplace as described in the Atlassian documentation.
Search for "resolution saml" and click "Install" for SAML Single Sign On (SSO) by resolution Reichert Network Solutions GmbH.


After the installation is complete, click Manage Apps/Addons



Install-25-loop.gif



Configure User Sync




Go to http://portal.azure.com and click the Microsoft Entra ID.

Microsoft Entra ID
Microsoft Entra ID


In the Microsoft Entra ID click App registrations.

app_registration
app_registration


Click New registration to create a new app.

new_registration
new_registration


Enter a name for your application and click on Register to proceed.

AAD3.png



Click API permissions in the left panel.

AAD4.png


Delete the default created permission since it's not needed.

AAD5.png


Click on Add a permission.

AAD6.png


Select Microsoft Graph.

AAD7.png



Choose Application permissions.

AAD8.png



Expand Directory and tick Directory.Read.All

AAD9.png



From SAML version 6.3.0 or User Sync 2.7.0 User Sync also supports syncing the profile pictures of users in Azure AD. To be able to use this feature, you additionally need to add User.Read.All as permission. 



image2023-1-12_16-12-24.png


Click on "Grant admin consent for ...".

image2023-1-16_17-8-13.png


It should look like this after granting admin consent:

image2023-1-16_17-10-59.png



For the next step, click on Certificates & secrets in the left panel, and then click on New client secret.

AAD13.png



Enter a description for the secret and also set an expiry date. Click on Add to confirm.

Please note that your secret will expire after 24 months. If syncs start failing in 24 months, you must create a new secret and update the secret in the connector.


AAD14.png



Your Client secret will display only once, thus copy the secret. Of course, it is possible to create a new secret, if you lost your secret.

Screenshot 2021-08-05 at 7.59.11 AM.png





Go overview page of the Microsoft Entra ID app. Copy the Application ID and the Directory (tenant ID). Now, it is time to head over to your Atlassian application.

AAD16.png



In your Atlassian application, go to User Sync,  click Create Connector, and choose Azure.

AAD17.png





Add the Application ID, Directory ID, and the Application secret. Use the Save and Test Connection button to check whether Azure's API endpoints are reachable and API permissions are set correctly.

Screenshot 2023-04-26 at 13.55.04.png



To take full advantage of User Sync, go to the Sync Settings tab and enable "Scheduled Synchronization". You can control the sync interval via a Cron Expression.
Do not forget to save your configuration by clicking on "Save and Return".

AAD19.png


You are now ready to commence either a simulated or a full sync. By simulating the sync first you will be able to verify your configuration and see what changes User Sync would apply like what users will be added, modified, or not modified. With the full sync, User Sync will apply those changes. Both sync actions will run a full sync and will have the same sync duration. For more information on the sync simulation, please refer to Using the Simulated Sync Feature.

image2023-8-31_13-0-56.png



Configure SAML SSO


For the next steps, please go to Manage apps (or addons), choose SAML SSO and click Configure.

First Steps - Wizard

After you clicked "Configure", the Wizard will be triggered. If not, or if you want to add another Identity Prover (IdP) to your existing configuration, click on "+ Add IdP". This guide assumes, that there is no IdP configured.
The Wizard greets you with information, click on "Add new IdP" to proceed.

welcome_wizard_add_newidp
welcome_wizard_add_newidp


Select Azure AD for your identity provider and select OpenID Connect for the authentication protocol. Enter a unique name and click Next to continue. 

1 choose idp.png

Copy the callback url to your favourite text editor. 
2 servlet link.png



Next, go to https://portal.azure.com

Then, click App registrations and click New registration.

1 add new app.png


Enter an app name and the copied oidc callback url into the Redirect URI
2 app name and url.png


After the creation of the app, copy the Application (client) ID and the Directory (tennant) ID into a texteditor of your choice.
3 copy things.png


Next, go to Certificates & secrets and click New client secret.
4 create secret.png

Set the expiry to your needs (we recommend 24 months) and click Add.
5 secret validity.png


Copy the secret value (but not the id) to your editor.
6 copy secret.png

Next, go to Token configuration and click Add optional claim.
7 claims.png

For the Token type, use ID. For the claim select UPN. Click Add.
8 create clai.png

If Azure asks for the Microsoft Graph profile permission, please do so. 
9 grant auth.png

If you have guest users in Azure AD who would also use SSO, then you would need to do the following:

Click on "..." for the upn claim, and click on Edit.

image2022-10-31_11-12-45.png

Then enable the Externally authenticated option, and click on Save.

image2022-10-31_11-15-0.png


Now, go back to your Atlassian application to finish the wizard. 

Enter the Client ID and Client Secret from before.
3 client id.png


Next, enter the Azure tennant ID from before and click the Import Metadata button.

4 azure tennant.png

You will see this message if the import was successful.
5 success.png


To finish the wizard, click Save and Close.

Screenshot 2021-12-08 at 11.06.14.png


Next, scroll down to the User Creation and Update section. Choose Update with UserSync for the User Update Method.
1 user update method.png

Select the connector you have created before and click Save.
2 connector.png


Testing SSO


To test you configuration, go to the System & Support section of the app and scroll down to the Tracker List.

1 System & Support.png

Click New Tracker. If you have more than one identity provider configured, you must choose which configuration should be used for the log in test.
2 tracker.png

Copy the test url and open the link an incognito web browser. If something goes wrong during the test, you can easily create a support ticket that includes this tracker by click Contact Support. Additionally, you can contact us by going to https://www.resolution.de/go/support or booking a free meeting via https://www.resolution.de/go/calendly.

3 Test.png


Redirect to SSO


After a successful test, the next step is to configure the redirection. With the redirection setting, the app can automatically redirect users to log in via OpenID Connect.

Go change this setting, go to Redirection from the middle panel.

By checking Enable SSO Redirect, users will get redirected to the configured SSO provider for login. If you are running JSM, you find a second option below. 

Click Save to finish the configuration
Screenshot 2022-01-11 at 13.22.40.png