Atlassian Access APIs and user provisioning

The access spaghetti

You’ve heard all the terms - SSO, SAML, user management, user provisioning, managed accounts, domain claims, and more. But what do they mean? How do they relate in the context of Atlassian Access? You have to understand this before getting into the weeds of using the APIs and building your own user provisioning tools.

Also, check out the references section at the bottom of the page.

Term	Definition
Organization	A container that brings together the users of Atlassian products in your company and the products that you manage. You typically have one. You may have more if you have other businesses/domains. Organizations only exist in managed accounts.
Site	A cloud site that sits under an organization. It consists of a number of products, for example, Jira and Confluence. New cloud sites would be created under their own organization, so an organization admin would need to transfer that site to an existing organization if they wish.
Domain claim	Proving you own your own domain and asserting your right to manage any user with that domain email address. You can claim multiple domains per organization. This is done at the organization level.
Managed accounts	Any users with email addresses belonging to a claimed domain. These accounts are managed at an organization level. These accounts give admins visibility into important things like the other sites the user belongs to and how many API tokens they have.
SSO	A capability that enables users to authenticate themselves via your corporate identity provider. This often means they are already authenticated if they have previously logged in to other internal applications. If not already authenticated, the user is redirected to your corporate login page when Atlassian recognizes the domain in their email. After authentication, the user is then granted the appropriate access in the cloud site. We currently support one identity provider configured per organization. SSO always applies to managed account users with matched claimed domains.
SAML 2.0	SAML 2.0 is the language protocol that facilitates the exchange of authentication and authorization information for SSO. Often used interchangeably with the term “SSO.” This is an open protocol, so any identity provider that supports it can integrate with Atlassian Access.
User provisioning	Managing managed users and groups from an external directory that is likely part of your identity provider. Atlassian Access currently supports Okta, Azure AD, OneLogin, Google Cloud, and PingFederate. There are pre-built integrations available for these identity management solutions. You can only provision a user from an external directory that is or will be a managed account, meaning they are using a claimed domain in their email address.
SCIM	This stands for System for Cross-domain Identity Management (SCIM). Another standard for enabling systems to share user identity information. SCIM is used for user provisioning, de-provisioning and syncing group memberships.

Organizations can control product access in two ways, individually and via groups. Each site grants default product access to new members, individually. Additionally, groups can grant additional product access permissions.

In other words, when you add a new member to your organization, they will receive certain product access depending on which site they belong to. If they need additional access, you can add them to a group that grants more product access.

Note: You will still need to define product access carefully for each site. It is possible to have users provisioned who cannot access anything.

This diagram provides a nice overview of the relationship between organizations and sites.

User provisioning — site vs. organization

Users and groups can be created at each site level. However, if your enterprise is running multiple sites under an organization, it makes more sense to provision the users and groups at the organization level from an external user directory you already have (e.g. Okta, Azure AD). You can then manage access and attributes from your own directory instead of in two places. Groups created via user provisioning are available for all sites to add as appropriate to product access/roles, whereas groups created at the site level only exist for that site.

Think of site-level user and group creation via API as simply automating what a site admin can do. These users may still become managed upon their first successful login if SSO is configured, but site admins will be able to activate/deactivate, update group attributes, etc.

So you want to manage access?

Atlassian Access provides you with centralized governance, security, and user management across all the sites you manage within your organization. However, most enterprises prefer to manage product access and user attributes using their own identity provider and existing user directories, instead of worrying about managing this in yet another tool. You may also want to automate provisioning and de-provisioning to Atlassian Cloud products as part of employee onboarding and termination.

The Access interface doesn't allow bulk operations. This is where APIs come in.

The APIs

There are three APIs for Access. You also have the option of adding users directly to sites via the Jira Cloud API (although if these users have a managed domain, they will become a managed account at the organization level on their first successful login). Each API is authenticated a little differently.

Keep your keys/tokens somewhere safe because you won’t see them again after the initial creation.

API Name	Authentication	Description (in user management context)
The organization API	Organization API key as a bearer token	Mostly GET operations for various organization attributes and audit log
The user management API	Organization API key as a bearer token	Management of user attributes, enabling or disabling users, and API tokens. Users are not created via this API.
The user provisioning API	SCIM API key as a bearer token	User and group provisioning from an external user directory
Jira Cloud API	User API token in basic authentication/OAuth	User creation and management at the site level, only available for Jira Confluence shares its own user base. Note: This will be deprecated when a more suitable alternative is available, so use it with caution.

