Okta Plugin for User Risk Exchange

This document explains how to configure the Okta integration with the User Risk Exchange module of the Netskope Cloud Exchange platform. This integration performs the following actions on Okta users:

• Add to group
• Remove from group
• Push risk score
• No actions

Fetched record types are not applicable.

Prerequisites

To complete this configuration, you need:

• A Netskope tenant (or multiple, for example, production and development/test instances) that is already configured in Cloud Exchange.
• A Netskope Cloud Exchange tenant with the User Risk Exchange module already configured.
• Your Okta Domain and API Token for performing group operations.
• For Push Risk Score, the public key generated in the steps below is to be hosted publicly.
• Connectivity to the following hosts:

  • https://<user>.oktapreview.com/

  • https://<user>.okta.com/

  • https://<user>.okta-emea.com/

  Note

  You need any one of these URLs for the plugin.

Compatibility

Netskope CE: v4.1.0, v4.2.0

Score Mapping

Netskope Score Mapping

Score	Level
0 – 250	Critical
251 – 500	High
501 – 750	Medium
751 – 1000	Low

Netskope-Okta Mapping

Netskope	Okta/td>
Critical (0 – 250)	high
High (251 – 500)	high
Medium (501 – 750)	medium
Low – (751 – 1000)	low
None (NA)	none

Permissions

For configuring the API Token, make sure you have admin access to your account.

API Details

List of APIs used

API Detail	Method	Endpoint
Get All Users	GET	/api/v1/users
Get All Groups	GET	/api/v1/groups
Create Group	POST	/api/v1/groups
Add to Group	PUT	/api/v1/groups/<group_id>/users/<user_id>
Remove from Group	DELETE	/api/v1/groups/<group_id>/users/<user_id>
Generate Security Provider	POST	/api/v1/security-events-providers
Push Risk Score	POST	/security/api/v1/security-events

Generating SET Token – for Push Risk Score Action: SET Token will be generated using the jwt library using RS256 Algorithm and the event schema: https://schemas.okta.com/secevent/okta/event-type/user-risk-change

User Agent

The user agent added for this plugin is in the following format:

netskope-ce-<ce_version>-<module>-<plugin>-<plugin_version>

Example:

netskope-ce-4.2.0-ure-okta-v1.1.0

Workflow

Click play to watch a video.

Get your API Token and Okta Domain

1. Log in to your Okta platform and click Admin.
   

   

2. Click on the downward arrow in the right upper corner.
   

   

3. Copy the Okta domain.
   

   

4. Go to Security > API.
   

   

5. Click Create Token.
   

   

6. Enter a token name and click Create Token.
   

   

7. Copy the token value.
   

   

Generate a JWKS Public and Private Key Pair (Required for Push Risk Score Action)

The Push Risk Score requires the public key to be hosted on a public URL. Here is one way of generating the Public and Private key Pair.

1. Go to https://mkjwk.org/
2. Enter the following values to generate the key pair from the RSA tab:
   • Key Size: 2048
   • Key Use: Signature
   • Algorithm: RS256
   • Key ID: SHA-256
   • Show X.509: Yes
3. Click Generate.
4. Copy and make a note of the Public Key. Host this Public Key on a public URL. This public URL will be required for the sharing configuration. The Base URL used for posting the Public Key will be used as the Issuer URL.
   • Example of URL that contains the JWKS token:

     http://<public ip address>:<publically accessible port>/jwks

   • Example of issuer URL:

     http://<public ip address>:<publically accessible port>

   

5. Scroll down, copy, and make a note of Private Key (X.509 PEM Format) as this will be required in the sharing configuration. Don’t use the Copy to Clipboard button. Copy it manually, as it may include \n for line break that will result in invalid OEM format while using in the plugin.
   

   Note

   CE requires the Public Key in the JWK format (to be hosted publicly) and the Private Key in the PEM format.

   JWKS format:

   {
   "keys": [
   <PUBLIC KEY>
   ]
   }

Get your Issuer and JWKS URL (Required for Push Risk Score Action)

You need to host the Public Key on a publicly hosted URL. Follow these steps to create the API endpoint in the Okta workflow for the Okta URE plugin where the public API endpoint will be used as a publicly hosted JWKS URL.

Hosting the Public Key

These steps define how to host the public key using the script provided in the plugin.

