SCIM User Provisioning for Atlassian Jira

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 Jira 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 Jira instance as an admin.
Click the admin dropdown and choose Atlassian Marketplace. The Manage apps screen loads.

Click Find new apps or Find new add-ons from the left-hand side of the page.
Locate SCIM User Provisioning for Jira 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 Jira. You're prompted to log into MyAtlassian. SCIM User Provisioning for Jira 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 Jira instance.

2. Plugin Setup

2.1. Quick setup

Here, 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 Jira 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.

3. Plugin Features

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://jiratest.luxplugins.com:2990/jira/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:

sudo apt update

sudo apt install curl

curl --version

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

curl -X GET https://jiratest.luxplugins.com:2990/jira/rest/user-provisioning/1.0/scim/v2/Users 
     -H "Accept: application/json" 
     -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxx" | json_pp

Sending a request, Windows:

curl -X GET https://jiratest.luxplugins.com:2990/jira/rest/user-provisioning/1.0/scim/v2/Users 
     -H "Accept: application/json" 
     -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxx"

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. Add logging for a plugin package (temporarly)

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 set the logging level for a new class or package:

Go to Administration > System.

Select Logging and profiling in the left-hand menu.
Scroll down to the Default loggers section.
Select Configure logging level for another package. This will let you enter the names of packages.
Enter the following name of package: com.luxplugins.jira.plugin

Check the setting. Click Ctrl+F and enter luxplugins, then click Enter. Check the logging level of found record:

Upon completion of the collection of information, return the old value of the logging level WARN.

Note that any changes you make here are not persisted across server restarts. You will need to edit 'WEB-INF/classes/log4j.properties' to change levels permanently.

5.2. SCIM Audit Log

You can easily check API requests history from the Jira 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 family name fn_lk10fjjz:

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.3. 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.