Provisioning users via API

Two main API endpoints will get you started with provisioning a user from your external user directory to Access.

Fun fact - you will see your SCIM directory ID when when it's created.

After that, the only place to see it is the user provisioning interface:

Note: This is the default SCIM directory group to which all SCIM users will belong. This group can be provisioned product access like any other, however, if you wish to manage your users differently by role and/or product, you’ll need other groups created in your external user directory to sync across.

Create the user

POST https://api.atlassian.com/scim/directory/{directoryId}/Users
EXAMPLE BODY
{
  "userName": "testuser",
  "emails": [
    {
      "value": "testuser@test.com",
      "type": "work",
      "primary": true
    }
  ],
  "name": {
    "formatted": "Test User",
    "familyName": "User",
    "givenName": "Test"
  },
  "displayName": "Test User",
  "active": true
}

Your user will now appear under Managed Accounts, but will have no product access and won’t appear on any site user lists unless you have configured the default SCIM directory group to have product access.

Update group memberships for that user

You may need to do a call first to get the ID of the group you wish to update - it’s not the one shown in the URL of the group page.

PATCH https://api.atlassian.com/scim/directory/{directoryId}/Groups/{groupId}
EXAMPLE BODY
{
   "schemas":[
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
   ],
   "Operations":[
      {
         "op":"add",
         "path":"members",
         "value":[
            {
               "value":"{userId}",
               "display":"testuser@test.com"
            }
         ]
      }
   ]
}

Assuming you pushed the user’s group membership for a group that provides product access to a site, that user will now appear on the list of users for that site.

Tips & gotchas

When provisioning users into groups, create batch sizes smaller than 10,000 users. Batch sizes above 10,000 users will suspend any following sync to your directory.
If your SCIM group contains more than 20,000 users, Atlassian need to enable a feature flag to allow 35,000 users to sync to your group. Syncing more than 20,000 users into a group will suspend any following sync to your directory.
Some environments may also need to contact Okta for support, as there may be limitations that must be modified by Okta.

TIP Groups with the same name as default access groups (for example, jira-software-users) can’t be pushed to Access. Create your own site or product-specific “default” groups in the external directory, sync those over, and then set up the appropriate product access rules for those groups in the appropriate sites.
TIP After syncing your users and verifying they have the right access, you may want to remove those users from the default access groups if you wish your identity provider to be the source of truth for authorization.
GOTCHA Updating the email address for a SCIM user can only be performed via the user provisioning API and not the user management API (though both have the same method available). If a user has been created using the user provisioning API, then it is expected that all changes for that user will originate from there as well.
GOTCHA User attributes can be synced via SSO or the user provisioning API, so be careful that the external directories sources for both are synced (particularly if the SSO provider isn’t the same as the identity provider).
GOTCHA Site roles can’t be managed via API (yet). The default is “Basic”. The different roles are:
- Basic — Can access specified products and apps. No additional permissions. Equivalent to adding this user to the default product access groups.
- Trusted — Can access, configure, and add products. Can invite users. No group level equivalent.
- Site administrator — Full admin permission for the site. Equivalent to adding this user to the “site-admins” group.
TIP As part of user de-provisioning, deactivate all the API tokens that belong to the user. The tokens cannot be used after they are deactivated, but if the user was reactivated, their tokens would work as they did before. It's up to the organization’s security team to determine how to manage this, but deactivating the tokens along with the user when they leave the organization is generally good housekeeping. This can be done per user or from the API as part of a de-provisioning script.
TIP Deactivating provisioned managed accounts will deactivate that user for every site they belong to. The API endpoint to do this is readily available (The user provisioning REST API) but reactivation is not as obvious. You’ll need to update that user’s attributes and set the “active” flag back to “true” (The user provisioning REST API).
TIP Exemptions from the SSO policy are not (yet) available. It's best practice to have an alternative “backdoor” non-provisioned, non-managed user in the event your SSO provider has an outage, thereby shutting access off to all domain users, including admins. At this stage, having a non-domain org admin account that is only allowed to be accessed during emergencies is the best solution to mitigate this risk.

References

Was this content helpful?

Connect, share, or get additional help

Atlassian Community