Integrate Azure AD with Atlassian Cloud

[Rachel Coles]

Current setup:

We have a Azure environment and want to have SSO using our Azure AD for Jira and Confluence hence wanting to use the Atlassian Access application.

But...

Currently we sign into Jira and Confluence Cloud using our Gmail accounts which we are using for our email services (will be migrating to Exchange Online), but they are the same as the credentials for Azure. We are in the process of slowly migrating away from Google Workspace to a full Microsoft environment. 

My question is?
Once we setup Atlassian Cloud/Access with Azure AD. When it syncs the user data will there be a conflict because the user login's are already in Atlassian because of Google? Will it delete all the user accounts and replace them with Azure AD users and would we have to setup all the permissions again and what about Admin access in Atlassian, will we lose this. will we have to create a new Atlassian admin account in Azure to cover this? 

Some some questions:
Does it sync groups and can you specify what groups from Azure and if you add members to the to the groups does this then get sync'd later? 
Can we then assign rights to the groups in Atlassian to stop having to assign rights to individual users.  

Hope this is understandable 

[João Nunes]

Hi, Rachel.

I hope you and your family are safe and well. 

Based on your description, the email at Google Workspace and Azure will be the same, is that correct? 

It is also important to mention that we have two different integrations you can do with Azure:
- SAML SSO : changes how the users authenticate to Atlassian and sync some of the accounts details such as email, name, and last name.
- User Provisioning : sync users and groups from your Identity Provider to your Organization and the sites below it

Now, to your questions:

1. Once we setup Atlassian Cloud/Access with Azure AD. When it syncs the user data will there be a conflict because the user login's are already in Atlassian because of Google?
   
   If you are already connected to G Suite/Google Workspace through our sync then you will need first to remove it then proceed with the Azure AD sync. But once you get Azure configured, if the email address coming from the AD matches the email at our side, no conflict should happen. 
   
   Side note: each integration (SAML SSO and User Provisioning) have its own attribute mappings. For example, for SSO we expect to receive the email address information in the NameID mapping attribute whereas for User Provisioning that should be synced in the emails[type eq "work"].value.
   
   
2. Will it delete all the user accounts and replace them with Azure AD users and would we have to setup all the permissions again and what about Admin access in Atlassian, will we lose this. will we have to create a new Atlassian admin account in Azure to cover this?
   
   No account will be deleted in this process. What will happen is that when Azure send the user to us, either through SSO or the User Provisioning integration, we will try to find an existing Atlassian Account with that same email, if we find it then a link will be created between the AD account and the Atlassian Account. If we don't then a new account is created: for SSO the user will be asked if they want to create a new account whereas for user provisioning, it will be created automatically.
   
   
3. Does it sync groups and can you specify what groups from Azure and if you add members to the to the groups does this then get sync'd later?
   
   The group syncing is possible through the User Provisioning integration and not through SSO. You can sync specific groups and members added to it will be synced based in Azure's sync cycle (once every 40 to 60 minutes). Check this Microsoft doc for more details.
   
   
4. Can we then assign rights to the groups in Atlassian to stop having to assign rights to individual users.
   
   This is one of the advantages of using User Provisioning integration: the groups you synced through it can be assigned to product access, project and space permissions.
   
   The limitation is that you can't sync groups with the same name as the DEFAULT ACCESS GROUP (e.g. jira-users, confluence-users) and synced used won't be added to those by default, therefore, to grant the users that same access level you will need to manually add the synced groups to the product access, projects and spaces permissions. 
   
   On the other hand, we have a public feature request to make that sync to the default groups possible in the future:
   - Grant users synced from identity providers via SCIM application access by default 

I hope this clarifies your questions. 

Let me know if you have any additional one. 

João Nunes 

Atlassian Cloud Support 

[Rachel Coles]

Hi João,

Thank you for the detailed reply and information.

