// Module included in the following assemblies:
//
// * cloud_experts_tutorials/cloud-experts-getting-started/cloud-experts-rosa-sts-explained.adoc

:_mod-docs-content-type: CONCEPT

[id="cloud-experts-rosa-sts-security_{context}"]
= {product-title} with STS security

[role="_abstract"]
Several crucial components make {product-title} with STS more secure than {product-title} with IAM Users:

* An explicit and limited set of roles and policies that the user creates ahead of time. The user knows every requested permission and every role used.
* The service cannot do anything outside of those permissions.
* Whenever the service needs to perform an action, it obtains credentials that expire in one hour or less. This means that there is no need to rotate or revoke credentials. Additionally, credential expiration reduces the risks of credentials leaking and being reused.

[id="cloud-experts-sts-explained_{context}"]
== AWS STS explained

{product-title} uses AWS STS to grant least-privilege permissions with short-term security credentials to specific and segregated IAM roles. The credentials are associated with IAM roles specific to each component and cluster that makes AWS API calls. This method aligns with principles of least-privilege and secure practices in cloud service resource management. The {product-title} command-line interface (CLI) tool manages the STS roles and policies that are assigned for unique tasks and takes action upon AWS resources as part of OpenShift functionality.

STS roles and policies must be created for each {product-title} cluster. To make this easier, the installation tools provide all the commands and files needed to create the roles as policies and an option to allow the CLI to automatically create the roles and policies. See "Creating a {product-title} cluster with STS using customizations" in the _Additional resource_ for more information about the different `--mode` options.

[id="cloud-experts-sts-process_{context}"]
== {product-title} with STS workflow
The user creates the required account-wide roles and account-wide policies. For more information, see the components section in this tutorial. During role creation, a trust policy, known as a cross-account trust policy, is created which allows a Red{nbsp}Hat-owned role to assume the roles. Trust policies are also created for the EC2 service, which allows workloads on EC2 instances to assume roles and obtain credentials. The user can then assign a corresponding permissions policy to each role.

After the account-wide roles and policies are created, the user can create a cluster. Once cluster creation is initiated, the Operator roles are created so that cluster Operators can make AWS API calls. These roles are then assigned to the corresponding permission policies that were created earlier and a trust policy with an OIDC provider. The Operator roles differ from the account-wide roles in that they ultimately represent the pods that need access to AWS resources. Because a user cannot attach IAM roles to pods, they must create a trust policy with an OIDC provider so that the Operator, and therefore the pods, can access the roles they need.

Once the user assigns the roles to the corresponding policy permissions, the final step is creating the OIDC provider.

image::cloud-experts-sts-explained_creation_flow.png[]

When a new role is needed, the workload currently using the Red{nbsp}Hat role will assume the role in the AWS account, obtain temporary credentials from AWS STS, and begin performing the actions using API calls within the customer's AWS account as permitted by the assumed role's permissions policy. The credentials are temporary and have a maximum duration of one hour.

image::cloud-experts-sts-explained_highlevel.png[]

The entire workflow is depicted in the following graphic:

image::cloud-experts-sts-explained_entire_flow.png[]

Operators use the following process to obtain the requisite credentials to perform their tasks. Each Operator is assigned an Operator role, a permissions policy, and a trust policy with an OIDC provider. The Operator will assume the role by passing a JSON web token that contains the role and a token file (`web_identity_token_file`) to the OIDC provider, which then authenticates the signed key with a public key. The public key is created during cluster creation and stored in an S3 bucket. The Operator then confirms that the subject in the signed token file matches the role in the role trust policy which ensures that the OIDC provider can only obtain the allowed role. The OIDC provider then returns the temporary credentials to the Operator so that the Operator can make AWS API calls. For a visual representation, see below:

image::cloud-experts-sts-explained_oidc_op_roles.png[]

[id="cloud-experts-sts-use-cases_{context}"]
== {product-title} with STS use cases

Creating nodes at cluster install: The Red{nbsp}Hat installation program uses the `RH-Managed-OpenShift-Installer` role and a trust policy to assume the `Managed-OpenShift-Installer-Role` role in the customer's account. This process returns temporary credentials from AWS STS. The installation program begins making the required API calls with the temporary credentials just received from STS. The installation program creates the required infrastructure in AWS. The credentials expire within an hour and the installation program no longer has access to the customer's account.

The same process also applies for support cases. In support cases, a Red{nbsp}Hat site reliability engineer (SRE) replaces the installation program.