OSDOCS-19838: add external id feature

modules/rosa-hcp-creating-account-wide-sts-roles-and-policies.adoc

@@ -35,20 +35,24 @@ Specific AWS-managed policies for {product-title} must be attached to each role.
 
 .Procedure
 
-. If they do not exist in your AWS account, create the required account-wide STS roles and attach the policies by running the following command:
+. If they do not exist in your AWS account, create the required account-wide STS roles and attach the policies, including an external ID for enhanced multi-tenant security, by running the following command:
 +
 ifndef::fips[]
 [source,terminal]
 ----
-$ rosa create account-roles --hosted-cp
+$ rosa create account-roles --hosted-cp --external-id "<external_id>"
 ----
++
+The `--external-id` flag assigns the constraint to both the Installer and Support role trust policies.
 endif::fips[]
 ifdef::fips[]
 [source,terminal]
 ----
-$ export PREFIX=<custom_prefix>; rosa create account-roles --hosted-cp --prefix $PREFIX
+$ export PREFIX=<custom_prefix>; rosa create account-roles --hosted-cp --external-id "<external_id>" --prefix $PREFIX
 ----
 +
+The `--external-id` flag assigns the constraint to both the Installer and Support role trust policies.
++
 When using FIPS encryption, you need to set a custom prefix instead of using the default `ManagedOpenShift` prefix.
 endif::fips[]
 
@@ -100,4 +104,4 @@ ifeval::["{context}" == "rosa-hcp-creating-cluster-with-fips-encryption"]
 endif::[]
 ifeval::["{context}" == "rosa-hcp-egress-zero-install"]
 :!egress-lockdown:
-endif::[]
+endif::[]

modules/rosa-hcp-sts-creating-a-cluster-cli.adoc

@@ -47,7 +47,7 @@ where:
 `<cluster_name>`:: Specify the name of your cluster. If your cluster name is longer than 15 characters, it contains an autogenerated domain prefix as a subdomain for your provisioned cluster on openshiftapps.com. To customize the subdomain, use the `--domain-prefix` flag. The domain prefix cannot be longer than 15 characters, must be unique, and cannot be changed after cluster creation.
 `--private`:: Optional. Use the `--private` argument to create private {product-title} clusters. If you use this argument, ensure that you only use your private subnet ID for `--subnet-ids`.
 `<operator-role-prefix>`:: By default, the cluster-specific Operator role names are prefixed with the cluster name and a random 4-digit hash. You can optionally specify a custom prefix to replace `<cluster_name>-<hash>` in the role names. The prefix is applied when you create the cluster-specific Operator IAM roles. For information about the prefix, see _About custom Operator IAM role prefixes_.
-`<external-id>`:: Optional. A unique identifier that might be required when you assume a role in another account.
+`<external-id>`:: Optional. A unique identifier that might be required when you assume a role in another account. For more information about external ID, see _About external ID_.
 
 [NOTE]
 ====

modules/rosa-hcp-sts-external-id.adoc

@@ -0,0 +1,69 @@
+// Module included in the following assemblies:
+//
+// * rosa_hcp/rosa-hcp-quickstart-guide.adoc
+// * rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="rosa-hcp-sts-external-id_{context}"]
+= About external ID
+
+[role="_abstract"]
+An external ID functions as a distinct cryptographic handshake embedded within your {product-title} account-wide roles, blocking unauthorized third-party access.
+
+During cluster creation, you might be asked to supply an external ID. An external ID allows Red{nbsp}Hat to safely log in to your {aws} account by using an IAM role in a secure manner. This serves as a strict tenant-isolation safeguard that prevents cross-account identity spoofing, ensuring that no one else can trigger automation against your AWS infrastructure.
+
+When Red{nbsp}Hat's automation plane issues an `sts:AssumeRole` API call to your account to manage cluster resources, it must present this exact identifier. If the string does not match the condition block defined in your AWS IAM trust relationship, AWS automatically blocks the request. This ensures Red{nbsp}Hat's automation can only access your environment when explicitly acting on behalf of your organization.
+
+When you assign an external ID, it is applied to both the Support IAM role and the Installer IAM role, through their associated trust policies:
+
+* Support role: when Red{nbsp}Hat Site Reliability Engineers (SREs) need to perform diagnostic, maintenance or any other support function, they assume this role.
++
+.Example support trust policy with an external ID `sts_hcp_support_trust_policy.json`
+[source,json]
+----
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "AWS": "arn:aws:iam::710019948333:role/RH-Technical-Support-15234082"
+            },
+            "Action": "sts:AssumeRole",
+            "Condition": {
+              "StringEquals": {
+                "sts:ExternalID": "<external_id>"
+              }
+           }
+        }
+    ]
+}
+----
++
+* Installer role: when {cluster-manager-first} (OCM) automation needs to provision, scale or delete core cluster infrastructure, it assumes this role.
++
+.Example installer trust policy with an external ID `sts_hcp_installer_trust_policy.json`
+[source,json]
+----
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+           "Effect": "Allow",
+           "Principal": {
+               "AWS": "arn:aws:iam::710019948333:role/RH-Managed-OpenShift-Installer"
+           },
+           "Action": "sts:AssumeRole",
+           "Condition": {
+             "StringEquals": {
+               "sts:ExternalID": "<external_id>"
+             }
+          }
+        }
+    ]
+}
+----
+
+.Additional resources
+* link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html#id_roles_third-party_example[Example scenario using an external ID.]
+* link:https://aws.amazon.com/blogs/apn/securely-using-external-id-for-accessing-aws-accounts-owned-by-others/[Securely using external ID for accessing AWS accounts owned by others.]

