Skip to main content
Skip table of contents

Okta

LAST UPDATED: 03/18/2024

Overview

Okta's cloud-based solution enables businesses to manage and secure user authentication into applications, while empowering developers to create identity controls for their applications, websites, web services, and devices. D3 SOAR's integration with Okta's Identity Access Management Service allows for the execution of CRUD operations on user lifecycle processes.

For example, you can use Okta to allow your users to sign in to other applications instead of requiring them to remember separate sets of credentials for each application or service. Users can simply sign in once and access your full suite of applications.

Okta is available for use in:

D3 SOAR

V12.7.83.0+

Category

Identity Access Management

Deployment Options

Option II, Option IV

Known Limitations

Okta enforces per-minute API call limits. For more information about each category, refer to Rate limits overview | Okta Developer. If any org-wide rate limit is surpassed, an HTTP 429 status code will be returned. To upgrade your account, please visit Pricing | Okta.

Connection

To connect to Okta from D3 SOAR, please follow this part to collect the required information below:

Parameter

Description

Example

Server URL

The server URL of your Okta instance.

https://*****.com

API Token

The API token to authenticate the connection.

00Uu*********************ZPDN

API Version

The version of the API to use for the connection.

v1

Permission Requirements

Each endpoint in the Okta API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command

Required Permission (Any permission listed)

Activates Users

Group Admin/Organization Admin/Super Admin

Add Users To Group

Group Admin/Group Membership Administrator/Organization Admin/Super Admin

Block IPs

Read-only Admin/Organization Admin/Super Admin

Create User In Group

Group Admin/Organization Admin/Super Admin

Create Zone

Organization Admin/Super Admin

Deactivate Users

Group Admin/Organization Admin/Super Admin

Delete Zones

Read-only Admin/Super Admin

Fetch Event

Read-only Admin/Organization Admin/Super Admin

Get Groups

Group Admin/Group Membership Administrator/Read-only Admin/Organization Admin/Super Admin

Get Logs

Group Admin/Read-only Admin/Organization Admin/Super Admin

Get User Groups

Group Admin/Group Membership Administrator/Read-only Admin/Organization Admin/Super Admin

Get Users

Group Admin/Group Membership Administrator/Read-only Admin/Organization Admin/Super Admin

Get Group Members

Group Admin/Group Membership Administrator/Read-only Admin/Organization Admin/Super Admin

List Zones

Read-only Admin//Organization Admin/Super Admin

Reset User Passwords

Group Admin/Organization Admin/Super Admin

Update Zone

Organization Admin/Super Admin

Test Connection

Group Admin/Group Membership Administrator/Read-only Admin/Organization Admin/Super Admin

As Okta is using role-based access control (RBAC), the API access token is generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the Okta console for each command in this integration.

READER NOTE

Okta User Management (permissions not listed in any particular order)

  • Super Admin: Perform all admin activities for an org. Super admins have full management access

  • Org Admin: Perform most admin activities for an org. Note: Org admins cannot manage applications, authorization servers, hooks, Okta Mobile, or other admins.

  • Group Admin: Manage users, their profiles, and their credentials. Note: You can specify one or more groups after selecting this role.

  • App Admin: View and manage user permissions in an application. Note: You can specify one or more applications after selecting this role.

  • Read-Only Admin: View most data in the Admin Console.

  • Mobile Admin: perform actions related to mobile policies, sign-on policies, mobile devices, and Okta Mobile.

  • Help Desk Admin: View and unlock users, reset passwords and reset MFA. Note: You can specify one or more groups after selecting this role.

  • Report Admin: View all reports and the System log.

  • API Access Management Admin: Build custom authorization servers to protect your API endpoints.

  • Group Membership Admin: Manages the membership of groups. Note: You can specify one or more groups after selecting this role.

Please refer to Okta Standard administrator roles and permissions and Learn about administrators for more details.

