Configure OAuth 2.0 to enable SCIM authentication

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 credentials allows applications to access resources like Jira on behalf of a service account securely and with permission, without using passwords.Understand service accountsto learn more.

Set up the SCIM authentication in order to use public-facing SCIM APIs.

Set up SCIM authentication

To set up SCIM authentication, you first need to set up a service account and configure OAuth 2.0.

Step 1: Create a service account and OAuth 2.0 credentials

You need to be an Atlassian org admin to perform this step.

To create a service account:

1. Go to Atlassian Administration. Select your organization if you have more than one.

2. Select Directory > Service accounts.

3. Enter a name and optionally a description for the service account, then select Next.

4. Select User Access Admin role for one of the apps.

5. Select Create.

Continue from here to create your OAuth credentials:

1. Select Create credentials.

2. Select Oauth 2.0, then select Next.

3. Enter a name for your OAuth 2.0 credentials, then select Next.

4. Under Select scopes, filter by App: Atlassian.

5. Select the Atlassian app with scope name read:account. This is a temporary placeholder scope until we provide manage:directory scope.

6. Review and select Create.

7. Copy and save the Client ID from the created OAuth credentials, then select Done.

Step 2: Create a SCIM directory in Atlassian administration

You need to be an Atlassian org admin to perform this step.

To create a SCIM directory:

1. Go to Atlassian Administration. Select your organization if you have more than one.

2. Go to Security > User security > Identity providers.

3. Choose Other provider.

4. Add the directory name apple_directory, then select Add.

5. Select Set up user provisioning.

6. Copy SCIM Base URL and select Next.

7. Select Stop and save SCIM configuration.

Steps 3: Provision an OAuth 2.0 client and create a grant

We provision the OAuth client for you, then we create a grant (role assignment) for you. Contact your Enterprise account representative, and provide us with the following information:

1. From the previous steps:

   1. Service account ID

   2. OAuth Client ID

   3. Directory ID

2. From Apple:

   1. Public key or JWKS URL (https://appleid.apple.com/auth/keys) with a kid.

We’ll let you know when we complete this step.

Use public-facing SCIM APIs

To use public-facing SCIM APIs, you first need to generate an access token. Generate an internal token signed with a private key, and exchange it with a short-lived Atlassian access token.

Step 1: Exchange internal token with Atlassian access token

1. Generate a "client_assertion" token:

   { "header" : { "alg" : "RS256", "kid" : "${configured_key_id}" }, "payload" : { "exp" : 1765575427, // This would conventionally be set to https://auth.atlasssian.com, // but will be different for Oasis "aud" : "${OASIS_AUTH_SERVER_CNAME}", "iss" : "${client_id}", "sub" : "${client_id}" }, "signature" : "..." }

2. Execute client_credentials grant flow:

   POST /oauth/token host: ${OASIS_AUTH_SERVER_CNAME} content-type: application/json { "client_id": ${client_id}, "grant_type": "client_credentials", "scope": "manage:directory", "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": ${SIGNED_JWT} }

3. Receive access token:

   HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Content-Length: 1687 Connection: close { "access_token": "$ACCESS_TOKEN", "expires_in": 3600, "token_type": "Bearer", "scope": "manage:directory" }

Step 2: Call public-facing SCIM APIs

Using the access_token generated in previous step for authentication, call the Create a user API to create a user.