# Okta {% hint style="info" %} This feature is part of the Enterprise plan. If it is not enabled for your organization, please contact StrongDM at the [StrongDM Help Center](https://help.strongdm.com/hc/en-us). {% endhint %} ## Overview This guide explains what capabilities StrongDM can provide for the management of privileges in Okta's Administrator Console. It also provides setup and configuration instructions to add an Okta Groups resource in StrongDM and begin using StrongDM to manage groups within Okta for your StrongDM users. StrongDM users in your organization can be granted privilege levels in StrongDM for an Okta Groups resource. Those StrongDM privilege levels add them directly to the corresponding groups in Okta, so that when the users use Okta Administrator Console or apps federated through Okta, their access is elevated based on those groups for a limited period of time. This allows StrongDM admins to manage access to Okta Admin Console or Okta-authenticated SaaS apps by adding and removing Okta groups from users using StrongDM. Okta resources in StrongDM can be used to support the use case of Just-in-Time access. Admins have the choice between providing temporary access directly to particular users within the StrongDM organization, or granting JIT access through access workflows. StrongDM users are able to use these access workflows set up by an admin to request various levels of access that correspond to Okta group membership. For more details on how Access Workflows function, see the [Access Workflows](https://docs.strongdm.com/admin/access/access-workflows) section. ## Limitations * The Okta Groups resource type does not require users to go through a StrongDM proxy (a gateway, relay, or proxy worker) to get access to Okta, the groups within Okta, or downstream apps federated through Okta. Instead, the users' network and authentication path to Okta remains unchanged. Instead, their groups within Okta are manipulated to allow them more or less access as required. This proxy-less approach allows you to use StrongDM to grant or revoke access to privileged resources controlled by Okta without disrupting current authentication paths." * Currently, Okta Groups privilege levels cannot be used in policies. * Currently, Okta Groups resources cannot be added to access rules within roles or dynamic access rules in workflows. * Privilege levels must be configured on the Okta Groups resource in order for it to work. ## Prerequisites * In StrongDM, you must have the Admin [permission level](https://docs.strongdm.com/admin/access/permission-level). * You must have Super Administrator access to your Okta Administrator Console. * Your StrongDM organization must have the Enterprise plan enabled. ## Privilege Levels You must configure privilege levels in your Okta Groups resources before you can grant temporary access and before users can request access to Okta groups. This is because StrongDM does not grant access to your entire Okta tenant, but to specific groups within Okta. StrongDM privilege levels correspond to Okta groups. When a user in StrongDM is granted a privilege level on the Okta Groups resource, their Okta user is added to that corresponding group, giving them whatever access that Okta group provides in your organization. This allows admins to manipulate access, using Okta groups, through StrongDM, and provides a framework for users to request particular Okta groups for limited periods of time, or be assigned them through standing access. ## Set up Okta and Nodes There are two options for setup: Okta API service application or API key. The Okta API service integration is the more secure option and does not depend on a user account's existence or permissions. The API key method is simpler to set up, but breaks if the user who created it ceases to exist in the organization. ### Okta API service setup 1. In the Okta Admin Console, navigate to **Applications** in the sidebar and then select **Create App Integration**. 2. Choose "API Services" for the sign-in method, then click next. 3. Name the integration and save it. 4. In the app integration configuration screen, scroll down to the **General settings** section and select **Edit**. 5. Disable **Require Demonstrating Proof of Possession (DPoP) header in token requests** and then select **Save** in the section's settings. 6. In the **Public keys** section select **Edit**. 7. Select **Add public key**, generate a new key, and copy the PEM value to your clipboard. Select **Done** and then **Save** the section's settings. Keep the key in your clipboard or save it somewhere secure. 8. In the **Client Credentials** section, select **Edit**. 9. Switch from "Client secret" to "Public key / Private key", and then **Save** the section's settings. {% hint style="info" %} The Client ID at the top of this screen is needed in future steps. Save it somewhere easily accessible, or keep the tab open. The organization URL is also be needed. This is your organization's subdomain at Okta. In the Admin Console, it can be found in the address bar, and by removing `-admin`. For example, if the bar reads `https://example-co-admin.okta.com` the actual value is `https://example-co.okta.com`. {% endhint %} 10. Next, go to the **Admin roles** tab and grant the **Super Administrator** role. The abilities of the integration are limited by the scopes set in the next step. {% hint style="info" %} The scopes assigned in the next step reduce the scope of the effective privileges StrongDM is granted through this Super Administrator role, allowing only the permissions needed to read groups, roles, and apps and to manage groups so that users get JIT access as configured by the StrongDM admin. {% endhint %} 11. Go to the **Okta API Scopes** tab and grant the following scopes: * `okta.groups.manage` * `okta.users.read` * `okta.apps.read` * `okta.roles.read` 12. Next, log in to the StrongDM node (proxy worker, gateway, or relay) you intend to use to connect to the Okta Groups resource. Open the file that you use to set StrongDM environment variables. This is often `/etc/sysconfig/sdm-proxy` (or `sdm-worker` if it is a proxy worker). 13. Set the following environment variables on the node: ```sh OKTA_CLIENT_ORGURL="https://" OKTA_CLIENT_CLIENTID="" OKTA_CLIENT_PRIVATEKEY="" ``` For example: ```sh OKTA_CLIENT_ORGURL="https://example-co.okta.com" OKTA_CLIENT_CLIENTID="12345678" OKTA_CLIENT_PRIVATEKEY="-----BEGIN RSA PRIVATE KEY----- MIIBOgIBAAJBALk9Z2Z0c2FtcGxlZmFrZWtleWRhdGEwMDAwMDAwMDAwMDAw MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAw AgMBAAECQFZha2VwZW1rZXlmb3Jkb2N1bWVudGF0aW9ub25seQ== -----END RSA PRIVATE KEY-----" ``` {% hint style="info" %} If your Okta API Service integration has multiple keys listed in the **Public keys** section, you also need to add a key ID environment variable to differentiate which key is being used. The value can be obtained in the **Public keys** section of the Okta integration config screen. ```sh OKTA_CLIENT_PRIVATEKEYID="" ``` {% endhint %} 14. Add an `okta.yaml` file on the node at the standard `~/.okta/okta.yaml` location. ```yaml okta: client: connectionTimeout: 30 # seconds authorizationMode: "PrivateKey" scopes: - okta.groups.manage - okta.users.read - okta.apps.read - okta.roles.read rateLimit: maxRetries: 4 ``` {% hint style="info" %} The values for timeout and retries are suggested starting values and can be adjusted based on your organization's needs. For example, if you use the Okta Groups discovery feature and want to discover many groups, you may want to raise the number of retries if StrongDM doesn't discover all of your groups successfully. Additionally, if you have many groups, consider adding name filters in the Okta discovery feature to reduce the size of the response required from Okta and avoid Okta API throttling. {% endhint %} Your Okta Admin Console and node should be configured successfully. ### API key setup API key setup is simpler, requiring you to generate and save a token from your Admin Console user account, and set three environment variables on your node(s). 1. Log in to the Okta Admin Console as the user whose key you would like to use, and navigate to **Security** > **API** and to the **Tokens** tab. 2. Select the **Create token** button, and fill in a name. 3. For origins, choose the value that makes the most sense to your setup. **Any IP** is the broadest, but if you know the IP or range of your node(s) you can choose a more granular value. 4. Copy the API key presented. 5. Next, log in to the node (proxy worker, gateway, or relay) you intend to use to connect to the Okta Groups resource. Open the file that you use to set StrongDM environment variables. This is often `/etc/sysconfig/sdm-proxy` (or `sdm-worker` if it is a proxy worker). 6. Set the following environment variables on the node: ```sh OKTA_CLIENT_ORGURL="https://" OKTA_CLIENT_AUTHORIZATIONMODE="SSWS" OKTA_CLIENT_TOKEN="" ``` For example: ```sh OKTA_CLIENT_ORGURL="https://example-co.okta.com" OKTA_CLIENT_AUTHORIZATIONMODE="SSWS" OKTA_CLIENT_TOKEN="00fakeOktaApiToken_9XKpLQmR7dA2CwYH" ``` {% hint style="info" %} The organization URL is your organization's subdomain at Okta. In the Admin Console, it can be found in the address bar, and by removing `-admin`. For example, if the bar reads `https://example-co-admin.okta.com` the actual value is `https://example-co.okta.com`. {% endhint %} Your Okta Admin Console and node should be configured successfully. ## Configure the Okta Groups Resource in StrongDM ### Verify the node is reachable If you look at the Okta Groups resource in the Admin UI, under **Diagnostics**, since your node is running with credentials the healthcheck should already be successful. The nodes in the diagnostics list that are healthy are the ones with access. If you have set up a proxy cluster to communicate with Okta, the healthcheck should be successful as long as you have assigned the proxy cluster to the resource. You can also tag your nodes with a tag `sdm admin nodes update --tags sdm__okta_orgurl=` (note the two underscores between `sdm` and `okta`). This forces StrongDM to use this node (and any other node tagged in this manner) to connect, regardless of the health status of it or any other node that has been configured to access Okta. ### Set up Identity Aliases {% hint style="info" %} The default "email" Identity Set is available for use if your StrongDM user emails match your Okta user emails perfectly. If they don't match, you will want to create an Identity Set so that you can add the email used in Okta to each user's profile in StrongDM, in order to map them correctly. {% endhint %} 1. Set up an Identity Set for use with your Okta Groups resource in the Admin UI at **Principals** > **Identity Sets** > **Add set**. See the [Identity Alias](https://docs.strongdm.com/admin/principals/identity-alias) section for more information on Identity Sets. 2. Open the **Principals** > **Users** page, find a user you wish to add to this Identity Set, open the user’s details page, and choose the **Identity Aliases** tab. 3. Select **Add Alias**, and then fill out the alias as the user’s exact Okta User email, such as `alice.glick@example.com`. When you set up the Okta Groups resource with StrongDM and select this Identity Set, the StrongDM user can be added to this resource with various privilege levels to manage the groups of the corresponding user in Okta. ### Add the Resource in StrongDM This section provides instructions for adding the resource in either the StrongDM Admin UI, CLI, Terraform provider, or SDKs. {% tabs %} {% tab title="Admin UI" %} **Set up and Manage With the Admin UI** If using the Admin UI to add the resource to StrongDM, use the following steps. 1. Log in to the Admin UI and go to **Resources** > **Managed Resources**. 2. Click **Add Resource**. 3. For **Resource Type**, set **Okta Groups**. 4. Set all other required [resource properties](#resource-properties). If you choose to use discovery, the integration attempts to discover Okta groups in your organization and provide those as privilege level options in StrongDM. You can limit the number of groups discovered by StrongDM by providing name filters. For every filter string you provide, StrongDM fetches groups with names that contain that string. You can use asterisks as wildcards, letting you find the group "SuperAdminStrongDM" by providing the string "Admin". You can provide multiple name strings separated by commas. If you do not choose to enable discovery, you can provide a comma separated list of existing Okta groups you would like to provide as privilege levels in StrongDM. 5. Click **create** to save the resource. 6. Click the resource name to view status, diagnostic information, and setting details. After the resource is created, the Admin UI displays that resource as unhealthy until the health checks run successfully. When the resource is ready, the **Health** icon indicates a positive, green status. {% endtab %} {% tab title="CLI" %} **Set up and Manage With the CLI** This section provides general steps on how to configure and manage the resource using the StrongDM CLI. For more information and examples, please see the [CLI Reference](https://docs.strongdm.com/references/cli) documentation. 1. In your terminal or Command Prompt, log in to StrongDM: ```sh sdm login ``` 2. Run `sdm admin clouds add oktaGroups --help` to view the help text for the command, which shows you how to use the command and what options (properties) are available. Note which [properties](#resource-properties) are required and collect the values for them. 3. Then run `sdm admin clouds add oktaGroups ` and set all required properties with their values. For example: ``` sdm admin clouds add oktaGroups "okta-groups-prod" --discovery-enabled --domain "exampleco.okta.com" --identity-set-name "Okta Admins" --proxy-cluster-id "plc_abcdef0123456789" --tags "env=prod" ``` 4. Check that the resource has been added. The output of the following command should show the resource's name: ```sh sdm admin clouds list ``` {% endtab %} {% tab title="Terraform" %} **Set up and Manage With Terraform** This section provides an example of how to configure and manage the resource using the Terraform provider. For more information and examples, please see the [Terraform provider](https://github.com/strongdm/terraform-provider-sdm) documentation. ```hcl # Install StrongDM provider terraform { required_providers { sdm = { source = "strongdm/sdm" version = "16.5.0" } } } # Configure StrongDM provider provider "sdm" { # Add API access key and secret key from the Admin UI api_access_key = "njjSn...5hM" api_secret_key = "ziG...=" } # Create Okta Groups cloud resource "sdm_resource" "okta_groups_prod" { okta_groups { # Required name = "okta-groups-prod" # domain = "exampleco.okta.com" # --domain identity_set_id = "ig-a1b2c3d4" # --identity-set-id # Optional discovery configuration discovery_enabled = true # --discovery-enabled group_names = "Okta Admins,OktaOps,Finance*" # --group-names (comma-separated, supports wildcards) privilege_levels = "Okta Admins,Helpdesk Support" # --privilege-levels (conditional) # Common networking options egress_filter = "field:name tag:env=prod tag:region=us-east" # --egress-filter proxy_cluster_id = "plc_abcdef0123456789" # --proxy-cluster-id # Tags tags = { # --tags env = "prod" cloud = "okta" auth = "okta" team = "platform" } } } ``` {% endtab %} {% tab title="SDKs" %} **Set up and Manage With SDKs** In addition to the Admin UI, CLI, and Terraform, you may configure and manage your resource with any of the following SDK options: Go, Java, Python, and Ruby. Please see the following references for more information and examples. | Go | ​[pkg.go.dev](https://pkg.go.dev/github.com/strongdm/strongdm-sdk-go/v16)​ | ​[strongdm-sdk-go](https://github.com/strongdm/strongdm-sdk-go)​ | ​[Go SDK Examples](https://github.com/strongdm/strongdm-sdk-go-examples)​ | | ------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | Java | ​[javadoc](https://strongdm.github.io/strongdm-sdk-java-docs/)​ | ​[strongdm-sdk-java](https://github.com/strongdm/strongdm-sdk-java)​ | ​[Java SDK Examples](https://github.com/strongdm/strongdm-sdk-java-examples)​ | | Python | ​[pdocs](https://strongdm.github.io/strongdm-sdk-python-docs/)​ | ​[strongdm-sdk-python](https://github.com/strongdm/strongdm-sdk-python)​ | ​[Python SDK Examples](https://github.com/strongdm/strongdm-sdk-python-examples)​ | | Ruby | ​[RubyDoc](https://www.rubydoc.info/gems/strongdm)​ | ​[strongdm-sdk-ruby](https://github.com/strongdm/strongdm-sdk-ruby)​ | ​[Ruby SDK Examples](https://github.com/strongdm/strongdm-sdk-ruby-examples)​ | | {% endtab %} | | | | | {% endtabs %} | | | | #### Resource properties The **Okta Groups** resource type has the following properties.
PropertyRequirementDescription
Display NameRequiredA meaningful name for this resource; displays throughout StrongDM; no special characters like quotes (") or angle brackets (< or >)
Resource TypeRequiredOkta Groups
Proxy ClusterRequiredDefaults to “None (use gateways)”; if using proxy clusters, select the appropriate cluster to be used for group manipulation
Okta Domain NameRequiredThe organization domain URL saved previously
Discovery EnabledOptionalEnable discovery for this resource; Discovered data displayed in the **Discovery** tab
Group NamesOptionalNames of the discovered Okta groups that you want to appear as privilege level options in StrongDM; Supports wildcard characters such as `*` and are matched case-insensitively; should be comma separated, such as: sdm_group1,sdm_group2; this field appears when discovery is enabled
Privilege LevelsRequiredExact names of the Okta groups that you want to provision access to, comma separated, such as sdm_group1,sdm_group2; this field appears when discovery is not enabled
Identity SetRequiredIdentity Set to map to use to map StrongDM users to Okta users
Resource TagsOptionalEnter tags consisting of key-value pairs <KEY>=<VALUE> (for example, env=dev)
## Manage Okta Group Membership With StrongDM There are currently two ways to grant privileges to StrongDM users on an Okta Groups resource. You can grant temporary access in the Admin UI by going to **Principals** > **Users** and selecting the user, and then navigating to the **Entitlements** tab and selecting **Grant Temporary Access**. Alternatively, you can create an [access workflow](https://docs.strongdm.com/admin/access/access-workflows) that facilitates JIT access for users using a static access rule that specifies the Okta Groups resource. Users can then request various privilege levels for the resource and be approved or denied by configured approvers. At this time, granting and revoking privilege levels via dynamic access rules or directly through StrongDM roles is not available. StrongDM periodically verifies that the user is still a member of the relevant Okta group(s), and re-adds them if necessary, until the access grant in StrongDM expires or is revoked. After a grant expires or is revoked, StrongDM removes the user from the Okta group to remove their elevated level of privilege. ### Verifying group membership additions or revocations Once a user has been granted a privilege level, you can verify this by checking your Okta group membership directly and see that the user is now in the corresponding group. If they are removed from the privilege level in StrongDM, they are also removed from the group in Okta. Note that revocations also work when the group was originally granted outside of StrongDM. For example, if Alice was added to the group `engineers1` directly in Okta and then later was given a privilege level in StrongDM that corresponds to the `engineers1` group as well, when her access in StrongDM is revoked, she is removed from the Okta group. ### Connection through CLI When a user requests access to an Okta Groups resource via an access workflow through the CLI, they need to append a `--oktaGroup` option to their command: ```sh sdm access to --duration 10m --reason "example reason for request" --oktaGroup sdmGroup1 ``` ## Logs When a user is given a privilege level for an Okta Groups resource, StrongDM Activity logs reflect this with events that say `User external grant provisioned`. Activity log events when a user privilege level for an Okta Groups resource is revoked in StrongDM say `User external grant revoked`. No user actions against Okta Groups resources are logged, since StrongDM does not facilitate connections or authentication for users. ## Connect to Okta In summary, before users can connect to Okta Administrator Console with the groups that are provided through privilege levels, the following things must occur: * Your node(s) must be set up to access Okta. Either an Okta API service integration has been created and environment variables and an Okta configuration file set up on the node, or a user API key has been generated and environment variables set on the node. * An Identity Set is configured and Identity Aliases are added to users, if not using the default email set. * The Okta Groups resource is configured in StrongDM, using the Identity Set and with configured privilege levels that correspond to existing Okta groups. * Temporary access is granted to user(s) or an access workflow is set up to allow requests for access. Once the resource is configured correctly, and once the user is assigned privilege levels within StrongDM or requests and is granted them, the user should be able to authenticate and connect as normal, now with escalated privileges via the additional Okta groups. Using the StrongDM Desktop application or CLI to launch the Okta Groups resource is not necessary, as the user was directly added to Okta groups. The user can simply go to authenticate to various services using Okta as normal. ## Troubleshooting * Healthchecks for this resource type attempt to list Okta users from the resource, so any error messages or failed routes through nodes should appear in the Diagnostics tab in the Admin UI. * If you’re having intermittent errors converging, try tagging nodes that you are certain are healthy with `sdm__okta_orgurl=`. This forces those healthy nodes to be selected, and you can see if your connections work when using only the healthy nodes. * If your users are failing to be provisioned or revoked, check the activity logs for any “user external grant provision failed” or “user external grant revocation failed” logs. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.strongdm.com/admin/resources/clouds/okta.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.