I've done reading around both the SSO and User Provisioning (Microsoft documentation) and it seems we can setup SAML SSO first and then do the User Provisioning setup afterwards so as to get the benefits of SSO and User Provisioning. I appreciate the mapping of the attributes for SSO and User Provisioning is different.

 "If you have previously setup Atlassian Cloud for SSO you can use the same application. However it is recommended that you create a separate app when testing out the integration initially." - Taken from Microsoft documentation around User Provisioning.

https://docs.microsoft.com/en-us/azure/active-directory/saas-apps/atlassian-cloud-provisioning-tutorial?source=docs

As we are trying to make the authentication as secure as possible for all users but at the same time make management of users simpler via Azure so hopefully we can incorporate both SAML SSO and User Provisioning as it seems to allow it. 

If you think this will not not work your feedback will be helpful 

Regards

Rachel

[Ed Letifov _TechTime - New Zealand_]

This will work but this is a mistake.

Groups you assign to the Atlassian Cloud application in Azure affect BOTH who are allowed to sign-in and who is provisioned. You'd think these should always be the same, but in real enterprise scenarios this is not always true.

If you have a security breach associated with one of the users – you'd want to lock them out immediately, but you will want to keep their product groups intact, so you can investigate i.e. to identify what they could have possibly have access to.

[Ed Letifov _TechTime - New Zealand_]

Please review these threads also, these might help:

https://community.atlassian.com/t5/Confluence-questions/What-is-the-difference-between-site-access-and-product-access/qaq-p/1306257#M221166

https://community.atlassian.com/t5/Jira-Service-Management/Azure-AD-login-and-incoming-email-not-matching-up/qaq-p/1821809#M88619

[Ed Letifov _TechTime - New Zealand_]

This is what I share with our customers:

Here are our recommendations on how to configure Cloud site and Atlassian Access integrated with Azure AD.

1) A lot of features in Cloud User Management, and access setup are aiming to make it easier for non-enterprise users to set everything up. 

In the presence of Atlassian Access provisioning a lot of these features are actually make it harder to manage everything from Azure AD.

As such it is recommended to tighten up the setup of Atlassian Cloud site as much as possible, so, at least for the regular users, the control over who gets access to what is fully on the side of Azure AD.

• Cloud site can list domains in Site Access, so users from these are pre-approved to just join the site on a whim by clicking a link and wandering in. This should be disabled – so the only way someone is allowed to be on the site is by being provisioned from Azure AD via User Provisioning in Atlassian Access
• It's impossible to stop site-admins from inviting users directly, but it can be tightened up: when a user is invited or joins the site they automatically get access to products that have "New users have access to this product" checked in Product Access. These checkboxes should be unchecked for all applications, so nobody gets any acess unless it comes from Azure AD via User Provisioning in Atlassian Access
• Product Access must have at least one default group, these are the groups that a user is assigned when the site admin ticks a checkbox to give access to a product or when they get a default product: this needs to be disabled. A dummy "local" group should be created – we usually call it "default-do-not-use". This group should be added to all applications in Product Access, made to be the default one, and any other default groups should be stopped from being default.
• In Product Access, except for site-admins and administrators – all groups that give access to products should be coming from Azure AD via User Provisioning in Atlassian Access
• In Product Admin Access, except for site-admins and administrators – all groups that give access to products should be coming from Azure AD via User Provisioning in Atlassian Access
• Inside the actual products e.g. Jira – access should be keyed to groups coming from Azure AD via User Provisioning in Atlassian Access. When we do Cloud Migrations we re-key application data e.g. from jira-administrators being used everywhere to the group name coming from Azure AD.
• "Local" Cloud groups e.g. site-admins and administrators should be used as little as possible, e.g., in Global permissions only.

All of the above ensures that users can only get access via Azure AD. Once a user is provisioned, with some groups listed in Product Access, they are given site access. When they are deprovisoined they lose access.

A site admin can elevate someone else to a site-admin or administrators level – but this will only allow you to administer site or get into administrators section of the product e.g. to review how setup is done. 

2) We recommend having two instances of "Atlassian Cloud" Enterprise application in Azure AD – one solely responsible for SSO and the other solely for User Provisioning.

