Atlassian IAM

Integrate with Atlassian's services to execute CRUD operations for employee lifecycle processes.

Authentication & Identity Management · Atlassian IAM

Details

IDAtlassian IAM
ProviderAtlassian
CategoryAuthentication & Identity Management
From Version6.0.0
Docker Imagedemisto/python3:3.12.13.10116658
Supported ModulesAgentix XSIAM EDR Cortex Cloud Cloud Runtime Security

README

Note: This integration should be used as part of our IAM premium pack. For further details, visit our IAM pack documentation.
For more information, please refer to the Identity Lifecycle Management article.
Integrate with Atlassian’s services to execute generic ILM management operations such as create, update, delete, etc, for employee lifecycle processes.

Configure Atlassian IAM in Cortex

Parameter Description Required
Atlassian URL   True
Access Token   False
Directory ID   True
Trust any certificate (not secure)   False
Use system proxy settings   False
Allow creating users If set to false, iam-create-user command will be skipped, and user will not be created. False
Allow updating users   False
Allow enabling users   False
Allow disabling users   False
Automatically create user if not found in update command   False
Incoming Mapper   True
Outgoing Mapper Cortex XSOAR only parameter. False
* To allow the integration to access the mapper from within the code, as required by the ILM pack, both mappers have to be configured in their proper respective fields and not in the "Mapper (outgoing)" dropdown list selector.

Commands

You can execute these commands from the CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

iam-create-user


Creates a user.

Base Command

iam-create-user

Input

Argument Name Description Required
user-profile User Profile indicator details. Required
allow-enable When set to true, after the command execution the status of the user in the 3rd-party integration will be active. Possible values are: true, false. Default is true. Optional

Context Output

Path Type Description
IAM.Vendor.active Boolean When true, indicates that the employee’s status is active in the 3rd-party integration.
IAM.Vendor.brand String Name of the integration.
IAM.Vendor.details string Provides the raw data from the 3rd-party integration.
IAM.Vendor.email String The employee’s email address.
IAM.Vendor.errorCode Number HTTP error response code.
IAM.Vendor.errorMessage String Reason why the API failed.
IAM.Vendor.id String The employee’s user ID in the app.
IAM.Vendor.instanceName string Name of the integration instance.
IAM.Vendor.success Boolean When true, indicates that the command was executed successfully.
IAM.Vendor.username String The employee’s username in the app.

Command Example

!iam-create-user user-profile=`{"emails":[{"value":"testatlas@paloaltonetworks.com","type":"work","primary":"true"}],"is_active": "true", "userName":"testatlas@paloaltonetworks.com"}` using="Atlassian IAM_instance_1"

Context Example

{
    "IAM": {
        "UserProfile": {
            "emails": [
                {
                    "primary": "true",
                    "type": "work",
                    "value": "testatlas@paloaltonetworks.com"
                }
            ],
            "is_active": "true",
            "userName": "testatlas@paloaltonetworks.com"
        },
        "Vendor": {
            "action": "create",
            "active": true,
            "brand": "Atlassian IAM",
            "details": {
                "active": true,
                "emails": [
                    {
                        "primary": true,
                        "type": "work",
                        "value": "testatlas@paloaltonetworks.com"
                    }
                ],
                "groups": [],
                "id": "247b915a-9d6c-4cd5-b5a5-071b1b3abc2e",
                "meta": {
                    "created": "2021-02-16T15:05:41.185473Z",
                    "lastModified": "2021-02-16T15:05:41.185473Z",
                    "location": "https://api.atlassian.com/scim/directory/315e79ae-404a-4061-8a88-df91c8c7db34/Users/247b915a-9d6c-4cd5-b5a5-071b1b3abc2e",
                    "resourceType": "User"
                },
                "schemas": [
                    "urn:scim:schemas:extension:atlassian-external:1.0",
                    "urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
                ],
                "urn:scim:schemas:extension:atlassian-external:1.0": {
                    "atlassianAccountId": "602bdf457b23f40068547c25"
                },
                "userName": "testatlas@paloaltonetworks.com"
            },
            "email": null,
            "errorCode": null,
            "errorMessage": "",
            "id": "247b915a-9d6c-4cd5-b5a5-071b1b3abc2e",
            "instanceName": "Atlassian IAM_instance_1",
            "reason": "",
            "skipped": false,
            "success": true,
            "username": "testatlas@paloaltonetworks.com"
        }
    }
}

