ICF 1.5.20.39

Atlassian connector

The Atlassian connector allows you to manage users, as well as manage user group memberships between IDM or Advanced Identity Cloud and Atlassian.

Atlassian requirements

To configure the connector, you need an Atlassian account and you must generate an API token to use as a password in the configuration. Complete the following steps to gather the required values, then use them to configure the connector.

Generate an API Token:

  1. Go to Atlassian API Token.

  2. Click Create API Token.

  3. Enter a name, select an expiration date, and click Create.

  4. Copy and save the API Token.

Install the Atlassian connector

To check for an Advanced Identity Cloud application for this connector, refer to:

You can download most connectors from Ping Identity Product Downloads, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

No

No

Download the connector .jar file from Ping Identity Product Downloads.

  • If you’re running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/atlassian-connector-1.5.20.39.jar /path/to/openidm/connectors/
  • If you’re using a remote connector server (RCS), place it in the /path/to/openicf/connectors directory on the RCS.

Configure the Atlassian connector

To create a connector configuration using a UI, use the Platform admin UI or the legacy admin UI (deprecated). Learn more about creating connector configuration.

Using the Platform admin UI

  1. From the sidebar, click settings_ethernet Provisioners.

  2. On the Provisioners page, click New Provisioner.

  3. In the New Provisioner modal, enter a Name.

  4. From the Connector Type list, select Atlassian Connector - 1.5.20.39.

    The UI displays a code editor field with the default provisioner configuration for the Atlassian connector.

  5. Make changes to the provisioner configuration, and click Save.

    For a list of all configuration properties, refer to Atlassian Connector Configuration.

When your connector is configured correctly, the connection status on the provisioner page displays as Connected.

Using the legacy admin UI

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type list, select Atlassian Connector - 1.5.20.39.

  5. Complete the Base Connector Details and any applicable Additional Options.

    For a list of all configuration properties, refer to Atlassian Connector Configuration.
  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the legacy admin UI.

Connection details

Property Description

serviceUri

The Atlassian API hostname, for example https://your.tenant.atlassian.net.

authenticationMethod

The authentication method. Must be BASIC.

login

The username to log into the Atlassian instance.

password

The password to log into the Atlassian instance.

connectionTimeout

The timeout for the underlying HTTPS connection in seconds. Defaults to 30.

Example Atlassian configuration

This excerpt shows a sample Atlassian connector configuration:

{
  "configurationProperties" : {
    "tokenExpiration" : null,
    "accessToken" : null,
    "serviceUri" : "__YOUR_TENANT__",
    "login" : "__YOUR_EMAIL__",
    "password" : "__API_TOKEN__",
    "authenticationMethod" : "BASIC",
    "tokenEndpoint" : null,
    "clientId" : null,
    "clientSecret" : null,
    "refreshToken" : null,
    "authToken" : null,
    "threadPoolSize": 25,
    "acceptSelfSignedCertificates" : false,
    "disableHostNameVerifier" : false,
    "disableHttpCompression" : false,
    "clientCertAlias" : null,
    "clientCertPassword" : null,
    "httpProxyHost" : null,
    "httpProxyPort" : null,
    "httpProxyUsername" : null,
    "httpProxyPassword" : null,
    "connectionTimeout" : 30,
    "grantType" : null,
    "scope" : null,
    "jwtKey" : null,
    "keyAlgorithm" : null,
    "jwtPem" : null,
    "jwtExpiration" : null,
    "jwtAlgorithm" : null,
    "jwtClaims" : null
  }
}

Mapping

From Atlassian users to IDM or Advanced Identity Cloud users

Attributes Grid: Where the columns represent the attribute name mapped from source to target to synchronize successfully.

SOURCE TARGET

_id

_id

__NAME__

userName

accountType

accountType

active

active

emailAddress

mail

locale

locale

products

products

groups

groups

timeZone

timeZone

From IDM or Advanced Identity Cloud users to Atlassian users

Attributes Grid: Where the columns represent the attribute name mapped from source to target to ensure successful synchronization.

SOURCE TARGET

mail

emailAddress

locale

locale

products

products

groups

groups

From Atlassian groups to IDM or Advanced Identity Cloud groups

Attributes Grid: Where the columns represent the attribute name mapped from source to target to ensure successful synchronization.

SOURCE TARGET

_id

_id

__NAME__

__NAME__

labels

labels

From IDM or Advanced Identity Cloud groups to Atlassian groups

Attributes Grid: Where the columns represent the attribute name mapped from source to target to ensure successful synchronization.

SOURCE TARGET

_id

_id

__NAME__

__NAME__

labels

labels

Test the Atlassian connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/atlassian?_action=test"
{
  "name": "atlassian",
  "enabled": true,
  "config": "config/provisioner.openicf/atlassian",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.atlassian-connector",
    "connectorName": "org.forgerock.openicf.connectors.atlassian.AtlassianConnector"
  },
  "displayName": "Atlassian Connector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__",
    "__GROUP__",
    "__ROLE__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector is configured correctly and can authenticate to the Atlassian environment.

Atlassian remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Atlassian connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