• It is recommended to configure SSO via Azure AD to be based on a group or set of groups distinct from the product groups used in provisioning, i.e. "authentication-only" group(s) assigned to the Atlassian Cloud Enterprise application in Azure AD that is responsible for SSO only, and "authorization-only" groups(s) assigned to the Atlassian Cloud Enterprise application in Azure AD that is responsible for User Provisioning only. Thus in Azure AD you would require a user to be a member of at least two groups – the access one and the product one.

Mainly this is from the desire to separate concerns, e.g., during a security breach investigation – deny someone SSO, effectively locking them out from Atlassian Cloud (temporarily), while not touching their provisioned user and the groups associated with that. If the groups used for provisioning are directly assigned to to the application responsible for SSO – removing the user from a group trying to deny them SSO will trigger deactivation of the user via User Provisioning.

The need for two applications in Azure stems from this too – since for a single application the assigned groups apply to both SSO and User Provisioning.

If you ever start running Jira Service Management – you will need to be able to give access to Cloud without giving access to products for Portal Only users.

3) SSO to Atlassian Cloud is Cloud-wide – it encompasses users outside of your single site, e.g. users from your own other sites, Bitbucket and Trello users, as well as users who require access to other Atlassian Cloud services, e.g. University or Community.

• It is recommended to have two groups in Azure to clearly track these: one for Trello users, one for Other users (as in "other Atlassian services"). These groups should be used in User Provisioning.
• in case you ever start running another site and you'd want to explicitly give access to site1 but not to site2 all other Product access groups used in User Provisioning should have the site name in the name of the group

4) Both User Provisioning and SSO sides of configuration in Azure AD need to be reviewed due to the fact that Atlassian uses email of the user for everything:

For the app responsible for SSO in Azure AD:

• what is pushed into "name" attribute is absolutely irrelevant, might as well be the UPN to match the meaning a username in AAD
• user's email (wherever it is stored in AAD) MUST be pushed to the Cloud's email attribute
• "Unique User Identifier" in the SSO mappings has meaning "... in Atlassian Cloud" and MUST always be the email of the user.

For the app responsible for User Provisioning in Azure AD:

• what is pushed into "username" attribute is absolutely irrelevant, might as well be the UPN to match the meaning a username in AAD
• user's email (wherever it is stored in AAD) MUST be pushed to the Cloud's email attribute
• AAD objectId MUST be pushed as Cloud's externalId, and it MUST be selected as the one used for user record matching ("Matching Precedence" = 1) – this will allow you to change the UPN, or email at will but keep Cloud in sync
• any groups assigned to the app responsible for SSO in Azure AD MUST be included in the list of groups assigned to the app responsible for User Provisioning in Azure AD (as otherwise you'd have to rely on product access groups to actually have the user provisioned or won't be able to lock a user out temporarily by removing them from a group giving them SSO without triggering deactivation via User Provisioning)

5) A new user created in Azure AD or a user after rename/change of email or/and UPN should wait for the provisioning to push the changes to Cloud (Azure AD does it only every 40 minutes)

6) For traceability,  admins in Atlassian Cloud should never trigger deletion of a previously active real user in Atlassian Admin UI – only deactivate.

Deleting a user in Azure AD or removing them from all groups assigned to the app responsible for User Provisioning in Azure AD will automatically trigger deactivation on Atlassian Cloud side, not delete.

7) To avoid being locked out if SSO is malfunctioning, it is recommended to have at least one org-admin and site-admin account from another domain, e.g., if we are supporting you in the Cloud – one of techtime accounts. They are all attached to real users, with Atlassian's own 2FA and strong passwords enforced. We use aliasing to avoid logging into one customer and accidentally changing something for another customer.

Creating a special "break glass" account in your own domain and assigning it to no-SSO policy in Atlassian Access is not recommended as this effectively circumvents the very security controls you are trying to implement with SSO via Azure AD.

[Rachel Coles]

Hi Ed,

Thank you for detailing it and making it very easy to follow. I appreciate the help and I will be taking your advice and implementing it as you recommend.

