SCIM User Provisioning for Atlassian Bitbucket

This add-on (plugin) provides SCIM server functionality with multiple IdP support that allows securely automate the exchange of user identity data between your IDPs and Atlassian Bitbucket according to the SCIM specification v.2 or v.1.1. Thus, this gives you the ability to easily synchronize your user and group accounts from different IDPs such as OneLogin, OKTA, Azure, etc.

1. Plugin Installation

Log into your Bitbucket instance as an admin.
Click the admin dropdown and choose Atlassian Marketplace. The Manage apps screen loads.

Locate SCIM User Provisioning for Bitbucket via search. The appropriate app version appears in the search results.
Click Free Trial to begin a new trial or Buy now to purchase a license for SCIM User Provisioning for Bitbucket. You're prompted to log into MyAtlassian. SCIM User Provisioning for Bitbucket begins to download.

Enter your information and click Generate license when redirected to MyAtlassian.
Click Apply license. If you're using an older version of UPM, you can copy and paste the license into your Bitbucket instance.

2. Plugin Setup

2.1. Quick setup

As an overview, we will show how you can quickly create a new SCIM configuration and get the parameters to configure your IDP connection.

Open the plugin Configuration page, navigate to the New Configuration tab and specify the values as shown below, then click Generate token.

Navigate to the General tab. Existing Configurations. Here in the table Existing Configurations we can see a new entry with the configuration parameters we specified.

Your IDP will need SCIM v2 URL (or possible v1) and Bearer Token to set up a connection. You can also test the SСIM API as described in p. 4.

Note that the SСIM v1/v2 URL values here are relative to the server with the Bitbucket instance, as if the SCIM client (IDP) is on the same server. So, the actual URL that you need to specify in the IDP will differ and depends on your network configuration and settings.

2.2. Advanced Setup

Let's look at the configuration options in more detail. Please navigate to the New Configuration tab again. Here we specify the parameters for creating a new configuration, which determine whether a new Bitbucket internal directory will be created, the authentication method, the method for deactivating users and the ability to assign users to groups by default when a new user is registered.

User Directory - by default you can select any Bitbucket internal 'User Directory' or create a new one for user provisioning (Create new user directory option).
Directory Name - specify the name of the directory to be created.
Username that will be used for BASIC Auth - optional parameter. The name of an existing Bitbucket user if you select the HTTP Basic authentication access control method. By default, if no username is specified, the OAuth2 Bearer Token (which acts as the authentication of the API request) method will be used.
Delete users - If you select 'Yes' users will be completely deleted from Bitbucket on delete operation. If you select 'No' users will be only disabled.
Default Group(s) - a comma-separated list of groups that users will be added to when they are created through the provisioning process.
Application Group(s) - there are three Bitbucket applications: Bitbucket Core, Bitbucket Software and Bitbucket Service Desk. Each of these applications allows users to create and use specific project types. Determine which applications the user will be associated with by default.

The created configurations are displayed on the General tab:

To set up a connection on the SСIM client/IDP side, you will need to specify the OAuth2 Bearer Token or Basic Auth (username and password) and the real URL corresponding to the value of the SCIM v2/v1 field.

3. Plugin Features

3.1. Utils for Existing Users/Directories

The plugin's internal logic of working with data is based on the automatic building of mapping for existing app users, groups and memberships with bindings to the corresponding directories. Mappings are stored in so-called SСIM tables. During the plugin regular operation, synchronization of SСIM tables is performed automatically. But, sometimes, you need manually sync data. For example, when you just installed a plugin, and you need perform an initial synchronization with users, groups, memberships and directories of the application. This operation does not affect the application data but only supplements the information in the SСIM tables with missing data.

Navigate to Utils for Existing Users/Directories tab.

Build mapping for existing users, groups and memberships section.

Sync Users & Groups button (optional) - synchronize local users and groups for SCIM API. Initiates asynchronous execution of a background synchronization task on the server. As a result, SCIM tables data about users and groups will match application data.
Show statistics… - expand the block of information with the statistics of the last synchronization. During the execution of the background synchronization task, the information updates dynamically.

Remove/Reset Users Data section.

User Directory drop-down menu - select a directory for further actions.
Remove Directory button - all users and groups of the selected directory in the application and SСIM tables will be deleted. Be careful, this operation is irreversible.
Clear All datа from SCIM Tables button - all users and groups of the selected directory in the SСIM tables will be deleted. However, if you then perform Sync Users & Groups, the data will be restored using information from the app. Note that the users and groups IDs will be changed (regenerated) in SCIM tables.

