Avoiding pitfalls when integrating Atlassian Access

Integrating Jira Cloud with identity providers through Atlassian Access can be tricky. In this blog post, we'll cover how to avoid pitfalls concerning mapping user attributes and claiming your domain.

Integrating Atlassian Access

One of the many things you can do to get the most out of your Atlassian tools is to integrate your Jira user directory with your local organization directory. The benefits of having a single “source of truth” regarding your users and their attributes are many, and regardless of which identity provider you normally use, it's all handled through Atlassian Access.

How Atlassian accounts work

Of the many benefits, there’s SAML single sign-on (SSO), automatic user provisioning, and the enforcement of two-factor authentication (2FA).

Good to know: For Bitbucket, you need Premium to enforce 2FA. Group and user synchronizing is also not supported, and the same goes for Trello, but it’s still listed because SSO works.

Before we get ahead of ourselves, we need to get the systems to communicate with each other, which brings us to our first obstacle—claiming a domain through Atlassian.

Claiming a domain to enable Atlassian Access

Before enabling Atlassian Access, you need to claim the desired domain. Essentially, this means telling Atlassian that you own the domain, for example, “@companyname.com,” and that you would like to manage associated Atlassian accounts.

Tip: You need the domain (web URL, verify file, or DNS record).

Accounts can be used across multiple Atlassian products, and ownership falls somewhere between users and Atlassian. Organizations can’t do much here, but claiming accounts allows you to manage and modify them by, for example, setting new attributes on the accounts or making other changes as needed.

The downside to this is that it can only be done by a single organization. You cannot claim the same domain across multiple. We often see organizations trying to claim their domain only to realize that a sister department has already done so.

In such circumstances, we recommend opening up a dialogue with your sister organization’s Jira administrators and Atlassian to confirm it makes sense to move everything to one single organization, so you can handle and manage your identity provider from one location.

Atlassian Access is billed when a managed account has one of the following supported products:

• Jira Software
• Jira Work Management
• Jira Service Management (agents)
• Confluence
• Bitbucket (no license provisioning)
• Trello (no license provisioning)

It’s important to note that Trello counts as an active use of Atlassian products even if you are on the free version, which can be confusing.

As previously mentioned, both Trello and Bitbucket only support the SSO part of Access, so you cannot provision licenses to users like you would on other products.

One organization can use a single Access setup even if they have multiple sites. Only one Access license is consumed per active Atlassian user, no matter how many products or sites they have.

Good to know: If you have an Enterprise licensing tier for Jira Software, it works in much the same way, where one license covers all instances in the organization.

Below is an example of how Enterprise and Trello licenses can affect Atlassian Access.

Here, we can see that 8,000 users already have an Enterprise license, which includes Access, meaning licenses for the 2,000 Trello users who do not already have an Enterprise license need to be paid for.

Setting up and enforcing SAML single sign-on (SSO)

Usually, the next step would be to set up SSO. If you do not need this, you can skip directly to user provisioning, but it’s still good to understand what this means.

A lot of people confuse the enforcement of verifying SSO through Access and their identity provider with the ability to quickly log in through Microsoft or Google, for example, if they’re already logged in to Jira.

You’ve probably noticed that even without Access, you have the option of choosing to log in with one of the above-mentioned portals. The key word here is “option.”

An account without Atlassian Access configured—remember authentication policies—is not forced to verify through an identity provider and can log in directly to Jira using an account email/name and password. Once SSO is set up and enforced, you’ll always be redirected to your identity provider login page.

Make sure to test this on a small number of users before you lock everyone out of the system, and be extra careful with policies impacting admin accounts as well as your own.

Provisioning Atlassian Access users correctly

Access-enabled Atlassian products should be automated via your identity provider. Once you’ve done the initial configuration, Access can handle both the on and off-boarding of users together with your internal system.

Group memberships can also be handled the same way, but note that nested groups will be flattened on the Atlassian side. Make sure to confirm internally what this will impact.

Since user groups define application use and licenses, you can control licensing directly from your identity provider for Jira and Confluence by simply synchronizing the corresponding groups. Bear in mind that some of the internal system groups in your Atlassian organization, like site admins, cannot be synchronized this way.

Remember: Group synchronization, which would give access and licenses for Bitbucket/Trello, is not possible.

Deleting users in Atlassian Cloud can be a time-consuming affair, so be careful with what groups and users you add to the directory you’d like to synchronize. If you synchronize too many groups or users, we recommend cleaning up using the BulkOps app or an alternative, e.g., REST API.

Enforced two-step verification with Atlassian Access

After setting up Access, you can enable 2FA. This works for Jira and Confluence but not for Bitbucket, as previously mentioned. If you’re already enforcing SSO, however, the easiest way is usually to do so on the identity provider level outside of Atlassian, which will also work with Bitbucket since it’s enforced in the login. This keeps the login experience consistent across systems and makes it easier for users to understand how to authenticate.

When you enforce SSO, you have control over your identity provider. Here, you can enable conditional use, enforce a local network/IP range, and more.

Without Access, you can also set up a single authentication policy where you can enforce 2FA, password security strength, and idle session time. You can also claim domains and manage accounts since none of this requires Access.

Attribute mapping and your identity provider

When mapping attributes, make sure that the values in your identity provider are correct and up to date and that you’re mapping the correct fields.

Available to map:

• Display name
• Email address
• Organization
• Job title
• Timezone
• Department
• Preferred language

Good to know: The display name is a combination of the user’s first and last name. If you update this, it overwrites attributes.

A noteworthy pitfall is an organization that had Atlassian users from across the globe. Not all of them wanted to display their first name in Jira, where they normally used their family name or similar.

In such circumstances, you may have to set up multiple connections with your identity provider, each with its own attribute mapping. This would require Atlassian Cloud Enterprise, as you would otherwise only be able to use a single identity provider configuration. This can be very costly but adds new features and is usually an important step for organizations growing globally.

Getting started with Atlassian Access

It can be daunting setting up Access, SSO, user provisioning, etc., for the first time. Clicking the “claim accounts” button once you’ve verified your domain may seem like a big decision, but it will have very little impact on your users.

It usually takes us half a day to configure Atlassian Access, and that really is all you need if you understand your identity provider correctly and how you want to synchronize/provision users.

We see a lot of organizations augment the Access integration with their own onboarding portal or platform. The idea is to have a single place to grant access to products and items within your organization and automate the entire process.

Make sure you have the knowledge, resources, and time before you embark on such a task. Understanding your organization's culture will help you see what your portal/platform will look like and how it should function.

New options and possibilities are added by Atlassian every day; it might be a small thing that makes all of the difference to your organization. Get started, and don’t be afraid to make mistakes!

To learn more about Atlassian Access, check out our blog post.