1. Log in to your Okta tenant and go to the admin console by clicking on the Admin button on the top right corner.
2. Go to Workflow console from Workflow > Workflow console from the left pane.
3. Select the Flow tab from the top panel.
4. Click New Flow.
5. Click Add Event.

   

6. Select API Endpoint.
7. The API endpoint settings dialog will open. Select the Security level as None (public service) and click Close.
8. Click Add function.

   

9. Search for Return raw in the search box and select Return Raw function form the list.
10. Now make the below changes in the header and body of the Return Raw function. Paste the below content in the headers field:

     {
    "Content-Type": "application/json"
    }

11. Paste the public key in the JWKS format here in the body:

    {
    "keys":[
    {
    "kty":"RSA",
    "e":"AQAB",
    "use":"sig",
    "kid":"1pXZQNc3YiNjWUD2rZ2WqFNQzBANcSzrGhrlhBExLzA",
    "alg":"RS256",
    "n":"g5r_OAU9OE-ybhedeFDWv7XGaqyhZevlDTqp9QWweB7xT_WGNbLh49LWYhe4t2-bqiRB2G3baR7iX5l3ojTEZ6YTCsPBTubAjh1Bfdm_7RyElEHuBGZ9j9zXCaNcu1WvE4G-yQH0boscLhLiFv8qwUFfFvKmF18R6JUFXmOKO0TWlkR2wfhtA8vXCH0il60ICUNmZV_axnnqUjzGezF_3D6coNt1NEocCiaYeX46tdJCLg8ac9furS0g-VbftPcg6DpkwrIN5t1UphNlPvkxhnmfMYxzSo9Pq_Sb0LPImL2h9a32Iw-GY2Zr69ctNQxhghR6_Aqaps5iQRqjAPs3CQ"
    }
    ]
    }

    

12. Click Save and enter a name for the flow.

    

13. Expand Flow is Off on the top and turn it on.
14. Click on the </> button to open the Endpoint settings.
15. Copy the Invoke URL from the Endpoint settings.

    

16. The public key will be hosted on the public URL and you can view it using the invoke URL.
17. The tenant URL of the Okta account used for hosting the public key will be used as the Issuer URL. Make a note of the tenant URL.

Configure the Okta Plugin

1. Log in to your CE instance and go to Settings > Plugins. Search for and select the Okta v1.1.0 (URE) box.
2. Enter the following parameters in the Basic Information section.
   • Configuration Name: Enter a name for the configuration.
   • Sync Interval: Enter the time at which the plugin will be synced.

   

3. Enter the plugin Configuration parameters for authenticating:
   • Okta Domain: Enter the Okta Domain obtained in the previous steps.
   • API Token: Enter the API Token generated in the previous steps.

   

4. Click Next and set the score range from the Select Range page (Recommended to keep the default).
5. Click Save.

Create a User Risk Exchange Business Rule for Okta

Use a Business Rule to filter the users on which you want to perform actions. Follow these steps to configure a business rule.

1. Go to User Risk Exchange > Business Rule and click Create New Rule.
2. Click Add Group and add the filter based on your requirement and click Save.

Manage User Risk Exchange Actions for Okta

Following is the list of available actions for the Okta plugin.

Add to a Group

Whenever an action triggers, this action adds users to the group that has been mentioned while creating the action configuration.

1. Go to User Risk Exchange > Actions and click Add Action Configuration.
2. Select a Business Rule.
3. Select the Okta Plugin you configured earlier.
4. Select Action as Add to group.
5. Select an existing group in the Group dropdown to add the user to an existing group, or select Create new group.
6. Enter a Group Name if you have selected the Create New Group option in the Group parameter.
7. Click Save.

Remove from a Group

Whenever an action triggers, this action removes users from the group that has was assigned while creating the action.

1. Go to User Risk Exchange > Actions and click on Add Action Configuration.
2. Select a Business Rule.
3. Select the Okta Plugin configured earlier.
4. Select Action as Remove from the group.
5. Select a group from the Group dropdown to remove the users that match the Business Rule from the selected group.
6. Click Save.

Push a Risk Score

Whenever an action triggers, this action pushes the current and the previous score level of the user to Okta (provided the user exists on the Okta tenant).

Follow these steps to perform the Push Risk Score Action on Okta users.