3.2. SCIM Customization

Navigate to SCIM Customization tab, Users last login info section.

Here you can enable the mode of displaying information about the user’s last login in responses to Get /Users requests. Information will be represented in the meta.lastLogin attribute and also according to User Enterprise Schema Extension (One Identity version).

Sync Users last login info button - is intended for initial synchronization the users last login info between the application data and the SCIM table. Further synchronization is performed automatically.

4. Plugin Health Check

Plugin health check can be performed by sending requests in accordance with the SCIM API spec. Let's consider examples of sending a GET request to the /Users endpoint (SCIM 2.0) in several ways.

4.1. Windows PowerShell

Hit the Windows+R to open the Run dialog box and type PowerShell in the text box. You may either hit "OK" or "Enter" to launch a regular PowerShell window. Copy the following code into PowerShell, after specifying your values for the $token and $url parameters:

$url="https://bitbucket.test.luxplugins.com:7990/bitbucket/rest/user-provisioning/1.0/scim/v2/Users"
$token="xxxxxxxxxxxxxxxxxxxxxxxxxxx"
$headers = @{
   "Accept"="application/json"
   "Authorization"="Bearer $token"
}
Invoke-RestMethod -Method Get -Uri $url -Headers $headers | ConvertTo-Json

Press Enter and analyze the result, for example:

 {
    "schemas":  [
                    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
                ],
    "totalResults":  0,
    "startIndex":  0,
    "Resources":  [
                  ]
}

This is the correct response (no users in Directory yet). You can also direct the output to a file with an additional option on the command line as shown below:

Invoke-RestMethod -Method Get -Uri $url -Headers $headers | ConvertTo-Json | Out-File -FilePath .\response.txt

4.2. cURL

The curl utility can be used on various operating systems. Let's take Linux Ubuntu as an example. If curl is not already installed in your Linux system:

Sending a request, Linux (with beautifying response JSON):

Sending a request, Windows:

where xxxxxxxxxxxxxxxxxxxx is your bearer token.

4.3. PostMan

Postman is an API platform for building, using and testing APIs. With a rich GUI, Postman simplifies your work. Let's see how we can create our request.

You can create a new request from a workspace, by using New > HTTP, or by selecting + to open a new tab.

Select Save to create your request. You can give your request a name and description, and choose or create a collection to save it in. Once your new tab is open, you can specify the details you need for your request:

Save your OAuth Bearer Token:

Click Send Button. Analyze the response:

5. Troubleshooting

5.1. Enabling debug logging via the UI

Sometimes our support team may ask you to enable some additional logging when troubleshooting a specific problem. You need System Administrator global permissions to do this.

To enable debug logging:

Go to the Logging and Profiling in the left-hand menu.
Select Enable debug logging.

Note that any changes you make here are not persisted across server restarts.

5.2. Enabling debug logging on startup

To enable debug logging whenever Bitbucket. is started, edit the <Bitbucket home directory>/shared/bitbucket.properties file (if this file doesn't exist then you should create it) and add these two lines:

If your instance is earlier than version 3.2, the bitbucket.properties file is at the top level of your home directory.

5.3. SCIM Audit Log

You can easily check API requests history from the Bitbucket admin page (Audit Log menu item in the SCIM section of the left-hand menu). By default, recording the history of incoming requests to the log is disabled. You can turn it on with the trigger button:

Log filtering feature makes it easy to search for events based on various search criteria. For example, you need to find the request that initiated the creation of a user with the user name un_002:

Search result:

The Audit Log can be uploaded to a CSV file (Export to CSV button), which can then be processed in the way you need. The uploaded file will contain no more than 10,000 recent records that match the conditions of the last filtering performed.

The Сlear History button will delete all existing log entries. The Reset Filter button will clear the filtering conditions, as a result, the initial unfiltered set of records will be displayed.

5.4. Our support

If you have any questions please ask our support team.

https://luxplugins.atlassian.net/servicedesk/customer/portal/1

Sometimes, If you contact our support with an issue, our team may also ask you to send a .csv file of the SCIM Audit Log to help us understand the problem faster. The same may apply to the system log file described in p. 5.1. regarding the operation of the plugin.