modules/rosa-prereq-roles-overview.adoc

@@ -35,6 +35,11 @@ For {product-title} clusters, you must create the following account-wide roles a
 
 |===
 +
+[IMPORTANT]
+====
+For enhanced security, it is recommended to include an external ID within the trust policies of the Support and Installer account-wide roles. For more information, see _About external ID_.
+====
++
 endif::openshift-rosa-hcp[]
 ifndef::openshift-rosa-hcp[]
 +

rosa_hcp/rosa-hcp-quickstart-guide.adoc

@@ -56,11 +56,12 @@ include::modules/rosa-hcp-vpc-subnet-tagging.adoc[leveloffset=+3]
 include::modules/rosa-sts-byo-oidc.adoc[leveloffset=+1]
 include::modules/rosa-operator-config.adoc[leveloffset=+1]
 include::modules/rosa-hcp-sts-creating-a-cluster-cli.adoc[leveloffset=+1]
+include::modules/rosa-hcp-sts-external-id.adoc[leveloffset=+2]
 include::modules/rosa-getting-started-grant-user-access.adoc[leveloffset=+1]
 include::modules/rosa-getting-started-grant-admin-privileges.adoc[leveloffset=+1]
 include::modules/rosa-getting-started-access-cluster-web-console.adoc[leveloffset=+1]
 include::modules/deploy-app.adoc[leveloffset=+1]
 include::modules/rosa-getting-started-revoking-admin-privileges-and-user-access.adoc[leveloffset=+1]
 include::modules/rosa-getting-started-revoke-admin-privileges.adoc[leveloffset=+2]
 include::modules/rosa-getting-started-revoke-user-access.adoc[leveloffset=+2]
-include::modules/rosa-getting-started-deleting-a-cluster.adoc[leveloffset=+1]
+include::modules/rosa-getting-started-deleting-a-cluster.adoc[leveloffset=+1]

rosa_hcp/rosa-hcp-sts-creating-a-cluster-quickly.adoc

@@ -79,6 +79,7 @@ include::modules/rosa-operator-config.adoc[leveloffset=+2]
 * xref:../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-about-operator-role-prefixes_rosa-sts-about-iam-resources[About custom Operator IAM role prefixes]
 
 include::modules/rosa-hcp-sts-creating-a-cluster-cli.adoc[leveloffset=+1]
+include::modules/rosa-hcp-sts-external-id.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 [id="additional-resources_rosa-sts-creating-a-cluster-quickly"]
@@ -89,4 +90,4 @@ include::modules/rosa-hcp-sts-creating-a-cluster-cli.adoc[leveloffset=+1]
 * xref:../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-hcp-prereqs[AWS prerequisites for ROSA with STS]
 * link:https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html[Creating OpenID Connect (OIDC) identity providers]
 * xref:../support/troubleshooting/rosa-troubleshooting-installations-hcp.adoc#rosa-troubleshooting-installations-hcp[Troubleshooting {product-title} installations]
-* xref:../support/getting-support.adoc#getting-support[Getting support for {product-title}]
+* xref:../support/getting-support.adoc#getting-support[Getting support for {product-title}]