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.
Table of contents
1.
| Anchor | ||||
|---|---|---|---|---|
|
Log into your Bitbucket instance as an admin.
Click the admin dropdown and choose Atlassian Marketplace. The Manage apps screen loads.
...
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.
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
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.
...
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.
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
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.
...
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.
| Anchor | ||||
|---|---|---|---|---|
|
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:
...
| Code Block | ||
|---|---|---|
| ||
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:
...
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.
...
Click Send Button. Analyze the response:
...
5.
| Anchor | ||||
|---|---|---|---|---|
|
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.
...
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:
...
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.
...
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.
6.
| Anchor | ||||
|---|---|---|---|---|
|
SCIM Integration with OKTA (new)
...