From 8d8c03bfe3cc60204e4314c2fdf8339147e3d68f Mon Sep 17 00:00:00 2001 From: Roman Tkachenko Date: Wed, 13 Nov 2024 19:24:39 -0800 Subject: [PATCH] Add draft Identity Center integration docs --- .../guides/aws-iam-identity-center.mdx | 183 ++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 docs/pages/admin-guides/management/guides/aws-iam-identity-center.mdx diff --git a/docs/pages/admin-guides/management/guides/aws-iam-identity-center.mdx b/docs/pages/admin-guides/management/guides/aws-iam-identity-center.mdx new file mode 100644 index 0000000000000..612644da400a9 --- /dev/null +++ b/docs/pages/admin-guides/management/guides/aws-iam-identity-center.mdx @@ -0,0 +1,183 @@ +--- +title: AWS IAM Identity Center (Preview) +description: How to set up and use Teleport AWS IAM Identity Center integration +--- + +Teleport's integration with [AWS IAM Identity Center](https://aws.amazon.com/iam/identity-center/) +allows you to organize and manage your users' short- and long-term access to AWS +accounts and their permissions. + +With the Identity Center integration you can grant or revoke persistent access +to AWS accounts and resources using Teleport access lists, or use Teleport +access requests for scenarios requiring temporary elevated AWS privileges. + +## How it works + +Identity Center integration builds on top of Teleport's [role-based access controls](../../access-controls/guides/guides), +[just-in-time access requests](../../access-controls/access-requests/access-requests/) +and [access lists](../../access-controls/access-lists/access-lists/). + +When enabled, Teleport takes ownership over Identity Center users, groups, and +permission set assignments: + +- All Identity Center groups, along with their members and account/permission + assignments, are imported into Teleport as access lists. +- Identity Center account/permission assignments are expressed as Teleport role + policies. +- Changes made to Teleport users or access lists with Identity Center assigned + permissions are reflected in the Identity Center. + + +Note that Identity Center integration requires using Teleport as an external +identity source. + +As such, we recommend ensuring that all Identity Center users have access to +your Teleport cluster before turning the integration on to avoid access +interruption. If your Identity Center already uses external identity source, +you can configure corresponding [SSO connector](../../access-controls/sso/sso/) +in Teleport or, if you're using Okta, turn on +[Okta integration](../../../enroll-resources/application-access/okta/hosted-guide/). + + +For managing long-term access, Teleport cluster administrators can designate +Identity Center-synced access lists owners who will be responsible for adding +or removing users and performing periodic access reviews. Users added to or +removed from such access lists will be added to or removed from corresponding +Identity Center groups. + +For short-term access, users can go through Teleport's standard access request +flow in which case Teleport will assign requested privileges to a particular +user and automatically unassign once the access request expires. + + +The preview release of Teleport's Identity Center integration in Teleport 17.0 +supports role access requests only. + +Resource access requests (ability to request access to a particular permission +set in a particular account or a particular resource) will be added in follow +up releases. + + +## Prerequisites + +- Teleport cluster version 17.0 or higher. +- Administrative access to AWS IAM Identity Center. + +## Step 1/5. Configure AWS integration + +Teleport provides a guided web UI based configuration flow for the Identity +Center integration. To get started, navigate to the "Add new integration" page +in your Teleport cluster control panel and select "AWS Identity Center". + +//screenshot + +During this step, you will set up Teleport as an OIDC identity provider for +your AWS account and create an AWS role with the permissions required for the +integration to function, such as fetching Identity Center accounts, users, +groups, permission set assignments, and so on. + +
+``` +organizations:ListAccounts +organizations:ListAccountsForParent + +identitystore:ListUsers +identitystore:ListGroups +identitystore:ListGroupMemberships + +sso:DescribeInstance +sso:DescribePermissionSet +sso:ListPermissionSets +sso:ListAccountAssignmentsForPrincipal +sso:ListPermissionSetsProvisionedToAccount +sso:CreateAccountAssignment +sso:DescribeAccountAssignmentCreationStatus +sso:DeleteAccountAssignment +sso:DescribeAccountAssignmentDeletionStatus + +iam:AttachRolePolicy +iam:CreateRole +iam:GetRole +iam:ListAttachedRolePolicies +iam:ListRolePolicies +iam:GetSAMLProvider +iam:ListRoles +``` +
+ +//screenshot + +Enter required information such as Identity Center region, ARN and integration +name, and execute the generated command in the Cloud Shell. + +## Step 2/5. Import AWS resources + +On the next step, you are presented with the list of AWS accounts, groups, and +permission sets that Teleport was able to find in your Identity Center. + +//screenshot + +Pick the default owners that should be assigned to the access lists in Teleport. +These resources will be imported into Teleport once you click Next. + +## Step 3/5. Configure identity source + + +After this step, Teleport will become your Identity Center's identity provider. + +To avoid access interruptions, we recommend making sure that all existing +Identity Center users have access to your Teleport cluster by e.g. using +the same [IdP](../../access-controls/sso/sso/) as your current Identity Center +external identity source. + + +Follow the instructions to change your Identity Center's identity source to +Teleport. + +//screenshot + +## Step 4/5. Enable SCIM + +The final step is to enable the SCIM endpoint in your Identity Center to +allow Teleport to push user and group changes. + +//screenshot + +## Step 5/5. Verify the integration + +Once the integration has been setup, navigate to the access lists view page +in your cluster and make sure that all your Identity Center groups have +been imported: + +//screenshot + + +It may take a few minutes for the initial sync to complete. + + +Imported access lists should show the same members as their corresponding +Identity Center groups. + +## Usage scenarios + +### Managing long-term access with access lists + +XXX + +### Using role access requests + +XXX + +### Creating custom Identity Center roles + +XXX + +## Next steps + +- Take a deeper dive into fundamental Teleport concepts used in Identity Center + integration such as [RBAC](../../access-controls/guides/guides), + [JIT access requests](../../access-controls/access-requests/access-requests/) + and [access lists](../../access-controls/access-lists/access-lists/). +- Learn how to enable [Okta integration](../../../enroll-resources/application-access/okta/hosted-guide/) + to sync apps, users and groups from Okta in conjunction with Identity Center + integration.