It's made things a lot easier now as I now understand the difference between SSO and User Provisioning for Atlassian/Azure.

Rachel      

[Sean Thorburn]

Hi Ed,

I second Rachel Coles appreciation!  It's been about a year since your shared your recommendations for configuring Cloud site and Atlassian Access integrated with Azure AD.  We are about to implement the same integration.

Are there any updates or new considerations you would make today?

Sean

[Ed Letifov _TechTime - New Zealand_]

Hi, @Sean Thorburn I do not think anything has changed.

[Rachel Coles]

Hi All,

Here are my steps I will be doing to integrate Atlassian with Azure AD
Please check to make sure I'm going it in the right order and correctly before I implement it

Step 1

• Make sure the domain is verified in Atlassian
  Atlassian Organizations and Domain Verification | Atlassian - Checked and Done

Step 2

• Cloud site can list domains in Site Access - via Atlassian Admin Console (should be off by default)
  Stop users from just accessing the site without been provisioned in Azure AD first via been in the Provisioning Group(s)
• New users have access to this product - via Atlassian Admin Console (Site Access - Invite Links) - All checkboxes should be unchecked for all applications
• Create a ‘dummy local group' called ‘default-do-not-use’ - via Atlassian Admin Console (Site access - access requests) and added to all applications in Product Access and made the default group.
  Product Access needs one default group which normally all users are added to within applications - needs to be disabled, hence creating the dummy group and making it the default of all applications.
• Product Access - all groups that give access to products should come from Azure AD (User Provisioning), except for Site Admins and Administrators
• Product Admin Access - all groups that give access to products should come from Azure AD (User Provisioning), except for Site Admins and Administrators

Step 3
Create groups in Azure AD

• Create ‘Authentication Only Group(s)' in Azure AD just for SSO that is assigned to the Azure Atlassian Application responsible for SSO
• Create ‘Authorization Only Group(s)' in Azure AD just for User Provisioning that is assigned to the Azure Atlassian Application responsible for User Provisioning
  Users will be therefore be members of two groups within Azure, access and product
• Create Azure Administrator group(s) - re-key application data from e.g. Jira Administrator to groups from within Azure AD

Step 4

• Create instances of ‘Atlassian Cloud’ Enterprise Application in Azure AD
  Responsible for SSO only

Step 5

Attribute matching between Atlassian and Azure for SSO:

Atlassian attribute	Azure AD attribute	Comments
name	UPN or anything	Can be anything but recommended to use UPN to match Username in Azure AD
email	email address	Must be the users email address in Azure AD
Unique User Identifier	email address	Must be the users email address in Azure AD

Testing SSO with Atlassian and Microsoft:

• Create Azure AD test user (recommended by Microsoft) or use existing user
• Assign the test user to Atlassian Cloud app (under manage users/groups)
• Create Atlassian test user - link this to the test Azure test user
• Test SSO - (can be done via Azure in test this application)
  SP (Service Provider) initiated or IDP initiated (3rd party Identity Provider)
  You can also use Microsoft My Apps to test the application in any mode. When you click the Atlassian Cloud tile in the My Apps, if configured in SP mode you would be redirected to the application sign on page for initiating the login flow and if configured in IDP mode, you should be automatically signed in to the Atlassian Cloud for which you set up the SSO

Step 6

• Create instances of ‘Atlassian Cloud’ Enterprise Application in Azure AD
  Responsible for User Provisioning only

Step 7

Attribute matching between Atlassian and Azure for User Provisioning:

Atlassian attribute	Azure AD attribute	Comments
username	UPN or anything	Can be anything but recommended to use UPN to match Username in Azure AD
email	email address	Must be the users email address in Azure AD
externalId	objectId	MUST be selected as the one used for user record matching ("Matching Precedence" = 1) – this will allow you to change the UPN, or email at will but keep Cloud in sync

[Damjan Lukežič]

Hi

We are on a similar path, ie moving grom Gsuite to Azure AD users, so i will follow this thread closely.