From 6afff8f4fee1e3ad5a39852dc64788146a15604c Mon Sep 17 00:00:00 2001 From: sophiajose-okta Date: Sun, 24 May 2026 14:12:09 +0530 Subject: [PATCH 1/3] manage identity source --- .../@okta/vuepress-site/docs/guides/index.md | 1 + .../terraform-manage-id-source/index.md | 9 + .../terraform-manage-id-source/main/index.md | 184 ++++++++++++++++++ .../const/navbar.const.js | 4 + 4 files changed, 198 insertions(+) create mode 100644 packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/index.md create mode 100644 packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md diff --git a/packages/@okta/vuepress-site/docs/guides/index.md b/packages/@okta/vuepress-site/docs/guides/index.md index c7dbaf7e7d8..5a9acd5ac97 100644 --- a/packages/@okta/vuepress-site/docs/guides/index.md +++ b/packages/@okta/vuepress-site/docs/guides/index.md @@ -135,6 +135,7 @@ guides: - terraform-enable-org-access - terraform-import-existing-resources - terraform-migrate-consolidated-app-sign-on-policy-rules + - terraform-manage-id-source - terraform-landing-page - terraform-manage-end-user-experience - terraform-manage-external-authenticators diff --git a/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/index.md b/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/index.md new file mode 100644 index 00000000000..6a4848b38ff --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/index.md @@ -0,0 +1,9 @@ +--- +title: Manage identity source +meta: + - name: description + content: Use this guide to manage identity source with Okta AI resources using Terraform. +layout: Guides +sections: + - main +--- \ No newline at end of file diff --git a/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md b/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md new file mode 100644 index 00000000000..a8bd0e8b5ec --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md @@ -0,0 +1,184 @@ +--- +title: Manage identity source +meta: + - name: description + content: Learn how to use Terraform to manage users, groups, and memberships within an Okta identity source. +layout: Guides +--- + +Learn how to use Terraform to manage users, groups, and memberships within an Okta identity source. This guide shows you how to use Terraform for retrieving data, managing individual records, and performing bulk operations. + +--- + +#### Learning outcomes + +* Retrieve identity source users, groups, and memberships using data sources. +* Manage individual user and group records directly. +* Perform bulk upsert and delete operations using a single import resource. +* Run complete import jobs without managing separate staging sessions. + +#### Prerequisites + +* An Okta Identity Engine organization. +* Terraform CLI version 1.0 or later. +* Okta Terraform provider version 6.6.0 or later. +* The specific `identity_source_id` for your integration. See, [API](https://developer.okta.com/docs/api/openapi/okta-management/management/tags/identitysource/identitysource) documentation. + +## Overview + +Managing an Okta identity source involves two primary workflows: + +* Direct management: Create or update individual user, group, or membership records directly in the identity source. This method updates the target system immediately at a single-record level. + +* Bulk management: Combine multiple create, update, or delete commands into a single batch operation using a unified import resource. + +To manage an identity source in Okta, you must follow a structured workflow that starts with verifying your current data and ends with applying your configuration to the environment. + +Perform the following steps to complete the management process: + +1. Retrieve existing data: Look up your current users and groups. +2. Manage individual records: Update specific users or memberships directly. +3. Run bulk operations: Group large batches of data changes inside a single import resource. + +## 1. Retrieve existing data + +Before you make changes, use data sources to look up existing information about your users, groups, and sessions. This ensures you have the correct external IDs to use in your configuration. + +Example: Look up a user and group memberships + +Terraform +```bash +# Look up a user by external ID +data "okta_identity_source_users" "user_example" { + identity_source_id = "" + external_id = "USEREXT123456EXAMPLE" +} + + +# Retrieve members of a specific group +data "okta_identity_source_group_memberships" "group_members" { + identity_source_id = "" + group_external_id = "GROUPEXT123456EXAMPLE" +} +``` + +## 2. Manage individual records + +To update a specific record without affecting other data, use standard resource blocks to interact with the identity source directly. This method is best for isolated, standalone changes. + +Example: Manage a single user and group membership + +```bash +# Manages an individual user in an Okta Identity Source +resource "okta_identity_source_user" "example" { + identity_source_id = "" + id = "USEREXT123456EXAMPLE" + + profile { + user_name = "jdoe@example.com" + email = "jdoe@example.com" + first_name = "Jane" + last_name = "Doe" + } +} + +# Manages a group within an Okta Identity Source +resource "okta_identity_source_group" "example" { + identity_source_id = "" + external_id = "GRPEXT123456EXAMPLE" + + profile { + display_name = "Engineering" + description = "Engineering team group" + } +} + +# Manages a single group membership within an Okta Identity Source +resource "okta_identity_source_group_membership" "example" { + identity_source_id = "" + group_or_external_id = "GRPEXT123456EXAMPLE" + member_external_id = "USEREXT123456EXAMPLE" +} +``` + +## 3. Perform bulk operations + +To manage large sets of data efficiently, use the okta_identity_source_import resource. This resource streamlines the process by automatically creating an import session, staging your batch data, and running the final import in a single configuration block. + +Example: Bulk user adjustments and group management inside a single job + +```bash +resource "okta_identity_source_import" "example" { + identity_source_id = "" + + + # Upsert users and group memberships + upsert_users { + entity_type = "USERS" + + + profiles { + external_id = "USEREXT_NEW" + + + profile { + user_name = "new.user@example.com" + email = "new.user@example.com" + first_name = "New" + last_name = "User" + } + } + } + + + upsert_group_memberships { + memberships { + group_external_id = "GROUPEXT001" + member_external_ids = ["USEREXT_NEW"] + } + } + + + # Upsert and delete in the same job + delete_users { + entity_type = "USERS" + + + profiles { + external_id = "USEREXT_OLD" + } + } + + + upsert_groups { + profiles { + external_id = "GROUPEXT001" + + + group_profile { + display_name = "Engineering" + description = "Engineering team" + } + } + } + + + delete_groups { + external_ids = ["GROUPEXT_DEPRECATED"] + } +} +``` + +## Best practices + +* Use the unified import resource: Do not manually configure resource dependencies or use `depends_on` blocks for bulk workflows. The `okta_identity_source_import` resource automatically creates the session, uploads data, and starts the import. + +* Avoid rate limits: Okta allows only one active import session per identity source every five minutes. If a configuration fails during execution, the provider deletes the incomplete session automatically so that future `terraform apply` runs are not blocked. + +* Understand permanent actions: The import process sends standalone data updates to Okta. Removing an `okta_identity_source_import` block from your configuration later does not undo or remove the entries created during the initial run. + +## Troubleshooting + +* Resource deletion: Removing optional blocks (such as a `delete_users` array) from your import configuration after an apply takes no action in Okta. To trigger a new import when your data parameters remain the same, change a resource attribute to force a new configuration cycle. + +* Session monitoring: You can verify processing updates or errors by checking the `session_status` read-only attribute in your state file or by reviewing your operational log outputs. diff --git a/packages/@okta/vuepress-theme-prose/const/navbar.const.js b/packages/@okta/vuepress-theme-prose/const/navbar.const.js index 66e1109d44d..11693da99c6 100644 --- a/packages/@okta/vuepress-theme-prose/const/navbar.const.js +++ b/packages/@okta/vuepress-theme-prose/const/navbar.const.js @@ -1079,6 +1079,10 @@ export const guides = [ title: "Manage Identity Threat Protection with Okta AI resources", guideName: "terraform-manage-itp", }, + { + title: "Manage identity source", + guideName: "terraform-manage-id-source", + }, ], }, { From 9baf3576c7c373a0d7c441e0eedb88f68350b535 Mon Sep 17 00:00:00 2001 From: sophiajose-okta Date: Mon, 25 May 2026 10:30:43 +0530 Subject: [PATCH 2/3] acrolinx update --- .../terraform-manage-id-source/main/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md b/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md index a8bd0e8b5ec..a2cae1717c2 100644 --- a/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md @@ -40,9 +40,9 @@ Perform the following steps to complete the management process: 2. Manage individual records: Update specific users or memberships directly. 3. Run bulk operations: Group large batches of data changes inside a single import resource. -## 1. Retrieve existing data +## Retrieve existing data -Before you make changes, use data sources to look up existing information about your users, groups, and sessions. This ensures you have the correct external IDs to use in your configuration. +Before you make changes, use data sources to look up existing information about your users, groups, and sessions. This ensures that you have the correct external IDs to use in your configuration. Example: Look up a user and group memberships @@ -62,7 +62,7 @@ data "okta_identity_source_group_memberships" "group_members" { } ``` -## 2. Manage individual records +## Manage individual records To update a specific record without affecting other data, use standard resource blocks to interact with the identity source directly. This method is best for isolated, standalone changes. @@ -101,7 +101,7 @@ resource "okta_identity_source_group_membership" "example" { } ``` -## 3. Perform bulk operations +## Perform bulk operations To manage large sets of data efficiently, use the okta_identity_source_import resource. This resource streamlines the process by automatically creating an import session, staging your batch data, and running the final import in a single configuration block. @@ -171,11 +171,11 @@ resource "okta_identity_source_import" "example" { ## Best practices -* Use the unified import resource: Do not manually configure resource dependencies or use `depends_on` blocks for bulk workflows. The `okta_identity_source_import` resource automatically creates the session, uploads data, and starts the import. +* Use the unified import resource: Don’t manually configure resource dependencies or use `depends_on` blocks for bulk workflows. The `okta_identity_source_import` resource automatically creates the session, uploads data, and starts the import. -* Avoid rate limits: Okta allows only one active import session per identity source every five minutes. If a configuration fails during execution, the provider deletes the incomplete session automatically so that future `terraform apply` runs are not blocked. +* Avoid rate limits: Okta allows only one active import session per identity source every five minutes. If a configuration fails during execution, the provider deletes the incomplete session automatically so that future `terraform apply` runs aren’t blocked. -* Understand permanent actions: The import process sends standalone data updates to Okta. Removing an `okta_identity_source_import` block from your configuration later does not undo or remove the entries created during the initial run. +* Understand permanent actions: The import process sends standalone data updates to Okta. Removing an `okta_identity_source_import` block from your configuration later doesn’t undo or remove the entries created during the initial run. ## Troubleshooting From 73659ddb67dc376d3e3856fe666d027a65c63605 Mon Sep 17 00:00:00 2001 From: sophiajose-okta Date: Tue, 26 May 2026 14:34:42 +0530 Subject: [PATCH 3/3] editorial comments --- .../docs/guides/terraform-manage-id-source/main/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md b/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md index a2cae1717c2..1b5bdea3ee8 100644 --- a/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/terraform-manage-id-source/main/index.md @@ -19,10 +19,10 @@ Learn how to use Terraform to manage users, groups, and memberships within an Ok #### Prerequisites -* An Okta Identity Engine organization. +* An Okta Identity Engine org. * Terraform CLI version 1.0 or later. * Okta Terraform provider version 6.6.0 or later. -* The specific `identity_source_id` for your integration. See, [API](https://developer.okta.com/docs/api/openapi/okta-management/management/tags/identitysource/identitysource) documentation. +* The specific `identity_source_id` for your integration. See [API](https://developer.okta.com/docs/api/openapi/okta-management/management/tags/identitysource/identitysource). ## Overview