Hello IAM World
An Identity and Access Management integration template.
Identity and Access Management · Hello World IAM
Details
| ID | Hello IAM World |
|---|---|
| Provider | Open Source |
| Category | Identity and Access Management |
| From Version | 6.0.0 |
| Docker Image | demisto/python3:3.12.13.10116658 |
| Supported Modules | Agentix XSIAM EDR Cortex Cloud Cloud Runtime Security |
README
This README contains the full documentation for your integration.
You auto-generate this README file from your integration YML file using the demisto-sdk generate-docs command.
For more information see the integration documentation.
An Identity and Access Management integration template.
Configure Hello World IAM in Cortex
| Parameter | Description | Required |
|---|---|---|
| Base URL | True | |
| Username | True | |
| Password | True | |
| Trust any certificate (not secure) | False | |
| Use system proxy settings | False | |
| Allow creating users | 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 |
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. |
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. |
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. |
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. |
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.
Base Command
get-mapping-fields
Input
There are no input arguments for this command.
Context Output
There is no context output for this command.
Incident Mirroring
You can enable incident mirroring between Cortex XSOAR incidents and Hello World IAM corresponding events (available from Cortex XSOAR version 6.0.0).
To set up the mirroring:
- Enable Fetching incidents in your instance configuration.
Newly fetched incidents will be mirrored in the chosen direction. However, this selection does not affect existing incidents.
Important Note: To ensure the mirroring works as expected, mappers are required, both for incoming and outgoing, to map the expected fields in Cortex XSOAR and Hello World IAM.
Configuration parameters
url— Base URL (required)credentials— Username (required)insecure— Trust any certificate (not secure)proxy— Use system proxy settingscreate_user_enabled— Allow creating usersupdate_user_enabled— Allow updating usersenable_user_enabled— Allow enabling usersdisable_user_enabled— Allow disabling userscreate_if_not_exists— Automatically create user if not found in update commandmapper_in— Incoming Mapper (required)mapper_out— Outgoing Mapper
Commands (5)
-
get-mapping-fieldsRetrieves 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-userCreates a user.
-
iam-disable-userDisable an active user.
-
iam-get-userRetrieves a single user resource.
-
iam-update-userUpdates an existing user with the data passed in the user-profile argument.
from HelloIAMWorld import Client, get_mapping_fields from IAMApiModule import * from requests import Response, Session APP_USER_OUTPUT = { "user_id": "mock_id", "user_name": "mock_user_name", "first_name": "mock_first_name", "last_name": "mock_last_name", "active": "true", "email": "testdemisto2@paloaltonetworks.com", } USER_APP_DATA = IAMUserAppData("mock_id", "mock_user_name", is_active=True, app_data=APP_USER_OUTPUT) APP_DISABLED_USER_OUTPUT = { "user_id": "mock_id", "user_name": "mock_user_name", "first_name": "mock_first_name", "last_name": "mock_last_name", "active": "false", "email": "testdemisto2@paloaltonetworks.com", } DISABLED_USER_APP_DATA = IAMUserAppData("mock_id", "mock_user_name", is_active=False, app_data=APP_DISABLED_USER_OUTPUT) def mock_client(): client = Client(base_url="https://test.com") return client def get_outputs_from_user_profile(user_profile): entry_context = user_profile.to_entry() outputs = entry_context.get("Contents") return outputs def test_get_user_command__existing_user(mocker): """ Given: - An app client object - A user-profile argument that contains an email of a user When: - The user exists in the application - Calling function get_user_command Then: - Ensure the resulted User Profile object holds the correct user details """ client = mock_client() args = {"user-profile": {"email": "testdemisto2@paloaltonetworks.com"}} mocker.patch.object(client, "get_user", return_value=USER_APP_DATA) mocker.patch.object(IAMUserProfile, "update_with_app_data", return_value={}) user_profile = IAMCommand().get_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.GET_USER assert outputs.get("success") is True assert outputs.get("active") is True assert outputs.get("id") == "mock_id" assert outputs.get("username") == "mock_user_name" assert outputs.get("details", {}).get("first_name") == "mock_first_name" assert outputs.get("details", {}).get("last_name") == "mock_last_name" def test_get_user_command__non_existing_user(mocker): """ Given: - An app client object - A user-profile argument that contains an email a user When: - The user does not exist in the application - Calling function get_user_command Then: - Ensure the resulted User Profile object holds information about an unsuccessful result. """ client = mock_client() args = {"user-profile": {"email": "testdemisto2@paloaltonetworks.com"}} mocker.patch.object(client, "get_user", return_value=None) user_profile = IAMCommand().get_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.GET_USER assert outputs.get("success") is False assert outputs.get("errorCode") == IAMErrors.USER_DOES_NOT_EXIST[0] assert outputs.get("errorMessage") == IAMErrors.USER_DOES_NOT_EXIST[1] def test_get_user_command__bad_response(mocker): """ Given: - An app client object - A user-profile argument that contains an email of a non-existing user in the application When: - Calling function get_user_command - A bad response (500) is returned from the application API Then: - Ensure the resulted User Profile object holds information about the bad response. """ import demistomock as demisto client = mock_client() args = {"user-profile": {"email": "testdemisto2@paloaltonetworks.com"}} bad_response = Response() bad_response.status_code = 500 bad_response._content = b'{"error": {"detail": "details", "message": "message"}}' mocker.patch.object(demisto, "error") mocker.patch.object(Session, "request", return_value=bad_response) user_profile = IAMCommand().get_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.GET_USER assert outputs.get("success") is False assert outputs.get("errorCode") == 500 assert outputs.get("errorMessage") == "message: details" def test_create_user_command__success(mocker): """ Given: - An app client object - A user-profile argument that contains an email of a non-existing user in the application When: - Calling function create_user_command Then: - Ensure a User Profile object with the user data is returned """ client = mock_client() args = {"user-profile": {"email": "testdemisto2@paloaltonetworks.com"}} mocker.patch.object(client, "get_user", return_value=None) mocker.patch.object(client, "create_user", return_value=USER_APP_DATA) user_profile = IAMCommand(get_user_iam_attrs=["email"]).create_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.CREATE_USER assert outputs.get("success") is True assert outputs.get("active") is True assert outputs.get("id") == "mock_id" assert outputs.get("username") == "mock_user_name" assert outputs.get("details", {}).get("first_name") == "mock_first_name" assert outputs.get("details", {}).get("last_name") == "mock_last_name" def test_create_user_command__user_already_exists(mocker): """ Given: - An app client object - A user-profile argument that contains an email of a user When: - The user already exists in the application and disabled - allow-enable argument is false - Calling function create_user_command Then: - Ensure the command is considered successful and the user is still disabled """ client = mock_client() args = {"user-profile": {"email": "testdemisto2@paloaltonetworks.com"}, "allow-enable": "false"} mocker.patch.object(client, "get_user", return_value=DISABLED_USER_APP_DATA) mocker.patch.object(client, "update_user", return_value=DISABLED_USER_APP_DATA) user_profile = IAMCommand().create_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.UPDATE_USER assert outputs.get("success") is True assert outputs.get("active") is False assert outputs.get("id") == "mock_id" assert outputs.get("username") == "mock_user_name" assert outputs.get("details", {}).get("first_name") == "mock_first_name" assert outputs.get("details", {}).get("last_name") == "mock_last_name" def test_update_user_command__non_existing_user(mocker): """ Given: - An app client object - A user-profile argument that contains user data When: - The user does not exist in the application - create-if-not-exists parameter is checked - Create User command is enabled - Calling function update_user_command Then: - Ensure the create action is executed - Ensure a User Profile object with the user data is returned """ client = mock_client() args = {"user-profile": {"email": "testdemisto2@paloaltonetworks.com", "givenname": "mock_first_name"}} mocker.patch.object(client, "get_user", return_value=None) mocker.patch.object(client, "create_user", return_value=USER_APP_DATA) user_profile = IAMCommand(create_if_not_exists=True, get_user_iam_attrs=["email"]).update_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.CREATE_USER assert outputs.get("success") is True assert outputs.get("active") is True assert outputs.get("id") == "mock_id" assert outputs.get("username") == "mock_user_name" assert outputs.get("details", {}).get("first_name") == "mock_first_name" assert outputs.get("details", {}).get("last_name") == "mock_last_name" def test_update_user_command__command_is_disabled(mocker): """ Given: - An app client object - A user-profile argument that contains user data When: - Update User command is disabled - Calling function update_user_command Then: - Ensure the command is considered successful and skipped """ client = mock_client() args = {"user-profile": {"email": "testdemisto2@paloaltonetworks.com", "givenname": "mock_first_name"}} mocker.patch.object(client, "get_user", return_value=None) mocker.patch.object(IAMUserProfile, "map_object", return_value={}) mocker.patch.object(client, "update_user", return_value=USER_APP_DATA) user_profile = IAMCommand(is_update_enabled=False).update_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.UPDATE_USER assert outputs.get("success") is True assert outputs.get("skipped") is True assert outputs.get("reason") == "Command is disabled." def test_update_user_command__allow_enable(mocker): """ Given: - An app client object - A user-profile argument that contains user data When: - The user is disabled in the application - allow-enable argument is true - Calling function update_user_command Then: - Ensure the user is enabled at the end of the command execution. """ client = mock_client() args = { "user-profile": {"email": "testdemisto2@paloaltonetworks.com", "givenname": "mock_first_name"}, "allow-enable": "true", } mocker.patch.object(client, "get_user", return_value=DISABLED_USER_APP_DATA) mocker.patch.object(client, "update_user", return_value=USER_APP_DATA) user_profile = IAMCommand(get_user_iam_attrs=["email"]).update_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.UPDATE_USER assert outputs.get("success") is True assert outputs.get("active") is True assert outputs.get("id") == "mock_id" assert outputs.get("username") == "mock_user_name" assert outputs.get("details", {}).get("first_name") == "mock_first_name" assert outputs.get("details", {}).get("last_name") == "mock_last_name" def test_disable_user_command__non_existing_user(mocker): """ Given: - An app client object - A user-profile argument that contains an email of a user When: - create-if-not-exists parameter is unchecked - The user does not exist in the application - Calling function disable_user_command Then: - Ensure the command is considered successful and skipped """ client = mock_client() args = {"user-profile": {"email": "testdemisto2@paloaltonetworks.com"}} mocker.patch.object(client, "get_user", return_value=None) user_profile = IAMCommand().disable_user(client, args) outputs = get_outputs_from_user_profile(user_profile) assert outputs.get("action") == IAMActions.DISABLE_USER assert outputs.get("success") is True assert outputs.get("skipped") is True assert outputs.get("reason") == IAMErrors.USER_DOES_NOT_EXIST[1] def test_get_mapping_fields_command(mocker): """ Given: - An app client object When: - User schema in the application contains the fields 'field1' and 'field2' - Calling function get_mapping_fields_command Then: - Ensure a GetMappingFieldsResponse object that contains the application fields is returned """ client = mock_client() mocker.patch.object(client, "get_app_fields", return_value={"field1": "desc1", "field2": "desc2"}) mapping_response = get_mapping_fields(client) mapping = mapping_response.extract_mapping() assert mapping.get(IAMUserProfile.DEFAULT_INCIDENT_TYPE, {}).get("field1") == "desc1" assert mapping.get(IAMUserProfile.DEFAULT_INCIDENT_TYPE, {}).get("field2") == "desc2"