Human Readable Output

Create User Results (Atlassian IAM)

brand instanceName success active id username details
Atlassian IAM Atlassian IAM_instance_1 true true 247b915a-9d6c-4cd5-b5a5-071b1b3abc2e testatlas@paloaltonetworks.com schemas: urn:scim:schemas:extension:atlassian-external:1.0,
urn:ietf:params:scim:schemas:core:2.0:User,
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
userName: testatlas@paloaltonetworks.com
emails: {‘value’: ‘testatlas@paloaltonetworks.com’, ‘type’: ‘work’, ‘primary’: True}
meta: {“resourceType”: “User”, “location”: “https://api.atlassian.com/scim/directory/315e79ae-404a-4061-8a88-df91c8c7db34/Users/247b915a-9d6c-4cd5-b5a5-071b1b3abc2e”, “lastModified”: “2021-02-16T15:05:41.185473Z”, “created”: “2021-02-16T15:05:41.185473Z”}
groups:
urn:scim:schemas:extension:atlassian-external:1.0: {“atlassianAccountId”: “602bdf457b23f40068547c25”}
id: 247b915a-9d6c-4cd5-b5a5-071b1b3abc2e
active: true

iam-update-user


Updates an existing user with the data passed in the user-profile argument.

Base Command

iam-update-user

Input

Argument Name Description Required
user-profile A User Profile indicator. Required
allow-enable When set to true, after the command execution the status of the user in the 3rd-party integration will be active. Possible values are: true, false. Default is true. Optional

Context Output

Path Type Description
IAM.Vendor.active Boolean When true, indicates that the employee’s status is active in the 3rd-party integration.
IAM.Vendor.brand String Name of the integration.
IAM.Vendor.details string Provides the raw data from the 3rd-party integration.
IAM.Vendor.email String The employee’s email address.
IAM.Vendor.errorCode Number HTTP error response code.
IAM.Vendor.errorMessage String Reason why the API failed.
IAM.Vendor.id String The employee’s user ID in the app.
IAM.Vendor.instanceName string Name of the integration instance.
IAM.Vendor.success Boolean When true, indicates that the command was executed successfully.
IAM.Vendor.username String The employee’s username in the app.

Command Example

!iam-update-user user-profile=`{"email": "testatlas@paloaltonetworks.com", "username": "testatlas@paloaltonetworks.com", "title": "Manager"}` using="Atlassian IAM_instance_1"

Context Example

{
    "IAM": {
        "UserProfile": {
            "email": "testatlas@paloaltonetworks.com",
            "title": "Manager",
            "username": "testatlas@paloaltonetworks.com"
        },
        "Vendor": {
            "action": "update",
            "active": true,
            "brand": "Atlassian IAM",
            "details": {
                "active": true,
                "emails": [
                    {
                        "primary": true,
                        "type": "work",
                        "value": "testatlas@paloaltonetworks.com"
                    }
                ],
                "groups": [],
                "id": "247b915a-9d6c-4cd5-b5a5-071b1b3abc2e",
                "meta": {
                    "created": "2021-02-16T15:05:41.185473Z",
                    "lastModified": "2021-02-16T15:05:41.185473Z",
                    "location": "https://api.atlassian.com/scim/directory/315e79ae-404a-4061-8a88-df91c8c7db34/Users/247b915a-9d6c-4cd5-b5a5-071b1b3abc2e",
                    "resourceType": "User"
                },
                "schemas": [
                    "urn:scim:schemas:extension:atlassian-external:1.0",
                    "urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
                ],
                "urn:scim:schemas:extension:atlassian-external:1.0": {
                    "atlassianAccountId": "602bdf457b23f40068547c25"
                },
                "userName": "testatlas@paloaltonetworks.com"
            },
            "email": "testatlas@paloaltonetworks.com",
            "errorCode": null,
            "errorMessage": "",
            "id": "247b915a-9d6c-4cd5-b5a5-071b1b3abc2e",
            "instanceName": "Atlassian IAM_instance_1",
            "reason": "",
            "skipped": false,
            "success": true,
            "username": "testatlas@paloaltonetworks.com"
        }
    }
}

Human Readable Output

Update User Results (Atlassian IAM)

brand instanceName success active id username email details
Atlassian IAM Atlassian IAM_instance_1 true true 247b915a-9d6c-4cd5-b5a5-071b1b3abc2e testatlas@paloaltonetworks.com testatlas@paloaltonetworks.com schemas: urn:scim:schemas:extension:atlassian-external:1.0,
urn:ietf:params:scim:schemas:core:2.0:User,
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
userName: testatlas@paloaltonetworks.com
emails: {‘value’: ‘testatlas@paloaltonetworks.com’, ‘type’: ‘work’, ‘primary’: True}
meta: {“resourceType”: “User”, “location”: “https://api.atlassian.com/scim/directory/315e79ae-404a-4061-8a88-df91c8c7db34/Users/247b915a-9d6c-4cd5-b5a5-071b1b3abc2e”, “lastModified”: “2021-02-16T15:05:41.185473Z”, “created”: “2021-02-16T15:05:41.185473Z”}
groups:
urn:scim:schemas:extension:atlassian-external:1.0: {“atlassianAccountId”: “602bdf457b23f40068547c25”}
id: 247b915a-9d6c-4cd5-b5a5-071b1b3abc2e
active: true

iam-get-user


Retrieves a single user resource.

Base Command

iam-get-user

Input

Argument Name Description Required
user-profile A User Profile indicator. Required

Context Output

Path Type Description
IAM.Vendor.active Boolean When true, indicates that the employee’s status is active in the 3rd-party integration.
IAM.Vendor.brand String Name of the integration.
IAM.Vendor.details string Provides the raw data from the 3rd-party integration.
IAM.Vendor.email String The employee’s email address.
IAM.Vendor.errorCode Number HTTP error response code.
IAM.Vendor.errorMessage String Reason why the API failed.
IAM.Vendor.id String The employee’s user ID in the app.
IAM.Vendor.instanceName string Name of the integration instance.
IAM.Vendor.success Boolean When true, indicates that the command was executed successfully.
IAM.Vendor.username String The employee’s username in the app.

Command Example

!iam-get-user user-profile=`{"email": "test@paloaltonetworks.com", "username": "testDemisto"}` using="Atlassian IAM_instance_1"

Context Example

{
    "IAM": {
        "UserProfile": {
            "Email": "test@paloaltonetworks.com",
            "Title": "Team Lead",
            "Username": "testDemisto"
        },
        "Vendor": {
            "action": "get",
            "active": null,
            "brand": "Atlassian IAM",
            "details": {
                "emails": [
                    {
                        "primary": true,
                        "type": "work",
                        "value": "test@paloaltonetworks.com"
                    }
                ],
                "groups": [],
                "id": "550364dd-1c1e-4953-bffc-418fce013c2e",
                "meta": {
                    "created": "2021-02-15T13:26:34.13545Z",
                    "lastModified": "2021-02-15T17:01:01.876067Z",
                    "location": "https://api.atlassian.com/scim/directory/315e79ae-404a-4061-8a88-df91c8c7db34/Users/550364dd-1c1e-4953-bffc-418fce013c2e",
                    "resourceType": "User"
                },
                "schemas": [
                    "urn:scim:schemas:extension:atlassian-external:1.0",
                    "urn:ietf:params:scim:schemas:core:2.0:User",
                    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
                ],
                "title": "Team Lead",
                "urn:scim:schemas:extension:atlassian-external:1.0": {
                    "atlassianAccountId": "5f3589458d89e30046317d34"
                },
                "userName": "testDemisto"
            },
            "email": null,
            "errorCode": null,
            "errorMessage": "",
            "id": "550364dd-1c1e-4953-bffc-418fce013c2e",
            "instanceName": "Atlassian IAM_instance_1",
            "reason": "",
            "skipped": false,
            "success": true,
            "username": "testDemisto"
        }
    }
}

Human Readable Output

Get User Results (Atlassian IAM)

brand instanceName success id username details
Atlassian IAM Atlassian IAM_instance_1 true 550364dd-1c1e-4953-bffc-418fce013c2e testDemisto schemas: urn:scim:schemas:extension:atlassian-external:1.0,
urn:ietf:params:scim:schemas:core:2.0:User,
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
userName: testDemisto
emails: {‘value’: ‘test@paloaltonetworks.com’, ‘type’: ‘work’, ‘primary’: True}
title: Team Lead
meta: {“resourceType”: “User”, “location”: “https://api.atlassian.com/scim/directory/315e79ae-404a-4061-8a88-df91c8c7db34/Users/550364dd-1c1e-4953-bffc-418fce013c2e”, “lastModified”: “2021-02-15T17:01:01.876067Z”, “created”: “2021-02-15T13:26:34.13545Z”}
groups:
urn:scim:schemas:extension:atlassian-external:1.0: {“atlassianAccountId”: “5f3589458d89e30046317d34”}
id: 550364dd-1c1e-4953-bffc-418fce013c2e

iam-disable-user


Disable an active user.

Base Command

iam-disable-user

Input

Argument Name Description Required
user-profile A User Profile indicator. Required

Context Output

Path Type Description
IAM.Vendor.active Boolean When true, indicates that the employee’s status is active in the 3rd-party integration.
IAM.Vendor.brand String Name of the integration.
IAM.Vendor.details string Provides the raw data from the 3rd-party integration.
IAM.Vendor.email String The employee’s email address.
IAM.Vendor.errorCode Number HTTP error response code.
IAM.Vendor.errorMessage String Reason why the API failed.
IAM.Vendor.id String The employee’s user ID in the app.
IAM.Vendor.instanceName string Name of the integration instance.
IAM.Vendor.success Boolean When true, indicates that the command was executed successfully.
IAM.Vendor.username String The employee’s username in the app.

Command Example

!iam-disable-user user-profile=`{"email": "testdemisto@paloaltonetworks.com", "username": "Demisto"}` using="Atlassian IAM_instance_1"

Context Example

{
    "IAM": {
        "UserProfile": {
            "email": "testdemisto@paloaltonetworks.com",
            "username": "Demisto"
        },
        "Vendor": {
            "action": "disable",
            "active": null,
            "brand": "Atlassian IAM",
            "details": null,
            "email": "testdemisto@paloaltonetworks.com",
            "errorCode": null,
            "errorMessage": "",
            "id": null,
            "instanceName": "Atlassian IAM_instance_1",
            "reason": "User does not exist",
            "skipped": true,
            "success": true,
            "username": null
        }
    }
}

Human Readable Output

Disable User Results (Atlassian IAM)

brand instanceName skipped reason
Atlassian IAM Atlassian IAM_instance_1 true User does not exist

Configuration parameters

  • url — Atlassian URL (required)
  • access_token — Access Token
  • access_token_creds
  • directory_id — Directory ID (required)
  • insecure — Trust any certificate (not secure)
  • proxy — Use system proxy settings
  • create_user_enabled — Allow creating users
  • update_user_enabled — Allow updating users
  • enable_user_enabled — Allow enabling users
  • disable_user_enabled — Allow disabling users
  • create_if_not_exists — Automatically create user if not found in update command
  • mapper_in — Incoming Mapper (required)
  • mapper_out — Outgoing Mapper

Commands (5)

  • get-mapping-fields

    Retrieves a User Profile schema, which holds all of the user fields within the application. Used for outgoing-mapping through the Get Schema option.

  • iam-create-user

    Creates a user.

  • iam-disable-user

    Disable an active user.

  • iam-get-user

    Retrieves a single user resource.

  • iam-update-user

    Updates an existing user with the data passed in the user-profile argument.

import traceback

import demistomock as demisto

# Disable insecure warnings
import urllib3
from CommonServerPython import *

urllib3.disable_warnings()


"""CLIENT CLASS"""


class Client(BaseClient):
    """
    Atlassian IAM Client class that implements logic to authenticate with Atlassian.
    """

    def __init__(self, base_url, directory_id, headers, ok_codes=None, verify=True, proxy=False):
        super().__init__(base_url, verify=verify, proxy=proxy, ok_codes=ok_codes, headers=headers)
        self.directory_id = directory_id

    def test(self):
        uri = f"/scim/directory/{self.directory_id}/Users?count=1"
        res = self._http_request(method="GET", url_suffix=uri)
        return res

    def get_user(self, filter_name, filter_value):
        uri = f"/scim/directory/{self.directory_id}/Users"
        query_params = {"filter": f'{filter_name} eq "{filter_value}"'}

        if filter_name == "id":
            uri += f"/{filter_value}"
            query_params = {}

        res = self._http_request(method="GET", url_suffix=uri, params=query_params)
        if res:
            user_app_data = res.get("Resources")[0] if res.get("totalResults") == 1 else res
            user_id = user_app_data.get("id")
            is_active = user_app_data.get("active")
            username = user_app_data.get("userName")
            email = get_first_primary_email_by_scim_schema(user_app_data)

            return IAMUserAppData(user_id, username, is_active, user_app_data, email)
        return None

    def create_user(self, user_data):
        if isinstance(user_data.get("emails"), dict):
            user_data["emails"] = [user_data["emails"]]
        uri = f"/scim/directory/{self.directory_id}/Users"
        res = self._http_request(method="POST", url_suffix=uri, json_data=user_data)
        user_app_data = res
        user_id = user_app_data.get("id")
        is_active = user_app_data.get("active")
        username = user_app_data.get("userName")
        email = get_first_primary_email_by_scim_schema(user_app_data)

        return IAMUserAppData(user_id, username, is_active, user_app_data, email)

    def update_user(self, user_id, user_data):
        if isinstance(user_data.get("emails"), dict):
            user_data["emails"] = [user_data["emails"]]
        uri = f"/scim/directory/{self.directory_id}/Users/{user_id}"
        res = self._http_request(method="PUT", url_suffix=uri, json_data=user_data)
        user_app_data = res
        user_id = user_app_data.get("id")
        is_active = user_app_data.get("active")
        username = user_app_data.get("userName")

        return IAMUserAppData(user_id, username, is_active, user_app_data)

    def disable_user(self, user_id):
        uri = f"/scim/directory/{self.directory_id}/Users/{user_id}"
        res = self._http_request(method="DELETE", url_suffix=uri)
        user_app_data = res
        user_id = user_app_data.get("id")
        is_active = user_app_data.get("active")
        username = user_app_data.get("userName")

        return IAMUserAppData(user_id, username, is_active, user_app_data)

    def get_app_fields(self):
        app_fields = {}
        uri = f"/scim/directory/{self.directory_id}/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
        res = self._http_request(method="GET", url_suffix=uri)

        elements = res.get("attributes", [])
        for elem in elements:
            if elem.get("name"):
                field_name = elem.get("name")
                description = elem.get("description")
                app_fields[field_name] = description

        return app_fields

    @staticmethod
    def handle_exception(user_profile, e, action):
        """Handles failed responses from the application API by setting the User Profile object with the results.

        Args:
            user_profile (IAMUserProfile): The User Profile object.
            e (Exception): The exception error. If DemistoException, holds the response json.
            action (IAMActions): An enum represents the current action (get, update, create, etc).
        """
        if e.__class__ is DemistoException and hasattr(e, "res") and e.res is not None:
            error_code = e.res.status_code
            try:
                resp = e.res.json()
                error_message = resp.get("detail")
            except ValueError:
                error_message = str(e)
        else:
            error_code = ""
            error_message = str(e)

        if error_code == 204:
            user_profile.set_result(action=action, success=True, details="The user was successfully disabled.")

        user_profile.set_result(
            action=action, success=False, error_code=error_code, error_message=f"{error_message}\n{traceback.format_exc()}"
        )

        demisto.error(traceback.format_exc())


"""COMMAND FUNCTIONS"""


def test_module(client):
    client.test()
    return_results("ok")


def get_mapping_fields(client: Client) -> GetMappingFieldsResponse:
    """Creates and returns a GetMappingFieldsResponse object of the user schema in the application

    :param client: (Client) The integration Client object that implements a get_app_fields() method
    :return: (GetMappingFieldsResponse) An object that represents the user schema
    """
    app_fields = client.get_app_fields()
    incident_type_scheme = SchemeTypeMapping(type_name=IAMUserProfile.DEFAULT_INCIDENT_TYPE)

    for field, description in app_fields.items():
        incident_type_scheme.add_field(field, description)

    return GetMappingFieldsResponse([incident_type_scheme])


def main():
    user_profile = None
    params = demisto.params()
    command = demisto.command()
    args = demisto.args()

    verify_certificate = not params.get("insecure", False)
    proxy = params.get("proxy", False)
    base_url = params.get("url")
    if base_url[-1] != "/":
        base_url += "/"
    access_token = params.get("access_token_creds", {}).get("password") or params.get("access_token")
    directory_id = params.get("directory_id")

    mapper_in = params.get("mapper_in")
    mapper_out = params.get("mapper_out")
    is_create_enabled = params.get("create_user_enabled")
    is_disable_enabled = params.get("disable_user_enabled")
    is_enable_enabled = params.get("enable_user_enabled")
    is_update_enabled = demisto.params().get("update_user_enabled")
    create_if_not_exists = demisto.params().get("create_if_not_exists")

    iam_command = IAMCommand(
        is_create_enabled,
        is_enable_enabled,
        is_disable_enabled,
        is_update_enabled,
        create_if_not_exists,
        mapper_in,
        mapper_out,
        get_user_iam_attrs=["id", "userName", "emails"],
    )

    headers = {"Content-Type": "application/json", "Accept": "application/json", "Authorization": f"Bearer {access_token}"}

    client = Client(
        base_url=base_url, directory_id=directory_id, verify=verify_certificate, proxy=proxy, headers=headers, ok_codes=(200, 201)
    )

    demisto.debug(f"Command being called is {command}")

    if command == "iam-get-user":
        user_profile = iam_command.get_user(client, args)

    elif command == "iam-create-user":
        user_profile = iam_command.create_user(client, args)

    elif command == "iam-update-user":
        user_profile = iam_command.update_user(client, args)

    elif command == "iam-disable-user":
        user_profile = iam_command.disable_user(client, args)

    if user_profile:
        # user_profile.return_outputs()
        return_results(user_profile)

    try:
        if command == "test-module":
            test_module(client)

        elif command == "get-mapping-fields":
            return_results(get_mapping_fields(client))

    except Exception:
        # For any other integration command exception, return an error
        return_error(f"Failed to execute {command} command.")


from IAMApiModule import *  # noqa: E402

if __name__ in ("__main__", "__builtin__", "builtins"):
    main()