Refer to Remote connectors for configuring the Atlassian remote connector.

Configure connection pooling

The Atlassian connector supports HTTP pooling, which can substantially improve the performance of the connector. Learn more about the basic connection pooling configuration and different pooling mechanisms described in Connection pooling configuration.

Use the Atlassian connector

You can use the Atlassian connector to perform various actions on the following Atlassian resources:

Connector resource Atlassian resource type

__ACCOUNT__

__GROUP__

__ROLE__

Users

Create an Atlassian user

To create a new user, the only required attribute is emailAddress.

  • products can be specified during creation and may affect the user’s groups.

  • groups can be specified during creation and may affect the user’s products.

  • emailAddress will only be returned if it belongs to a domain registered on the platform.

  • emailAddress may take a few minutes to appear.

  • __NAME__ will be the content of emailAddress before the @ symbol.

  • __NAME__ can be updated by the user (the owner of the account) through the Atlassian Cloud platform.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "emailAddress": "john.doe@example.com",
  "products": [
    "jira-software"
  ],
  "groups": [
    "groupId1",
    "groupId2"
  ]
}
'\
'http://localhost:8080/openidm/system/atlassian/__ACCOUNT__?_action=create'
{
  "_id": "userId1",
  "accountType": "atlassian",
  "emailAddress": "john.doe@example.com",
  "active": true,
  "groups": [
    "groupId1",
    "groupId2"
  ],
  "__NAME__": "john.doe",
  "products": [
    "jira-software"
  ]
}
Update an Atlassian user

Only the following attribute can be updated:

  • groups

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match: *" \
--request PUT \
--data '{
  "groups": [
    "groupId1",
    "groupId2",
    "groupId3"
  ]
}' \
"http://localhost:8080/openidm/system/atlassian/__ACCOUNT__/userId1"
{
  "_id": "userId1",
  "accountType": "atlassian",
  "emailAddress": "john.doe@example.com",
  "active": true,
  "groups": [
    "groupId1",
    "groupId2",
    "groupId3"
  ],
  "__NAME__": "john.doe",
  "products": [
    "jira-software"
  ]
}
Query all Atlassian user IDs

The following example queries all Atlassian users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__ACCOUNT__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "userId1"
    },
    ...
    {
      "_id": "userId999"
    }
  ],
  "resultCount": 50,
  "pagedResultsCookie": "50",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query all Atlassian users

The following example queries all Atlassian users. By default, the connector returns 50 results per page:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__ACCOUNT__?_queryFilter=true"
{
  "result": [
    {
      "_id": "userId1",
      "accountType": "atlassian",
      "emailAddress": "john.doe@example.com",
      "active": true,
      "groups": [
        "groupId1",
        "groupId2"
      ],
      "__NAME__": "john.doe",
      "products": [
        "jira-software"
      ]
    },
    ...
    {
      "_id": "userId999",
      "accountType": "atlassian",
      "emailAddress": "jane.doe@example.com",
      "active": true,
      "groups": [
        "groupId1",
        "groupId2",
        "groupId3"
      ],
      "__NAME__": "jane.doe",
      "products": [
        "jira-software"
      ]
    }
  ],
  "resultCount": 50,
  "pagedResultsCookie": "50",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The Atlassian connector only supports equals and contains filters for users through the __NAME__ and emailAddress fields, which are evaluated simultaneously.

Query a single Atlassian user

The following example reads an Atlassian user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__ACCOUNT__/userId"
{
  "_id": "userId",
  "accountType": "atlassian",
  "emailAddress": "john.doe@example.com",
  "active": true,
  "groups": [
    "groupId1",
    "groupId2",
    "groupId3"
  ],
  "__NAME__": "john.doe",
  "products": [
    "jira-software"
  ]
}

The emailAddress is displayed only after the user has been activated. timeZone and locale are not returned by default. They must be requested through the _fields query parameter.

Delete an Atlassian user

The following example deletes an Atlassian user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request DELETE \
"http://localhost:8080/openidm/system/atlassian/__ACCOUNT__/userId"
{
  "_id": "userId",
  "accountType": "atlassian",
  "emailAddress": "john.doe@example.com",
  "active": false,
  "groups": [
    "groupId1",
    "groupId2",
    "groupId3"
  ],
  "__NAME__": "john.doe",
  "products": [
    "jira-software"
  ]
}

The DELETE operation doesn’t delete the user; it deactivates it.

Groups

Create an Atlassian group
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "__NAME__": "New Group"
}
'\
'http://localhost:8080/openidm/system/atlassian/__GROUP__?_action=create'
{
  "_id": "groupId123",
  "__NAME__": "New Group",
  "labels": []
}
Query all Atlassian groups