1. Go to User Risk Exchange > Actions and click Add Action Configuration.
2. Select a Business Rule.
3. Select the Okta Plugin you configured earlier.
4. Select Action as a Push risk score.
5. Enter these parameters:
   • Plugin Configuration Name: The Configuration Name whose current and previous score will be shared with Okta.
   • Issuer URL: The URL that is used for hosting the JWK Public Key publicly (Okta tenant URL used for hosting public key).
   • JWKS URL: The URL where the JWK Public Key is hosted publicly (Invoke URL).
   • Private Key: Private Key (PEM format) corresponding to the Public Key hosted publicly.

   

6. Click Save.

No Action

This action will not perform any kind of action on users. Users can use this action to generate the UBA alerts in the Netskope Ticket Orchestrator module.

Validate the Okta Plugin

In Cloud Exchange

Go to User Risk Exchange > Action Logs.

In Okta

1. Go to the Okta Admin section.
2. Click on Groups. After Finding the group that you have selected while in action configuration. Here you can check the groups created and the user added in the groups or removed from the group.
3. To verify the Push risk score, Navigate to the Reports System Log, the logs for push risk score action will have “Partner reported risk” as the Event info.

Troubleshooting the Okta Plugin

Here is a list of error messages and solutions for what to do if the error occurs in the Okta plugin.

• Not able to save the sharing configuration and receiving the below error in the loggers:URE Okta [URE Okta]: Received error code 400. Error Summary: Api validation failed: name. Error Causes: [{‘errorSummary’: ‘name: Security Events Provider name must be unique’}].

• You can receive this error if a sharing configuration with destination “Okta” is currently present on CE or was earlier created and deleted.
• Cause: While creating the sharing configuration a new Security Event Provider is created on Okta tenant with the name – “Netskope Security Events Provider”.

But the Okta Netskope URE accepts a single 1:1 mapping of sharing with the security event provider.

• What to do: Delete the existing Security Event Provider from the Okta platform in order to edit or create a new sharing configuration with Okta in Netskope CE. Below are the steps to delete the existing Security Event Provider:
  • Log in to your Okta Tenant.
  • Go to Security > Device Integrations.

  

• Click on the Receive shared signals tab.
• For the shared signal named Netskope Security Events Provider, expand Actions and select Delete.

After this you can create a new sharing configuration on Netskope CE URE for Okta plugin or edit the existing one.

• • URE Okta [configuration_name]: Received error code 400. Error Summary: Api validation failed: settings.jwksUrl. Error Causes: [{‘errorSummary’: ‘settings.jwksUrl: Is not a valid URL. Valid example: http://www.okta.com‘}].
    • What to do: Verify the Public Key hosted on the public URL.
  • URE Okta [URE Okta]: Unable to establish connection with Okta platform while ‘Fetching Key ID’. Proxy server or Okta server is not reachable. Error: HTTPConnectionPool(host=’35.172.183.204′, port=8080): Max retries exceeded with url: /jwks (Caused by NewConnectionError(‘<urllib3.connection.HTTPConnection object at 0x7f075a904430>: Failed to establish a new connection: [Errno 111] Connection refused’))
    • What to do: Check the site where you have hosted the public key. If you are using a script, make sure the script is up and running.
  • URE Okta [URE Okta]: Received error code 400. Error Summary: Error Summary not available. Error: invalid_key. Error Description: No matching key was found in JWKS uri, kid=8s4cciA4UPIN7aVyTwVEhE9JTUSL87XALbCY9SUKvws.
    • What to do: This specifies that the private key provided in the Action configuration does not match with its public key pair provided in the script. Regenerate the public and private key or verify the public and private key added.
  • URE Okta [Okta]: Group with id ’00ga2i326jTvm8sxV1d7′ does not exist on Okta.
    • What to do: If you receive the above error, that means that the group name provided in the action configuration does not exist on the Okta platform, change the group name or create the same group on Okta.
  • URE Okta [URE Okta]: Invalid Private Key provided, make sure the Private Key is in PEM format.
    • What to do: If you received the above error that means the private key provided is invalid or is not in a valid PEM format.
  • URE Okta [Okta]: Invalid Okta Domain provided.
    • What to do: If you received the above error that means the Okta Domain provided in the plugin configuration is invalid.
  • URE Okta [Okta]: Validation error occurred. Error: Authentication failed, check the API Token provided.
    • What to do: If you received the above error that means the Okta API Token provided in the plugin configuration is invalid.