AWS IAM high security documentation change
Summary
Updated documentation for federated principals (OIDC/SAML) and AWS STS federation methods. Added details about OIDC provider configuration, JWT requirements, SAML authentication flow, and security recommendations for `GetFederationToken`.
Security assessment
The changes emphasize security best practices: (1) Warns against using root credentials with `GetFederationToken` (explicit security guidance). (2) Highlights that `AssumeRoleWithSAML`/`AssumeRoleWithWebIdentity` eliminate long-term credential risks. (3) Adds requirements for JWT validation and OIDC provider configuration. These changes directly address credential management risks and authentication security.
Diff
diff --git a/IAM/latest/UserGuide/reference_policies_elements_principal.md b/IAM/latest/UserGuide/reference_policies_elements_principal.md index 1ef88af2b..fb09b739c 100644 --- a//IAM/latest/UserGuide/reference_policies_elements_principal.md +++ b//IAM/latest/UserGuide/reference_policies_elements_principal.md @@ -5 +5 @@ -How to specify a principalAWS account principalsIAM role principalsRole session principalsIAM user principalsIdentity Center principalsFederated user session principalsAWS service principalsAWS service principals in opt-in RegionsAll principalsMore information +How to specify a principalAWS account principalsIAM role principalsRole session principalsIAM user principalsIdentity Center principalsFederated user principalsAWS service principalsAWS service principals in opt-in RegionsAll principalsMore information @@ -35 +35 @@ You cannot use the `Principal` element in an identity-based policy. Identity-bas - * AWS STS federated user session principals + * AWS STS federated user principals @@ -161 +161 @@ When you specify an assumed-role session in a `Principal` element, you cannot us -A _federated principal_ is a session principal that results from using the AWS STS `AssumeRoleWithWebIdentity` operation. You can use an external OIDC provider (IdP) to sign in, and then assume an IAM role using this operation. This leverages identity federation and issues a role session. For more information about which principals can assume a role using this operation, see [Compare AWS STS credentials](./id_credentials_sts-comparison.html). +An OIDC federated principal is one type of principal created when authenticating through AWS STS `AssumeRoleWithWebIdentity`. This principal supports various identity providers including OpenID Connect, OAuth 2.0 providers like Login with Amazon, Facebook, Google, and Amazon Cognito federated identities. @@ -163 +163 @@ A _federated principal_ is a session principal that results from using the AWS S -When you issue a role from an OIDC provider, you get this special type of session principal that includes information about the OIDC provider. +Identities who've authenticated with a web identity provider, include a JSON web token (JWT) from an OIDC provider in the API call. This token both verifies their identity and returns temporary AWS security credentials. However, two prerequisites must be met. First, you must obtain a JWT from a supported identity provider. Second, you must add the identity provider to your AWS account and [configure](./id_roles_providers_create_oidc.html) it. You assign an IAM role to your identity provider to give your external user identities managed by your identity provider permissions to access AWS resources in your account. `AssumeRoleWithWebIdentity` doesn't require AWS credentials for authentication. See [OIDC federation for mobile apps](./id_federation_common_scenarios.html#id_roles_providers_oidc_manual) and [Requesting credentials through an OIDC provider](./id_credentials_temp_request.html#api_assumerolewithwebidentity) for more information. @@ -165 +165 @@ When you issue a role from an OIDC provider, you get this special type of sessio -Use this principal type in your policy to allow or deny access based on the built-in trusted web identity provider. To specify the OIDC role session ARN in the `Principal` element of a role trust policy, use the following format: +Use this principal type in your policy to allow or deny access based on the built-in trusted web identity provider. AWS natively supports Amazon, Facebook, Google, and Amazon Cognito as identity providers, so you don't need additional configuration. To specify the OIDC federated principal ARN in the `Principal` element of a role trust policy, use the following format: @@ -178,0 +179,5 @@ Use this principal type in your policy to allow or deny access based on the buil +When using a custom OIDC provider (i.e. it is created and managed in IAM) rather than AWS-supported providers, specify the provider's ARN in your role's trust policy. This configuration allows you to write IAM policies that control access specifically for users authenticated through your custom identity provider. + + + "Principal": { "Federated": "arn:aws:iam::AWS-account-ID:oidc-provider/full-OIDC-identity-provider-URL" } + @@ -183,0 +189,2 @@ Use this principal type in your policy to allow or deny access based on custom t +See [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) for more information. + @@ -186 +193 @@ Use this principal type in your policy to allow or deny access based on custom t -A _SAML federated principal_ is a session principal that results from using the AWS STS `AssumeRoleWithSAML` operation. You can use an external SAML identity provider (IdP) to sign in, and then assume an IAM role using this operation. This leverages identity federation and issues a role session. For more information about which principals can assume a role using this operation, see [Compare AWS STS credentials](./id_credentials_sts-comparison.html). +A _SAML federated principal_ is a session principal that results from using the AWS STS `AssumeRoleWithSAML` operation. Similar to `AssumeRoleWithWebIdentity`, `AssumeRoleWithSAML` doesn't require AWS credentials for authentication. Instead, users first authenticate with their SAML identity provider, then make the `AssumeRoleWithSAML` API call with three required parameters. These parameters are: the SAML assertion (received from their identity provider), the RoleArn (the role they wish to assume), and the PrincipalArn (the ARN of the SAML provider configured in IAM). This call returns temporary AWS security credentials for accessing AWS resources. For more information about which principals can assume a role using this operation, see [Compare AWS STS credentials](./id_credentials_sts-comparison.html). @@ -224 +231 @@ In IAM Identity Center, the principal in a resource-based policy must be defined -## AWS STS federated user session principals +## AWS STS federated user principals @@ -232 +239,3 @@ AWS recommends that you use AWS STS federated user sessions only when necessary, -An _AWS STS federated user session principal_ is a session principal that results from using the AWS STS `GetFederationToken` operation. In this case, AWS STS uses [identity federation](https://aws.amazon.com/identity/federation/) as the method to obtain temporary access tokens instead of using IAM roles. +An AWS STS federated user session principal is created through the `GetFederationToken` operation, but it differs fundamentally from federated role session principals (created via `AssumeRoleWithSAML` or `AssumeRoleWithWebIdentity`). In this case, AWS STS uses [identity federation](https://aws.amazon.com/identity/federation/) as the method to obtain temporary access tokens instead of using IAM roles. Unlike role-based federation methods, `GetFederationToken` requires authentication using user’s AWS long-term credentials before obtaining temporary security credentials. While the operation can be called using either IAM user credentials or AWS account root user credentials, the latter is strongly discouraged for security reasons. For more information, see [Follow best practices to protect your root user credentials](./best-practices.html#lock-away-credentials) in the _IAM User Guide_. + +`GetFederationToken` requires managing and securing long-term AWS credentials. Alternative federation methods such as IAM roles anywhere, SAML federation, OIDC and OAuth2 federation eliminate the need for long-term credential and are recommended as alternatives to using `GetFederationToken` API call.