The following example queries all Atlassian groups:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__GROUP__?_queryFilter=true"
{
  "result": [
    {
     "_id": "groupId1",
     "__NAME__": "Group Name 1"
    },
    ...
    {
     "_id": "groupId99",
     "__NAME__": "Group Name 99"
    }
  ],
  "resultCount": 99,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query all Atlassian group IDs

The following example queries all Atlassian group IDs:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__GROUP__?_queryId=query-all-ids"
{
  "result": [
    {
     "_id": "groupId1"
    },
    ...
    {
     "_id": "groupId99"
    }
  ],
  "resultCount": 99,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query a single Atlassian group

The following example reads an Atlassian group:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__GROUP__/groupId1?_fields=_id,__NAME__,labels"
{
  "_id": "groupId1",
  "__NAME__": "Group Name 1",
  "labels": [
    "Admin",
    "Multi-App-Access"
  ]
}
Delete an Atlassian group

The following example deletes an Atlassian group:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request DELETE \
"http://localhost:8080/openidm/system/atlassian/__GROUP__/groupId1"
{
  "_id": "groupId1",
  "__NAME__": "Group Name 1"
}

Roles

Query all Atlassian roles

The following example queries all Atlassian roles:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__ROLE__?_queryFilter=true"
{
  "result": [
    {
      "_id": "roleId1",
      "__NAME__": "Role Name 1",
      "description": "Role Description 1"
    },
    ...
    {
      "_id": "roleId10",
      "__NAME__": "Role Name 10",
      "description": "Role Description 10"
    }
  ],
  "resultCount": 10,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query all Atlassian role IDs

The following example queries all Atlassian role IDs:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__ROLE__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "roleId1"
    },
    ...
    {
      "_id": "roleId10"
    }
  ],
  "resultCount": 10,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query a single Atlassian role

The following example reads an Atlassian role:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/atlassian/__ROLE__/roleId1"
{
    "_id": "roleId1",
    "description": "Role description",
    "__NAME__": "Role name 1"
}

OpenICF Interfaces Implemented by the Atlassian Connector

The Atlassian Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector.

Any script that runs on the connector has the following characteristics:

  • The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.

  • The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.

  • The script has access to any script arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Test

Tests the connector configuration.

Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

Atlassian Connector Configuration

The Atlassian Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

serviceUri

String

null

Yes

The service endpoint URI.

login

String

null

No

The service login name.

password

GuardedString

null

Yes

No

The service user password.

threadPoolSize

int

25

No

The maximum number of threads used for concurrent operations, such as fetching user groups and project roles in bulk. Default is 25.

authenticationMethod

String

OAUTH

Yes

Defines which method is to be used to authenticate on the remote server. Options are BASIC (username/password), OAUTH (Client id/secret), JWT_TOKEN (jwt token), or TOKEN (static token).

tokenEndpoint

String

null

No

When using OAUTH as authentication method, this property defines the endpoint where a new access token should be queried for (https://myserver.com/oauth2/token).

clientId

String

null

No

The client identifier for OAuth2.

clientSecret

GuardedString

null

Yes

No

Secure client secret for OAuth2.

authToken

GuardedString

null

Yes

No

Static authentication token.

acceptSelfSignedCertificates

boolean

false

No

To be used for debug/test purposes. To be avoided in production.

disableHostNameVerifier

boolean

false

No

To be used for debug/test purposes. To be avoided in production.

disableHttpCompression

boolean

false

No

Set this property to true to disable content compression.

clientCertAlias

String

null

No

If TLS Mutual Auth is needed, set this to the certificate alias from the keystore.

clientCertPassword

GuardedString

null

Yes

No

If TLS Mutual Auth is needed and the client certificate (private key) password is different from the keystore password, set this to the client private key password.

maximumConnections

Integer

10

No

Defines the max size of the HTTP connection pool used.

httpProxyHost

String

null

No

Defines the Hostname if an HTTP proxy is used between the connector and the service.

httpProxyPort

Integer

null

No

Defines the Port if an HTTP proxy is used between the connector and the service.

httpProxyUsername

String

null

No

Defines Proxy Username if an HTTP proxy is used between the connector and the service.

httpProxyPassword

GuardedString

null

Yes

No

Defines Proxy Password if an HTTP proxy is used between the connector and the service.

connectionTimeout

int

30

No

Defines a timeout for the underlying HTTP connection in seconds.

refreshToken

GuardedString

null

No

Used by the refresh_token grant type.

grantType

String

null

No

The OAuth2 grant type to use (client_credentials, refresh_token, or jwt_bearer).

scope

String

null

No

The OAuth2 scope to use.

authorizationTokenPrefix

String

Bearer

No

The prefix to be used in the Authorization HTTP header for Token authentication.

useBasicAuthForOauthTokenNeg

boolean

true

No

The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header).

jwtKey

GuardedString

null

Yes

No

The JWT data structure that represents a cryptographic key.

jwtExpiration

Integer

null

No

Defines the JWT expiration time in minutes.

jwtAlgorithm

String

null

No

The Algorithm type to sign payload.

jwtClaims

Map

null

No

JWT Claims to be included in the payload

jwtPem

GuardedString

null

Yes

No

The contents of the private key of the PEM file

jwtCert

GuardedString

null

Yes

No

The contents of the certificate of the PEM file

keyAlgorithm

String

null

No

Indicates the type of key (such as RSA, DSA or EC) used to sign from the PEM.

userAgent

String

PingIdentityConnector

No

The User Agent HTTP Header used by the connector. Defaults to PingIdentityConnector.

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.