Configuring Okta to Work with D3 SOAR

  1. Login to Okta (https://<subdomain>.okta.com). To locate your sign-in URL, look in the address bar of your desktop browser, the sign-in URL is the web address you use in your desktop browser to access your company portal.

  2. On the left side menu, go to Security > API

  3. Select the Tokens tab, then Create Token. A Create Token window will appear.

  4. Enter the Token Name, then click Create Token.

  5. The generated token will appear. Copy and store the token in a secure location.

READER NOTE

This is the only time that you will be able to view the token, please store it to a secure location.

  1. To create users with specific roles, follow the steps below:

a. Log in to Okta using a Super Administrator account. On the top left corner of your screen, select Directory > People.

b. Click Add person.

c. Fill in the required user information and click Save.

READER NOTE

Your password must meet the following requirements: at least 8 characters, cannot include any part of your username, and cannot be one of your last four passwords.

d. Locate the created user from the user list, and click Add Individual admin privileges.

e. Use the dropdown menu to assign a role to the user and click Save Changes. You can always modify the user's role later.

f. You may log out of the super admin account and log into the created account. Follow steps 2 to 4 of this section for instructions on creating an API token.

Configuring D3 SOAR to Work with Okta

  1. Log in to D3 SOAR.

  2. Find the Okta integration.

a. Navigate to Configuration on the top header menu.

b. Click on the Integration icon on the left sidebar.

c. Type Okta in the search box to find the integration, then click it to select it.

d. Click + Connection, on the right side of the Connections section. A new connection window will appear.

  1. Configure the following fields to create a connection to Okta.

a. Connection Name: The desired name for the connection.

b. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.

c. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.

d. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.

e. Description (Optional): Add your desired description for the connection.

f. Configure User Permissions: Defines which users have access to the connection.

g. Active: Check the tick box to ensure the connection is available for use.

h. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.

1. Input your domain level Server URL.

2. Input your saved API Token.

3. Input your API Version.

i. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.

To set up a connection health check, check the Connection Health Check tick box. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.

j. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.

  1. Test the connection.

a. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green check mark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.

b. Click OK to close the alert window.

c. Click Add to create and add the configured connection.

Commands

Okta includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Okta API, please refer to the Okta API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Okta to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

  1. Navigate to Configuration > Application Settings. Select Date/Time Format.

  2. Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Activates Users

Activates the specified users. This operation can only be performed on users with a STAGED or DEPROVISIONED status. The activation of a user is an asynchronous operation.

READER NOTE

  • Users who have not configured a password must complete the activation process by visiting the activation link. However, if the user account has the optional password setting enabled, it is optional for the user to use the activation link. For more information, please refer to the Okta API document.

  • If the status is Stage, running the command will change your status to Pending user action on Okta UI. Go to your user inbox to complete the activation process.

  • If the status is DEPROVISIONED, it means the user account has been deactivated. To reactivate an account, run the command to change the status to Stage. Make sure to click on Active Person or run the command for a second time. Your status will then change to Pending user action on Okta UI, and you will receive an email with instructions to complete the activation process. Failure to complete the activation process will result in the inability to login to the account after a certain time period.

    The input parameter User IDs is required to run this command.

  • Run the Get Users command to obtain the User IDs. User IDs can be obtained from the returned raw data at the path $[*].id.

Input

Input Parameter

Required/Optional

Description

Example

User IDs

Required

The IDs of the users to activate. User IDs can be obtained using the Get Users command.

00u******************5d7

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Okta API response by adding the userID and actionResult fields.

SAMPLE DATA

CODE 
[
    {
        "userID": "*****",
        "actionResult": "Activate the user successfully"
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
  "UserIDs": [
      "*****"
  ],
  "ActivationUrls": [
      "https://*****.okta.com/*****"
  ],
  "ActivationTokens": [
      "*****"
  ]
}
Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

userID

actionResult

*****

Activate the user successfully

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Activates Users failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta API Error Codes for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: User ID Not Found.

Error Sample Data

Activates Users failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: User ID Not Found.

Add Users To Group

Adds the specified users to a group with the OKTA_GROUP type.

READER NOTE

User IDs and Group ID are required parameters to run this command.

Run the Get Users command to obtain the User IDs. User IDs can be found from the returned raw data at the path $[*].id.

Run the Get Groups command to obtain the Group ID. Group ID can be found from the returned raw data at the path $.id.

Alert

  • When adding a user, ensure that they are not already a member of the input group. Otherwise, an error indicating that the user is already in the group will be returned.

  • It is not possible to add a user to a built-in group. When retrieving a group, make sure that the group's "type" field is set to "OKTA_GROUP"; if the type is "BUILT_IN", the operation cannot be performed. You can find the group type in the raw data returned by the Get Groups command, at the path $.type.

Input

Input Parameter

Required/Optional

Description

Example

User IDs

Required

The IDs of the users to add to the group. User IDs can be obtained using the Get Users command. Note: You cannot add a deprovisioned user to a group.

[ "00u*************5d7" ]

Group ID

Required

The ID of the group to add users. Group ID can be obtained using the Get Groups command. Note: You cannot add users to a built-in group.

00g*****************5d7

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Okta API response by adding the userID and actionResult fields.

SAMPLE DATA

CODE 
[
    {
        "userID": "*****",
        "actionResult": "Added the user to group successfully"
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
  "UserIDs": [
      "*****"
  ]
}
Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

userID

actionResult

*****

Added the user to group successfully

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Add Users To Group failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: User ID Not Found.

Error Sample Data

Add Users To Group failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: User ID Not Found.

Block IPs

Blocks the specified IP addresses in a network zone.

READER NOTE

Zone ID is a required parameter to run this command.

  • Run the List Zones command to obtain Zone ID. Zone IDs can be found in the returned raw data at the path $[*].id.

  • When retrieving a zone, make sure that the zone's "type" field is set to "IP" and "usage" field is set to "BLOCKLIST". You can find the zone type in the raw data returned by the List Zones command, at the path $[*].type; you can find the zone usage in the raw data returned by the List Zones command, at the path $[*].usage.

Input

Input Parameter

Required/Optional

Description

Example

Zone ID

Required

The ID of the network zone to block the IP addresses. The specified zone's type must be IP and its usage must be set to Blocklist. Zone IDs can be obtained using the List Zones command.

nzo***************5d7

IP Addresses

Required

The IP addresses to block by the specified zone. The values may take the form of IP Addresses in the format of ***.***.***.***, ***.***.***.***/**, or ***.***.***.***-***.***.***.***.

[ "***.***.***.***", "***.***.***.***/**", "***.***.***.***-***.***.***.***" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "type": "IP",
    "id": "*****",
    "name": "*****",
    "status": "ACTIVE",
    "usage": "BLOCKLIST",
    "created": "2022-08-31T18:09:27.000Z",
    "lastUpdated": "2022-09-06T20:35:04.000Z",
    "system": false,
    "gateways": [
        {
            "type": "CIDR",
            "value": "***.***.***.***/**"
        },
        {
            "type": "CIDR",
            "value": "***.***.***.***/**"
        },
        {
            "type": "RANGE",
            "value": "***.***.***.***-***.***.***.***"
        },
        {
            "type": "RANGE",
            "value": "***.***.***.***-***.***.***.***"
        }
    ],
    "proxies": null,
    "_links": {
        "self": {
            "href": "https://*****.okta.com/*****",
            "hints": {
                "allow": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        },
        "deactivate": {
            "href": "https://*****.okta.com/*****/***/***",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "ZoneID": "*****",
    "blockedIPs": [
    "***.***.***.***/**",
    "***.***.***.***-***.***.***.***",
    "***.***.***.***",
    "***.***.***.***/**",
    "***.***.***.***-***.***.***.***"
    ]
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE 
No Sample Data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Block IPs failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Zone ID Not Found.

Error Sample Data

Block IPs failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: Zone ID Not Found.

Create User In Group

Creates a user and adds the user to a group.

READER NOTE

The input parameter Group IDs is required to run this command.

  • Run the Get Groups command to obtain the Group IDs. Group ID can be found from the returned raw data at the path $.id.

When you use this command to create a user, their status will be set to Staged. To complete the activation process, you can click Activate in the Okta user interface or run the Activate Users command, and then verify the user's email inbox.

Input

Input Parameter

Required/Optional

Description

Example

First Name

Required

The first name of the user.

*****

Last Name

Required

The last name of the user.

*****

Email

Required

The email address of the user. Note: The email address must be valid.

*****@*****.com

Phone Number

Optional

The phone number of the user.

***-***-****

Group IDs

Required

The IDs of the groups to which the user is added. Group IDs can be obtained using the Get Groups command.

[ "*************" ]

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Okta API response by adding the userID and actionResult fields.

SAMPLE DATA

CODE 
{
    "id": "***********",
    "status": "STAGED",
    "created": "2021-11-13T00:38:33.000Z",
    "activated": null,
    "statusChanged": null,
    "lastLogin": null,
    "lastUpdated": "2021-11-13T00:38:33.000Z",
    "passwordChanged": null,
    "type": {
        "id": "***********"
    },
    "profile": {
        "firstName": "*****",
        "lastName": "*****",
        "mobilePhone": null,
        "secondEmail": null,
        "login": "*****@*****.com",
        "email": "*****@*****.com"
    },
    "credentials": {
        "emails": [
            {
                "value": "*****@*****.com",
                "status": "VERIFIED",
                "type": "PRIMARY"
            }
        ],
        "provider": {
            "type": "OKTA",
            "name": "OKTA"
        }
    },
    "_links": {
        "schema": {
            "href": "https://*****.okta.com/api/v1/*****"
        },
        "activate": {
            "href": "https://*****.okta.com/api/v1/*****",
            "method": "POST"
        },
        "self": {
            "href": "https://*****.okta.com/api/v1/*****"
        },
        "type": {
            "href": "https://*****.okta.com/api/v1/*****"
        }
    }
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "UserID": "*****",
    "Status": "STAGED"
}
Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

id

***********

status

STAGED

created

2021-11-13T00:38:33.000Z

activated

None

statusChanged

None

lastLogin

None

lastUpdated

2021-11-13T00:38:33.000Z

passwordChanged

None

type

{'id': '***********'}

profile

{'firstName': 'Test', 'lastName': 'User1', 'mobilePhone': None, 'secondEmail': None, 'login': '*****@*****.com', 'email': '*****@*****.com'}

credentials

{'emails': [{'value': '*****@*****.com', 'status': 'VERIFIED', 'type': 'PRIMARY'}], 'provider': {'type': 'OKTA', 'name': 'OKTA'}}

_links

{'schema': {'href': 'https://*****.okta.com/api/v1/******'}, 'activate': {'href': 'https://*****.okta.com/api/v1/******', 'method': 'POST'}, 'self': {'href': 'https://*****.okta.com/api/v1/******'}, 'type': {'href': 'https://*****.okta.com/api/v1/******'}}

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Create User In Group failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Group ID Not Found.

Error Sample Data

Create User In Group failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: Group ID Not Found.

Create Zone

Creates a new network zone.

Input

Input Parameter

Required/Optional

Description

Example

Zone Name

Required

The unique name of the zone. The name can have a maximum length of 128 characters, any characters exceeding the limit will be truncated.

blockListNetworkZone

Zone Type

Optional

The type (i.e., Policy or Dynamic) of the zone. The default value is IP.

IP

Zone Usage

Optional

The usage (i.e., Policy or Blocklist) of the zone. The default value is Blocklist.

Blocklist

IP Zone Gateway Addresses

Optional

The IP addresses to act as the gateway for the zone. The values may take the form of IP Addresses in the format of ***.***.***.***, ***.***.***.***/**, or ***.***.***.***-***.***.***.***. Note: This parameter is required when the Zone Type is set to IP and Zone Usage is Blocklist. At least one of the parameters IP Zone Gateway Addresses or IP Zone Proxy Addresses must be defined.

[ "***.***.***.***", "***.***.***.***/**", "***.***.***.***-***.***.***.***" ]

IP Zone Proxy Addresses

Optional

The IP addresses to act as the proxy addresses for the zone. The values may take the form of IP Addresses in the format of ***.***.***.***, ***.***.***.***/**, or ***.***.***.***-***.***.***.***. Note: At least one of the parameters IP Zone Gateway Addresses or IP Zone Proxy Addresses must be defined.

[ "***.***.***.***", "***.***.***.***/**", "***.***.***.***-***.***.***.***" ]

Dynamic Zone Proxy Type

Optional

The proxy type of the dynamic zone. The available proxy types are None, Any, Tor Anonymizer and Not Tor Anonymizer. This parameter is only used when the Zone Type is set to Dynamic.

Any

Dynamic Zone Locations

Optional

The list of location objects containing country and region information (formatted as "country-regionKey") for the zone. Each location object includes an ISO-3166-1 country code and an optional ISO-3166-2 region code. This parameter is only used when the Zone Type is set to Dynamic. For example, the parameter can be formatted as follows: [{"country":"AX"},{"country":"AF","region":"AF-BGL"}].

[
{
"country": "AX"
},
{
"country": "AF",
"region": "AF-BGL"
}
]

Dynamic Zone ASNs

Optional

The ANS numeric value for the zone. This parameter is only used when the Zone Type is set to Dynamic.

[*****, *****]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "type": "IP",
    "id": "*****",
    "name": "blockListNetworkZone",
    "status": "ACTIVE",
    "usage": "BLOCKLIST",
    "created": "2022-08-31T18:15:39.000Z",
    "lastUpdated": "2022-08-31T18:15:39.000Z",
    "system": false,
    "gateways": [
        {
            "type": "CIDR",
            "value": "***.***.***.***/**"
        },
        {
            "type": "CIDR",
            "value": "***.***.***.***/**"
        }
    ],
    "proxies": null,
    "_links": {
        "self": {
            "href": "https://*****.okta.com/api/v1/*****",
            "hints": {
                "allow": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        },
        "deactivate": {
            "href": "https://*****.okta.com/api/v1/*****",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "ZoneID": "*****",
    "ZoneType": "STAGED",
    "ZoneUsage": "BLOCKLIST"
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

createdZoneCount

1

zoneID

*****

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Create Zone failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Status Code: E0000011.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Invalid token provided.

Error Sample Data

Create Zone failed.

Status Code: E0000011.

HTTP Status Code: 404.

Message: Invalid token provided.

Deactivate Users

Deactivates the specified users. This operation can only be performed on users that do not have a DEPROVISIONED status.

READER NOTE

The input parameter User IDs is required to run this command.

Run Get Users to obtain the Users IDs. User IDs can be found in the returned raw data at the path $[*].id.

WARNING

  • Please be careful when deactivating the users. As an administrator with proper permission set up, you can deactivate all users (even higher privilege users like superadmin).

  • Deactivated users cannot be listed by the Get Users command.

  • This operation can only be performed on users that do not have a DEPROVISIONED status. You can check user's status by running Get Users command, at the path $.status

  • Deactivating a user is a destructive operation. The user is deprovisioned from all assigned applications which may destroy their data such as email or files. This action cannot be recovered!

Please refer to Okta API document for details.

Input

Input Parameter

Required/Optional

Description

Example

User IDs

Required

The IDs of the users to deactivate. User IDs can be obtained using the Get Users command.

["00u*************5d7"]

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Okta API response by adding the userID and actionResult fields.

SAMPLE DATA

CODE 
[
    {
        "userID": "*****",
        "actionResult": "Deactivate the user successfully"
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "UserIDs": "*****",
    "Statuses": "Deactivated"
}
Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

userID

actionResult

*****

Deactivate the user successfully

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Deactivate Users failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: User ID Not Found.

Error Sample Data

Deactivate Users failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: User ID Not Found.

Delete Zones

Deletes the specified non-system network zones.

READER NOTE

The input parameter Zone IDs is required to run this command.

  • Run the List Zones command to obtain Zone IDs. Zone IDs can be found in the returned raw data at the path $[*].id.

Input

Input Parameter

Required/Optional

Description

Example

Zone IDs

Required

The IDs of the network zones to delete. Zone IDs can be obtained using the List Zones command. Note: Only non-system zones can be deleted.

[ "nzo****************5d7", "nzo****************5d7" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "zoneID": "*****",
        "message": "Zone deleted successfully."
    },
    {
        "zoneID": "*****",
        "errorCode": "E0000001",
        "errorSummary": "Api validation failed: id",
        "errorLink": "E0000001",
        "errorId": "*****",
        "errorCauses": [
            {
                "errorSummary": "id: The zone: ***** is a legacy zone. Legacy zone cannot be deleted."
            }
        ]
    }
]
Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

successfulCount

1

failedCount

2

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Delete Zones failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Zone ID Not Found.

Error Sample Data

Delete Zones failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: Zone ID Not Found.

Fetch Event

Retrieves events from Okta based on the specified criteria. Events (system logs) are retained by Okta for 90 days. Invoking queries with the time range exceeding the retention period will be successful, but only results with a published timestamp within the timeframe will be returned. Note: Events are fetched by creation time.

Input

Input Parameter

Required /Optional

Description

Example

Start Time

Required

The start time of the time range (by creation time) to fetch events in UTC time.

2023-03-02 00:00

End Time

Optional

The end time of the time range (by creation time) to fetch events in UTC time.

2023-03-10 00:00

Number of Event(s) Fetched

Optional

The maximum number of events to return. When the value is 0, a negative number, or not specified, the command will return all events in the given time range. Note: If the input value is too large, it may affect system performance when returning a large number of events. In this situation, please set a suitable value to limit the number of returned events.

50

Search Condition

Optional

The query expression to filter results. For more information about the query syntax, see System Log API.

eventType eq "user.account.reset_password"

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "actor": {
            "id": "*****",
            "type": "User",
            "alternateId": "*****@***.com",
            "displayName": "*****",
            "detailEntry": null
        },
        "client": {
            "userAgent": {
                "rawUserAgent": "***/*.* (***; ***; ***) AppleWebKit/***.*** (KHTML, like Gecko) ***/***.***.***.*** ***/***.***",
                "os": "Windows 10",
                "browser": "***"
            },
            "zone": "null",
            "device": "Computer",
            "id": null,
            "ipAddress": "***.***.***.***",
            "geographicalContext": {
                "city": "Vancouver",
                "state": "British Columbia",
                "country": "Canada",
                "postalCode": "V6B",
                "geolocation": {
                    "lat": 49.282,
                    "lon": -123.1103
                }
            }
        },
        "device": null,
        "authenticationContext": {
            "authenticationProvider": null,
            "credentialProvider": null,
            "credentialType": null,
            "issuer": null,
            "interface": null,
            "authenticationStep": 0,
            "externalSessionId": "*****"
        },
        "displayMessage": "Fired when the user's Okta password is reset",
        "eventType": "user.account.reset_password",
        "outcome": {
            "result": "SUCCESS",
            "reason": null
        },
        "published": "2021-11-13T00:22:47.599Z",
        "securityContext": {
            "asNumber": *****,
            "asOrg": "skyway west",
            "isp": "skyway west",
            "domain": "*****.ca",
            "isProxy": false
        },
        "severity": "INFO",
        "debugContext": {
            "debugData": {
                "requestId": "*****@*****",
                "requestUri": "/api/v1/***/***/***",
                "threatSuspected": "false",
                "url": "/api/v1/***/***/***?"
            }
        },
        "legacyEventType": "core.user_auth.self_service.password_reset",
        "transaction": {
            "type": "WEB",
            "id": "*****@*****",
            "detail": {}
        },
        "uuid": "*****",
        "version": "0",
        "request": {
            "ipChain": [
                {
                    "ip": "***.***.***.***",
                    "geographicalContext": {
                        "city": "Vancouver",
                        "state": "British Columbia",
                        "country": "Canada",
                        "postalCode": "V6B",
                        "geolocation": {
                            "lat": 49.282,
                            "lon": -123.1103
                        }
                    },
                    "version": "V4",
                    "source": null
                }
            ]
        },
        "target": [
            {
                "id": "*****",
                "type": "User",
                "alternateId": "*****@***.com",
                "displayName": "*****",
                "detailEntry": null
            }
        ]
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "LogIDs": ["*****"],
    "EventTypes": ["user.account.reset_password"],
    "ActorNames": ["sysint D3"],
    "ActorIDs": ["*****"],
    "ClientIpAddresses": ["***.***.***.***"],
    "Severities": ["INFO"]
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

actor

client

device

authenticationContext

displayMessage

eventType

outcome

published

securityContext

severity

debugContext

legacyEventType

transaction

uuid

version

request

target

{'id': '*****', 'type': 'User', 'alternateId': '*****@*****.com', 'displayName': 'sysint D3', 'detailEntry': None}

{'userAgent': {'rawUserAgent': '*****/*.* (***; ***; ***) AppleWebKit/***.*** (KHTML, like Gecko) ***/***.***.***.*** ***/***.***', 'os': 'Windows 10', 'browser': '***'}, 'zone': 'null', 'device': 'Computer', 'id': None, 'ipAddress': '***.***.***.***', 'geographicalContext': {'city': 'Vancouver', 'state': 'British Columbia', 'country': 'Canada', 'postalCode': 'V6B', 'geolocation': {'lat': 49.282, 'lon': -123.1103}}}

None

{'authenticationProvider': None, 'credentialProvider': None, 'credentialType': None, 'issuer': None, 'interface': None, 'authenticationStep': 0, 'externalSessionId': '*****'}

Fired when the user's Okta password is reset

user.account.reset_password

{'result': 'SUCCESS', 'reason': None}

2021-11-13T00:22:47.599Z

{'asNumber': *****, 'asOrg': 'skyway west', 'isp': 'skyway west', 'domain': 'http://hplaw.ca ', 'isProxy': False}

INFO

{'debugData': {'requestId': '*****@*****', 'requestUri': '/api/v1/***/***/***', 'threatSuspected': 'false', 'url': '/api/v1/***/***/***?'}}

core.user_auth.self_service.password_reset

{'type': 'WEB', 'id': '*****@*****', 'detail': {}}

*****

0

{'ipChain': [{'ip': '***.***.***.***', 'geographicalContext': {'city': 'Vancouver', 'state': 'British Columbia', 'country': 'Canada', 'postalCode': 'V6B', 'geolocation': {'lat': 49.282, 'lon': -123.1103}}, 'version': 'V4', 'source': None}]}

[{'id': '*****', 'type': 'User', 'alternateId': '*****@*****.com', 'displayName': 'sysint D3', 'detailEntry': None}]

Fetch Event Field Mapping

Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.

If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

As a system integration, the Okta integration has some pre-configured field mappings for default field mapping.

  • Default Event Source
    The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events. The default event source has a “Main Event JSON Path” (i.e., $) that is used to extract a batch of events from the response raw data. Click Edit Event Source to view the “Main Event JSON Path”.

    • Main Event JSON Path: $.data
      The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays. For example, the root node of a JSON Path is $. The child node denoting the Unique Event Key field would be uuid. Putting it together, the JSON Path expression to extract the Unique Event Key is $.uuid.

The pre-configured field mappings are detailed below:

Field Name

Source Field

Device IP address

.client.ipAddress

Unique Event Key

.uuid

Event Type

.eventType

HTTP user agent

.client.userAgent.rawUserAgent

Start Time

.published

Description

.displayMessage

Log username

.actor.displayName

Severity

.severity

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Fetch Event failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000047.

HTTP Status Code: 429.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: API call exceeded rate limit due to too many requests.

Error Sample Data

Fetch Event failed.

Okta Code: E0000047.

HTTP Status Code: 429.

Message: API call exceeded rate limit due to too many requests.

Get Groups

List groups in your organization with the specified search condition.

Input

Input Parameter

Required/Optional

Description

Example

Filter

Optional

The expression to filter results. For more information about the syntax, see Core Okta API.

type eq "OKTA_GROUP" and lastUpdated gt "2021-11-13T00:30:00.000Z"

Limit

Optional

The maximum number of results to return. The default value is 100. Note: If the input value is too large, it may affect system performance when returning a large number of results. In this situation, please set a suitable value to limit the number of returned results.

100

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "id": "*****",
        "created": "2021-11-13T00:32:00.000Z",
        "lastUpdated": "2021-11-13T00:32:00.000Z",
        "lastMembershipUpdated": "2021-11-13T00:57:51.000Z",
        "objectClass": [
            "okta:user_group"
        ],
        "type": "OKTA_GROUP",
        "profile": {
            "name": "Super Users Group",
            "description": "All Super Users West of The Rockies"
        },
        "_links": {
            "logo": [
                {
                    "name": "medium",
                    "href": "https://***.oktacdn.com/***/*****.png",
                    "type": "image/png"
                },
                {
                    "name": "large",
                    "href": "https://***.oktacdn.com/***/*****.png",
                    "type": "image/png"
                }
            ],
            "users": {
                "href": "https://*****.okta.com/api/v1/*****"
            },
            "apps": {
                "href": "https://*****.okta.com/api/v1/*****"
            }
        }
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
  "GroupIDs": ["*****"],
  "GroupTypes": ["OKTA_GROUP"],
  "GroupNames": [ "*****" ]
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

id

created

lastUpdated

lastMembershipUpdated

objectClass

type

profile

_links

*****

2021-11-13T00:32:00.000Z

2021-11-13T00:32:00.000Z

2021-11-13T00:57:51.000Z

['okta:user_group']

OKTA_GROUP

{'name': 'Super Users Group', 'description': 'All Super Users West of The Rockies'}

{'logo': [{'name': 'medium', 'href': 'https://***.oktacdn.com/***/*****.png', 'type': 'image/png'}, {'name': 'large', 'href': 'https://***.oktacdn.com/***/*****.png', 'type': 'image/png'}], 'users': {'href': 'https://*****.okta.com/api/v1/*****'}, 'apps': {'href': 'https://*****.okta.com/api/v1/*****'}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get Groups failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000031.

Status Code: 403.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Invalid Filter expression.

Error Sample Data

Get Groups failed.

Okta Code: E0000031.

Status Code: 403.

Message: Invalid Filter expression.

Get Logs

Retrieves system logs from Okta based on the specified criteria. System logs are retained by Okta for 90 days. Invoking queries with the time range exceeding the retention period will be successful, but only results with a published timestamp within the timeframe will be returned.

Input

Input Parameter

Required/Optional

Description

Example

Filter

Optional

The expression to filter results. For more information about the syntax, see System Log API.

eventType eq "user.account.reset_password"

Limit

Optional

The maximum number of results to return. The default value is 100. Note: If the input value is too large, it may affect system performance when returning a large number of results. In this situation, please set a suitable value to limit the number of returned results.

100

Start Time

Optional

The start time (in UTC) of the time range to filter results by the log events' published property or persistence time for bounded or polling queries.

2023-03-01 00:00

End Time

Optional

The end time (in UTC) of the time range to filter results by the log events' published property or persistence time for bounded or polling queries.

2023-03-10 00:00

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "actor": {
            "id": "*****",
            "type": "User",
            "alternateId": "*****@*****.com",
            "displayName": "*****",
            "detailEntry": null
        },
        "client": {
            "userAgent": {
                "rawUserAgent": "***/*.* (***; ***; ***) AppleWebKit/537.36 (KHTML, like Gecko) ***/*.*.*.* ***/***.***",
                "os": "Windows 10",
                "browser": "CHROME"
            },
            "zone": "null",
            "device": "Computer",
            "id": null,
            "ipAddress": "***.***.***.***",
            "geographicalContext": {
                "city": "Vancouver",
                "state": "British Columbia",
                "country": "Canada",
                "postalCode": "V6B",
                "geolocation": {
                    "lat": 49.282,
                    "lon": -123.1103
                }
            }
        },
        "device": null,
        "authenticationContext": {
            "authenticationProvider": null,
            "credentialProvider": null,
            "credentialType": null,
            "issuer": null,
            "interface": null,
            "authenticationStep": 0,
            "externalSessionId": "*****"
        },
        "displayMessage": "Fired when the user's Okta password is reset",
        "eventType": "user.account.reset_password",
        "outcome": {
            "result": "SUCCESS",
            "reason": null
        },
        "published": "2021-11-13T00:22:47.599Z",
        "securityContext": {
            "asNumber": 14007,
            "asOrg": "skyway west",
            "isp": "skyway west",
            "domain": "hplaw.ca",
            "isProxy": false
        },
        "severity": "INFO",
        "debugContext": {
            "debugData": {
                "requestId": "*****@*****",
                "requestUri": "/api/v1/***/***/***",
                "threatSuspected": "false",
                "url": "/api/v1/***/***/***?"
            }
        },
        "legacyEventType": "core.user_auth.self_service.password_reset",
        "transaction": {
            "type": "WEB",
            "id": "*****@*****",
            "detail": {}
        },
        "uuid": "*****",
        "version": "0",
        "request": {
            "ipChain": [
                {
                    "ip": "***.***.***.***",
                    "geographicalContext": {
                        "city": "Vancouver",
                        "state": "British Columbia",
                        "country": "Canada",
                        "postalCode": "V6B",
                        "geolocation": {
                            "lat": 49.282,
                            "lon": -123.1103
                        }
                    },
                    "version": "V4",
                    "source": null
                }
            ]
        },
        "target": [
            {
                "id": "*****",
                "type": "User",
                "alternateId": "*****@*****.com",
                "displayName": "*****",
                "detailEntry": null
            }
        ]
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "LogIDs": "*****",
    "EventTypes": ["user.account.reset_password"],
    "ActorNames": [ "*****" ],
    "ActorIDs": ["*****"],
    "ClientIpAddresses": ["***.***.***.***"],
    "Severities": ["INFO"]
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

actor

client

device

authenticationContext

displayMessage

eventType

outcome

published

securityContext

severity

debugContext

legacyEventType

transaction

uuid

version

request

target

{'id': '*****', 'type': 'User', 'alternateId': '*****@*****.com', 'displayName': 'sysint D3', 'detailEntry': None}

{'userAgent': {'rawUserAgent': '***/*.* (***; ***; ***) AppleWebKit/537.36 (KHTML, like Gecko) ***/*.*.*.* ***/***.***', 'os': 'Windows 10', 'browser': 'CHROME'}, 'zone': 'null', 'device': 'Computer', 'id': None, 'ipAddress': '***.***.***.***', 'geographicalContext': {'city': 'Vancouver', 'state': 'British Columbia', 'country': 'Canada', 'postalCode': 'V6B', 'geolocation': {'lat': 49.282, 'lon': -123.1103}}}

None

{'authenticationProvider': None, 'credentialProvider': None, 'credentialType': None, 'issuer': None, 'interface': None, 'authenticationStep': 0, 'externalSessionId': '*****'}

Fired when the user's Okta password is reset

user.account.reset_password

{'result': 'SUCCESS', 'reason': None}

2021-11-13T00:22:47.599Z

{'asNumber': 14007, 'asOrg': 'skyway west', 'isp': 'skyway west', 'domain': 'http://hplaw.ca ', 'isProxy': False}

INFO

{'debugData': {'requestId': '*****@*****', 'requestUri': '/api/v1/***/***/***', 'threatSuspected': 'false', 'url': '/api/v1/***/***/***?'}}

core.user_auth.self_service.password_reset

{'type': 'WEB', 'id': '*****@*****', 'detail': {}}

*****

0

{'ipChain': [{'ip': '***.***.***.***', 'geographicalContext': {'city': 'Vancouver', 'state': 'British Columbia', 'country': 'Canada', 'postalCode': 'V6B', 'geolocation': {'lat': 49.282, 'lon': -123.1103}}, 'version': 'V4', 'source': None}]}

[{'id': '*****', 'type': 'User', 'alternateId': '*****@*****.com', 'displayName': 'sysint D3', 'detailEntry': None}]

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get Logs failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000031.

Status Code: 403.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Invalid Filter expression.

Error Sample Data

Get Logs failed.

Okta Code: E0000031.

Status Code: 403.

Message: Invalid Filter expression.

Get User Groups

Retrieves user groups in which the specified user is a member.

READER NOTE

User ID Or Login Name is a required parameter to run this command.

  • Run the Get Users command to obtain User ID Or Login Name. User ID can be found from the returned raw data at the path $[*].id; Login Name can be found from the returned raw data at the path $[*].profile.login.

Input

Input Parameter

Required/Optional

Description

Example

User ID Or Login Name

Required

The ID or login name of the user to retrieve user groups. User ID and Login Name can be obtained using the Get Users command.

*****@*****.com

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "id": "*****",
        "created": "2021-11-12T21:02:41.000Z",
        "lastUpdated": "2021-11-12T21:02:41.000Z",
        "lastMembershipUpdated": "2021-11-14T01:08:43.000Z",
        "objectClass": [
            "okta:user_group"
        ],
        "type": "BUILT_IN",
        "profile": {
            "name": "Everyone",
            "description": "All users in your organization"
        },
        "_links": {
            "logo": [
                {
                    "name": "medium",
                    "href": "https://***.oktacdn.com/***/***.png",
                    "type": "image/png"
                },
                {
                    "name": "large",
                    "href": "https://***.oktacdn.com/***/***.png",
                    "type": "image/png"
                }
            ],
            "users": {
                "href": "https://***.okta.com/api/v1/groups/*****/***"
            },
            "apps": {
                "href": "https://***.okta.com/api/v1/groups/*****/***"
            }
        }
    },
    {
        "id": "*****",
        "created": "2021-11-13T00:32:00.000Z",
        "lastUpdated": "2021-11-13T00:32:00.000Z",
        "lastMembershipUpdated": "2021-11-14T01:08:43.000Z",
        "objectClass": [
            "okta:user_group"
        ],
        "type": "OKTA_GROUP",
        "profile": {
            "name": "Super Users Group",
            "description": "All Super Users West of The Rockies"
        },
        "_links": {
            "logo": [
                {
                    "name": "medium",
                    "href": "https://***.oktacdn.com/***/***.png",
                    "type": "image/png"
                },
                {
                    "name": "large",
                    "href": "https://***.oktacdn.com/***/***.png",
                    "type": "image/png"
                }
            ],
            "users": {
                "href": "https://***.okta.com/api/v1/groups/*****/***"
            },
            "apps": {
                "href": "https://***.okta.com/api/v1/groups/*****/***"
            }
        }
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "GroupIDs": ["*****"],
    "GroupTypes": ["OKTA_GROUP"],
    "GroupNames": [ "*****" ]
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

id

created

lastUpdated

lastMembershipUpdated

objectClass

type

profile

_links

*****

2021-11-12T21:02:41.000Z

2021-11-12T21:02:41.000Z

2021-11-14T01:08:43.000Z

['okta:user_group']

BUILT_IN

{'name': 'Everyone', 'description': 'All users in your organization'}

{'logo': [{'name': 'medium', 'href': 'https://***.oktacdn.com/***/***.png', 'type': 'image/png'}, {'name': 'large', 'href': 'https://***.oktacdn.com/***/***.png', 'type': 'image/png'}], 'users': {'href': 'https://***.okta.com/api/v1/groups/*****/***'}, 'apps': {'href': 'https://***.okta.com/api/v1/groups/*****/***'}}

*****

2021-11-13T00:32:00.000Z

2021-11-13T00:32:00.000Z

2021-11-14T01:08:43.000Z

['okta:user_group']

OKTA_GROUP

{'name': 'Super Users Group', 'description': 'All Super Users West of The Rockies'}

{'logo': [{'name': 'medium', 'href': 'https://***.oktacdn.com/***/***.png', 'type': 'image/png'}, {'name': 'large', 'href': 'https://***.oktacdn.com/***/***.png', 'type': 'image/png'}], 'users': {'href': 'https://***.okta.com/api/v1/groups/*****/***'}, 'apps': {'href': 'https://***.okta.com/api/v1/groups/*****/***'}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get User Groups failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: User ID Not Found.

Error Sample Data

Get User Groups failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: User ID Not Found.

Get Users

Lists all users matching the filter criteria.

READER NOTE

  • This command cannot be used to retrieve deactivated users.

  • The names of certain statuses returned by Okta differ from what is shown on the user interface. While the "Stage" status remains unchanged, "Provisioned", "Active", and "Recovery" statuses are displayed as "Pending user action", "Stage", and "Password reset", respectively.

  • All input parameters in this command are optional. If no input parameters are defined, the first 100 users in Okta will be returned.

Input

Input Parameter

Required/Optional

Description

Example

Filter

Optional

The expression to filter results. For more information about the syntax, see Users API.

status eq "ACTIVE" and profile.firstName eq "sysint"

Limit

Optional

The maximum number of results to return. The default value is 100. Note: If the input value is too large, it may affect system performance when returning a large number of results. In this situation, please set a suitable value to limit the number of returned results.

100

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "id": "*****",
        "status": "ACTIVE",
        "created": "2021-11-12T23:26:44.000Z",
        "activated": "2021-11-13T00:21:59.000Z",
        "statusChanged": "2021-11-13T00:22:47.000Z",
        "lastLogin": "2021-11-13T00:22:47.000Z",
        "lastUpdated": "2021-11-13T00:22:47.000Z",
        "passwordChanged": "2021-11-13T00:22:47.000Z",
        "type": {
            "id": "*****"
        },
        "profile": {
            "firstName": "sysint",
            "lastName": "*****",
            "mobilePhone": null,
            "secondEmail": null,
            "login": "*****@*****.com",
            "email": "*****@*****.com"
        },
        "credentials": {
            "password": {},
            "emails": [
                {
                    "value": "*****@*****.com",
                    "status": "VERIFIED",
                    "type": "PRIMARY"
                }
            ],
            "provider": {
                "type": "OKTA",
                "name": "OKTA"
            }
        },
        "Roles": [
            {
                "id": "*****",
                "label": "Super Administrator",
                "type": "SUPER_ADMIN",
                "status": "ACTIVE",
                "created": "2022-08-31T14:53:49.000Z",
                "lastUpdated": "2022-08-31T14:53:49.000Z",
                "assignmentType": "USER",
                "_links": {
                    "assignee": {
                        "href": "https://*****.okta.com/api/v1/***/***"
                    }
                }
            }
        ],
        "_links": {
            "self": {
                "href": "https://*****.okta.com/api/v1/***/***"
            }
        }
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "UserIDs": ["*****"],
    "Statuses": ["ACTIVE"],
    "LoginNames": ["*****@*****.com"],
    "Emails": ["*****@*****.com"]
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

id

status

created

activated

statusChanged

lastLogin

lastUpdated

passwordChanged

type

profile

credentials

_links

*****

ACTIVE

2021-11-12T23:26:44.000Z

2021-11-13T00:21:59.000Z

2021-11-13T00:22:47.000Z

2021-11-13T00:22:47.000Z

2021-11-13T00:22:47.000Z

2021-11-13T00:22:47.000Z

{'id': '*****'}

{'firstName': 'sysint', 'lastName': 'D3', 'mobilePhone': None, 'secondEmail': None, 'login': '*****@*****.com', 'email': '*****@*****.com'}

{'password': {}, 'emails': [{'value': '*****@*****.com', 'status': 'VERIFIED', 'type': 'PRIMARY'}], 'provider': {'type': 'OKTA', 'name': 'OKTA'}}

{'self': {'href': 'https://*****.okta.com/api/v1/***/***'}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get Users failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000031.

Status Code: 403.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Invalid Filter expression.

Error Sample Data

Get Users failed.

Okta Code: E0000031.

Status Code: 403.

Message: Invalid Filter expression.

Get Group Members

List all users that are a member of the specified group.

READER NOTE

  • Group ID is a required parameter to run this command.

    • Run Get Groups command to obtain the Group ID. Group IDs can be found from the returned raw data at the path $.id.

  • The recommended page limit is 200.

  • If you receive an HTTP 500 status code, it is likely that your request has exceeded the allotted timeout. To resolve this, attempt your request again with a smaller limit. For more information, see Core Okta API.

Input

Input Parameter

Required/Optional

Description

Example

Group ID

Required

The ID of the group to retrieve members. Group IDs can be obtained using the Get Groups command.

*************

Limit

Optional

The maximum number of results to return. The default value is 100. Note: If the input value is too large, it may affect system performance when returning a large number of results. In this situation, please set a suitable value to limit the number of returned results.

100

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "id": "*****",
        "status": "DEPROVISIONED",
        "created": "2021-11-13T00:38:33.000Z",
        "activated": "2021-11-13T00:40:21.000Z",
        "statusChanged": "2021-11-13T01:20:39.000Z",
        "lastLogin": "2021-11-13T00:46:20.000Z",
        "lastUpdated": "2021-11-13T01:20:39.000Z",
        "passwordChanged": "2021-11-13T00:46:20.000Z",
        "type": {
            "id": "*****"
        },
        "profile": {
            "firstName": "*****",
            "lastName": "*****",
            "mobilePhone": null,
            "secondEmail": null,
            "login": "*****@*****.com",
            "email": "*****@*****.com"
        },
        "credentials": {
            "emails": [
                {
                    "value": "*****@*****.com",
                    "status": "VERIFIED",
                    "type": "PRIMARY"
                }
            ],
            "provider": {
                "type": "OKTA",
                "name": "OKTA"
            }
        },
        "_links": {
            "self": {
                "href": "https://*****.okta.com/api/v1/***/***"
            }
        }
    },
    {
        "id": "*****",
        "status": "ACTIVE",
        "created": "2021-11-13T00:50:47.000Z",
        "activated": "2021-11-13T01:09:15.000Z",
        "statusChanged": "2021-11-13T01:09:43.000Z",
        "lastLogin": "2021-11-13T01:09:44.000Z",
        "lastUpdated": "2021-11-13T01:09:43.000Z",
        "passwordChanged": "2021-11-13T01:09:43.000Z",
        "type": {
            "id": "*****"
        },
        "profile": {
            "firstName": "*****",
            "lastName": "*****",
            "mobilePhone": null,
            "secondEmail": null,
            "login": "*****@*****.com",
            "email": "*****@*****.com"
        },
        "credentials": {
            "password": {},
            "emails": [
                {
                    "value": "*****@*****.com",
                    "status": "VERIFIED",
                    "type": "PRIMARY"
                }
            ],
            "provider": {
                "type": "OKTA",
                "name": "OKTA"
            }
        },
        "_links": {
            "self": {
                "href": "https://*****.okta.com/api/v1/***/***"
            }
        }
    },
    {
        "id": "*****",
        "status": "DEPROVISIONED",
        "created": "2021-11-13T00:57:51.000Z",
        "activated": "2021-11-13T01:36:10.000Z",
        "statusChanged": "2021-11-13T01:49:38.000Z",
        "lastLogin": "2021-11-13T01:37:52.000Z",
        "lastUpdated": "2021-11-13T01:49:38.000Z",
        "passwordChanged": "2021-11-13T01:37:52.000Z",
        "type": {
            "id": "*****"
        },
        "profile": {
            "firstName": "admin",
            "lastName": "*****",
            "mobilePhone": "**********",
            "secondEmail": null,
            "login": "*****@*****.com",
            "email": "*****@*****.com"
        },
        "credentials": {
            "emails": [
                {
                    "value": "*****@*****.com",
                    "status": "VERIFIED",
                    "type": "PRIMARY"
                }
            ],
            "provider": {
                "type": "OKTA",
                "name": "OKTA"
            }
        },
        "_links": {
            "self": {
                "href": "https://*****.okta.com/api/v1/***/***"
            }
        }
    },
    {
        "id": "*****",
        "status": "STAGED",
        "created": "2021-11-14T01:08:43.000Z",
        "activated": null,
        "statusChanged": null,
        "lastLogin": null,
        "lastUpdated": "2021-11-14T02:02:25.000Z",
        "passwordChanged": null,
        "type": {
            "id": "*****"
        },
        "profile": {
            "firstName": "*****",
            "lastName": "*****",
            "mobilePhone": "**********",
            "secondEmail": null,
            "login": "*****@*****.com",
            "email": "*****@*****.com"
        },
        "credentials": {
            "emails": [
                {
                    "value": "*****@*****.com",
                    "status": "VERIFIED",
                    "type": "PRIMARY"
                }
            ],
            "provider": {
                "type": "OKTA",
                "name": "OKTA"
            }
        },
        "_links": {
            "self": {
                "href": "https://*****.okta.com/api/v1/***/***"
            }
        }
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "UserIDs": ["*****"],
    "Statuses": ["ACTIVE"],
    "LoginNames": ["*****@*****.com"],
    "Emails": ["*****@*****.com"]
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

id

status

created

activated

statusChanged

lastLogin

lastUpdated

passwordChanged

type

profile

credentials

_links

*****

DEPROVISIONED

2021-11-13T00:38:33.000Z

2021-11-13T00:40:21.000Z

2021-11-13T01:20:39.000Z

2021-11-13T00:46:20.000Z

2021-11-13T01:20:39.000Z

2021-11-13T00:46:20.000Z

{'id': '*****'}

{'firstName': 'Test', 'lastName': 'User1', 'mobilePhone': None, 'secondEmail': None, 'login': '*****@*****.com', 'email': '*****@*****.com'}

{'emails': [{'value': '*****@*****.com', 'status': 'VERIFIED', 'type': 'PRIMARY'}], 'provider': {'type': 'OKTA', 'name': 'OKTA'}}

{'self': {'href': 'https://*****.okta.com/api/v1/***/***'}}

*****

ACTIVE

2021-11-13T00:50:47.000Z

2021-11-13T01:09:15.000Z

2021-11-13T01:09:43.000Z

2021-11-13T01:09:44.000Z

2021-11-13T01:09:43.000Z

2021-11-13T01:09:43.000Z

{'id': '*****'}

{'firstName': 'Jianing', 'lastName': 'Yao', 'mobilePhone': None, 'secondEmail': None, 'login': '*****@*****.com', 'email': '*****@*****.com'}

{'password': {}, 'emails': [{'value': '*****@*****.com', 'status': 'VERIFIED', 'type': 'PRIMARY'}], 'provider': {'type': 'OKTA', 'name': 'OKTA'}}

{'self': {'href': 'https://*****.okta.com/api/v1/***/***'}}

*****

DEPROVISIONED

2021-11-13T00:57:51.000Z

2021-11-13T01:36:10.000Z

2021-11-13T01:49:38.000Z

2021-11-13T01:37:52.000Z

2021-11-13T01:49:38.000Z

2021-11-13T01:37:52.000Z

{'id': '*****'}

{'firstName': 'admin', 'lastName': 'D3', 'mobilePhone': '**********', 'secondEmail': None, 'login': '*****@*****.com', 'email': '*****@*****.com'}

{'emails': [{'value': '*****@*****.com', 'status': 'VERIFIED', 'type': 'PRIMARY'}], 'provider': {'type': 'OKTA', 'name': 'OKTA'}}

{'self': {'href': 'https://*****.okta.com/api/v1/***/***'}}

*****

STAGED

2021-11-14T01:08:43.000Z

None

None

None

2021-11-14T02:02:25.000Z

None

{'id': '*****'}

{'firstName': 'admin2', 'lastName': 'D3', 'mobilePhone': '**********', 'secondEmail': None, 'login': '*****@*****.com', 'email': '*****@*****.com'}

{'emails': [{'value': '*****@*****.com', 'status': 'VERIFIED', 'type': 'PRIMARY'}], 'provider': {'type': 'OKTA', 'name': 'OKTA'}}

{'self': {'href': 'https://*****.okta.com/api/v1/***/***'}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Get Group Members failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Group ID Not Found.

Error Sample Data

Get Group Members failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: Group ID Not Found.

List Zones

Lists all zones matching the filter criteria.

READER NOTE

Zone IDs and After are optional parameters to run this command.

  • You should already have the desired values on hand to run this command. If you want to know what these values represent, you may run this command with parameters empty. Zone IDs can be obtained from the returned raw data at the path $[*].id; Zone Names can be obtained from the returned raw data at the path $[*].name.

Input

Input Parameter

Required/Optional

Description

Example

Zone IDs

Optional

The IDs of the zones to retrieve.

[ "nzo****************5d7", "nzo****************5d7" ]

Zone Usage

Optional

The zone's usage (i.e., Policy or Blocklist) to filter results.

Blocklist

Limit

Optional

The maximum number of results to return. When the value is 0, a negative number, or not specified, the command will return 20 zones within the given time range. Note: If the input value is too large, it may affect system performance when returning a large number of results. In this situation, please set a suitable value to limit the number of returned results.

5

After

Optional

The name of the last zone in the returned data page. If this parameter is defined, the command will retrieve the zones following the specified zone name.

blockListNetworkZone5

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
[
    {
        "type": "IP",
        "id": "*****",
        "name": "BlockedIpZone",
        "status": "ACTIVE",
        "usage": "BLOCKLIST",
        "created": "2022-08-31T14:53:45.000Z",
        "lastUpdated": "2022-08-31T14:53:45.000Z",
        "system": true,
        "gateways": null,
        "proxies": null,
        "_links": {
            "self": {
                "href": "https://*****.okta.com/api/v1/***/***",
                "hints": {
                    "allow": [
                        "GET",
                        "PUT",
                        "DELETE"
                    ]
                }
            },
            "deactivate": {
                "href": "https://*****.okta.com/api/v1/***/***",
                "hints": {
                    "allow": [
                        "POST"
                    ]
                }
            }
        }
    }
]
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "ZoneIDs": ["*****","*****"]
    "ZoneTypes": ["IP","DYNAMIC"],
    "ZoneUsages": ["POLICY","BLOCKLIST"],
    "BlocklistZones": ["*****","*****"],
    "After": blockListNetworkZone
}
Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

ZoneCount

3

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

List Zones failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Zone ID Not Found.

Error Sample Data

List Zones failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: Zone ID Not Found.

Reset User Passwords

Resets password for a given list of users. A one-time token link can be automatically emailed to each user or returned as a response and can be distributed using a custom flow. This command will transition the users to the status of RECOVERY and the users will not be able to login or initiate a forgotten password flow until they complete the reset flow.

READER NOTE

  • The input parameter User IDs is required to run this command.

    • Run Get Users command to obtain the User IDs. User IDs can be obtained from the returned raw data at the path $[*].id.

  • This operation will change the user's status to "RECOVERY", which will prevent them from logging in or resetting their password until they complete the reset process.

  • This API can be used to switch a user with the Okta Credential Provider to a Federated Provider. However, the user will no longer be able to sign in using a password after this transition.

Input

Input Parameter

Required/Optional

Description

Example

User IDs

Required

The IDs of the users to reset passwords. User IDs can be obtained using the Get Users command.

[ "nzo***********5d7", "XE6************FxO" ]

Automatically Send Email

Optional

The option to automatically send a password reset email to the specified users, when set to True. If this parameter set to False, the generated password reset links will be returned. The default value of this parameter is True. When the Convert User To Federated User parameter is set to True, the parameter is omitted.

True

Convert User To Federated User

Optional

The option to the specified users to federated users, when set to True. If this parameter set to False, no action will occur. The default value of this parameter is False. When the Automatically Send Email parameter is set to True, the parameter is forcibly set to False.

False

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "results": [
        {
            "userID": "*****",
            "sendEmail": false,
            "resetPasswordUrl": "https://*****.okta.com/reset_password/***"
        },
        {
            "userID": "*****",
            "sendEmail": false,
            "resetPasswordUrl": "https://*****.okta.com/reset_password/***"
        }
    ],
    "errors": [
        {
            "userID": "*****",
            "failedAction": "Reset password Failed.",
            "statusCode": 403,
            "reason": "Forbidden",
            "message": {
                "errorCode": "E0000017",
                "errorSummary": "Password reset failed",
                "errorLink": "E0000017",
                "errorId": "*****,
                "errorCauses": []
            }
        }
    ]
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "UserIDs": ["*****","*****"],
    "ResetPasswordUrls": [
    "https://*****.okta.com/reset_password/***",
    "https://*****.okta.com/reset_password/***"
    ]
}
Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

passwordRestSuccessfulCount

2

passwordRestFailedCount

1

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Reset User Passwords failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: User ID Not Found.

Error Sample Data

Reset User Passwords failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: User ID Not Found.

Update Zone

Updates a network zone.

READER NOTE

Zone ID is a required parameter to run this command.

  • Run the List Zones command to obtain Zone ID. Zone ID can be found in the returned raw data at the path $[*].id.

  • A valid Zone object with the ID of the Network Zone to update is required.

  • The updated Network Zone type must be the same as the existing type.

  • You may update the usage (POLICY, BLOCKLIST) of a Network Zone by updating the usage attribute.

Zone ID is a required parameter to run this command.

  • Run the List Zones command to obtain Zone ID. Zone IDs can be found in the returned raw data at the path $[*].id.

  • A valid Zone object with the ID of the Network Zone to update is required.

  • The updated Network Zone type must be the same as the existing type.

  • You may update the usage (POLICY, BLOCKLIST) of a Network Zone by updating the usage attribute.

Input

Input Parameter

Required/Optional

Description

Example

Zone ID

Required

The ID of the zone to update. Zones IDs can be obtained using the List Zones command.

nzo***********5d7

Zone Name

Optional

The unique name of the zone. The name can have a maximum length of 128 characters, any characters exceeding the limit will be truncated.

blockListNetworkZone

Zone Usage

Optional

The usage (i.e., Policy or Blocklist) of the zone. The default value is Blocklist.

Blocklist

Is Overwrite

Optional

The option to overwrite the existing values for IP addresses, locations, or ASNs, when set to True.

False

IP Zone Gateway Addresses

Optional

The IP addresses to act as the gateway for the zone. The values may take the form of IP Addresses in the format of ***.***.***.***, ***.***.***.***/**, or ***.***.***.***-***.***.***.***. Note: This parameter is required when the Zone Type is set to IP and Zone Usage is Blocklist. At least one of the parameters IP Zone Gateway Addresses or IP Zone Proxy Addresses must be defined. This parameter will be omitted when the specified zone is Dynamic.

[ "***.***.***.***", "***.***.***.***/**", "***.***.***.***-***.***.***.***" ]

IP Zone Proxy Addresses

Optional

The IP addresses to act as the proxy addresses for the zone. The values may take the form of IP Addresses in the format of ***.***.***.***, ***.***.***.***/**, or ***.***.***.***-***.***.***.***. Note: When the zone usage is Dynamic, at least one of the parameters IP Zone Gateway Addresses or IP Zone Proxy Addresses must be defined. This parameter will be omitted when the type of the specified zone is Dynamic.

[ "***.***.***.***", "***.***.***.***/**", "***.***.***.***-***.***.***.***" ]

Dynamic Zone Proxy Type

Optional

The proxy type of the dynamic zone. The available proxy types are None, Any, Tor Anonymizer and Not Tor Anonymizer. This parameter is omitted when the specified zone type is IP.

Any

Dynamic Zone Locations

Optional

The list of location objects containing country and region information (formatted as "country-regionKey") for the zone. Each location object includes an ISO-3166-1 country code and an optional ISO-3166-2 region code. This parameter is only used when the Zone Type is set to Dynamic. For example, the parameter can be formatted as follows: [{"country":"AX"},{"country":"AF","region":"AF-BGL"}].

[
{
"country": "AX"
},
{
"country": "AF",
"region": "AF-BGL"
}
]

Dynamic Zone ASNs

Optional

The ANS numeric value for the zone. This parameter is omitted when the specified zone type is IP.

[*****, *****]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

CODE 
{
    "type": "IP",
    "id": "*****",
    "name": "UpdatedNetZone3",
    "status": "ACTIVE",
    "usage": "POLICY",
    "created": "2022-08-31T18:09:27.000Z",
    "lastUpdated": "2022-09-06T20:35:04.000Z",
    "system": false,
    "gateways": [
        {
            "type": "CIDR",
            "value": "***.***.***.***/**"
        },
        {
            "type": "CIDR",
            "value": "***.***.***.***/**"
        },
        {
            "type": "RANGE",
            "value": "***.***.***.***-***.***.***.***"
        },
        {
            "type": "RANGE",
            "value": "***.***.***.***-***.***.***.***"
        }
    ],
    "proxies": [
        {
            "type": "CIDR",
            "value": "***.***.***.***/**"
        },
        {
            "type": "CIDR",
            "value": "***.***.***.***/**"
        },
        {
            "type": "RANGE",
            "value": "***.***.***.***-***.***.***.***"
        },
        {
            "type": "RANGE",
            "value": "***.***.***.***-***.***.***.***9"
        }
    ],
    "_links": {
        "self": {
            "href": "https://*****.okta.com/api/v1/***/***",
            "hints": {
                "allow": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            }
        },
        "deactivate": {
            "href": "https://*****.okta.com/api/v1/***/***",
            "hints": {
                "allow": [
                    "POST"
                ]
            }
        }
    }
}
Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.

The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE 
{
    "ZoneID": "*****",
    "ZoneType": "DYNAMIC",
    "ZoneUsage": "BLOCKLIST"
}
Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

  • A connection issue with the integration

  • The API returned an error message

  • No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE 
Successful
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE 
No sample data

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Update Zone failed.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Okta Code: E0000007.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Zone ID Not Found.

Error Sample Data

Update Zone failed.

Okta Code: E0000007.

HTTP Status Code: 404.

Message: Zone ID Not Found.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Output Type

Description

Return Data Type

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

- A connection issue with the integration

- The API returned an error message

- No response from the API

You can view more details about an error in the Error tab.

String

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error

Description

Example

Failure Indicator

Indicates the command failure that happened at a specific input and/or API call.

Test Connection failed. Failed to check the connector.

Status Code

The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Okta portal. Refer to the HTTP Status Code Registry and Okta Error Code Registry for details.

Status Code: E0000011.

HTTP Status Code: 404.

Message

The raw data or captured key error message from the integration API server about the API request failure.

Message: Invalid token provided.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: E0000011.

Invalid token provided.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close