AWS IAM documentation change
Summary
Reorganized and expanded documentation for OIDC/SAML federated principals and assumed-role sessions. Added explicit guidance about supported IDPs, JWT requirements, and policy limitations.
Security assessment
The changes clarify security-sensitive authentication mechanisms (OIDC/SAML federation) and emphasize role-based access over federated users. While this improves security documentation, there's no evidence of addressing a specific vulnerability.
Diff
diff --git a/IAM/latest/UserGuide/reference_policies_elements_principal.md b/IAM/latest/UserGuide/reference_policies_elements_principal.md index 681aa8c2b..fcc8b01da 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 principalsAWS service principalsAWS service principals in opt-in RegionsAll principalsMore information +How to specify a principalAWS account principalsIAM role principalsRole session principalsAssumed-role session principalsOIDC federated principalsSAML federated principalsIAM user principalsIdentity Center principalsFederated user principalsAWS service principalsAWS service principals in opt-in RegionsAll principalsMore information @@ -30,0 +31,6 @@ You cannot use the `Principal` element in an identity-based policy. Identity-bas + * Assumed-role session principals + + * OIDC federated principals + + * SAML federated principals + @@ -125,2 +130,0 @@ You can specify IAM role principal ARNs in the `Principal` element of a resource -IAM roles are identities that exist in IAM. Roles trust another authenticated identity, such as a principal in AWS or a user from an external identity provider. When a principal or identity assumes a role, they receive temporary security credentials. They can then use those credentials as a role session principal to perform operations in AWS. - @@ -148 +152 @@ Additionally, administrators can design a process to control how role sessions a -### Assumed-role session principals +## Assumed-role session principals @@ -159 +163 @@ When you specify an assumed-role session in a `Principal` element, you cannot us -### OIDC federated principals +## OIDC federated principals @@ -161 +165 @@ When you specify an assumed-role session in a `Principal` element, you cannot us -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. +An OIDC federated principal is the principal used when calling AWS STS `AssumeRoleWithWebIdentity` API with a JSON web token (JWT) from an OIDC compliant IDP, also known as OpenID Provider (OP), to request temporary AWS credentials. An OIDC federated principal can represent an OIDC IDP in your AWS account, or the 4 built in identity providers: Login with Amazon, Google, Facebook, and [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/role-based-access-control.html). @@ -163 +167 @@ An OIDC federated principal is one type of principal created when authenticating -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. +Users, workloads, or systems who’ve been issued a JWT from their OIDC IDP can call `AssumeRoleWithWebIdentity` using the JWT to request temporary AWS security credentials for an IAM role that is configured to trust the OIDC IDP that issued the JWT. The JWT can be an id token, access token, or a JWT token delivered by any other method as long as it meets the [requirements listed by AWS STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html#manage-oidc-provider-prerequisites). For more information, see [Common scenarios](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_federation_common_scenarios.html) and [Requesting credentials through an OIDC provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_assumerolewithwebidentity). @@ -165 +169 @@ Identities who've authenticated with a web identity provider, include a JSON web -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: +Use this principal type in your role trust policy to allow or deny permissions to call `AssumeRoleWIthWebIdentity` using an OIDC IDP that exists in your AWS account, or one of the four built in IDPs. To specify the OIDC federated principal ARN in the `Principal` element of a role trust policy, use one of the following four formats for the built in OIDC IDPs: @@ -179 +183 @@ 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. +When using a OIDC provider you add to your account, such as GitHub, you 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. @@ -184 +188 @@ When using a custom OIDC provider (i.e. it is created and managed in IAM) rather -Use this principal type in your policy to allow or deny access based on custom trusted web identity provider. For example, if GitHub was the trusted web identity provider, the OIDC role session ARN in the Principal element of a role trust policy, uses the following format: +For example, if GitHub was the trusted web identity provider, the OIDC role session ARN in the `Principal` element of a role trust policy uses the following format: @@ -191 +195 @@ See [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/ -### SAML federated principals +OIDC federated principals are not supported in policy types other than role trust policies. @@ -193 +197 @@ See [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/ -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). +## SAML federated principals @@ -195 +199 @@ A _SAML federated principal_ is a session principal that results from using the -When you issue a role from a SAML identity provider, you get this special type of session principal that includes information about the SAML identity provider. +A _SAML federated principal_ is a principal that is used when calling AWS STS `AssumeRoleWithSAML` API to request temporary AWS credentials using a SAML assertion. You can use your SAML identity provider (IDP) to sign in, and then assume an IAM role using this 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 using their SAML assertion, or are redirected to the AWS Sign-In/SAML page to sign into the AWS Management Console. For more information about which principals can assume a role using this operation, see [Compare AWS STS credentials](./id_credentials_sts-comparison.html). @@ -197 +201 @@ When you issue a role from a SAML identity provider, you get this special type o -Use this principal type in your policy to allow or deny access based on the trusted SAML identity provider. To specify the SAML identity role session ARN in the `Principal` element of a role trust policy, use the following format: +Use this principal type in your role trust policy to allow or deny permissions based on the trusted SAML identity provider. To specify the SAML identity role session ARN in the `Principal` element of a role trust policy, use the following format: @@ -237,3 +241 @@ You can specify _federated user sessions_ in the `Principal` element of a resour -AWS recommends that you use AWS STS federated user principals only when necessary, such as when [root user access is required](https://docs.aws.amazon.com/general/latest/gr/root-vs-iam.html#aws_tasks-that-require-root). Instead, [use roles to delegate permissions](./tutorial_cross-account-with-roles.html). - -An AWS STS federated user 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_. +AWS recommends that you limit the use of AWS STS federated user sessions. Instead, use [IAM roles](IAM/latest/UserGuide/tutorial_cross-account-with-roles.html). @@ -241 +243 @@ An AWS STS federated user principal is created through the `GetFederationToken` -`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. +An AWS STS federated user principal is created through the `GetFederationToken` operation called with long-lived IAM credentials. Federated user permissions are the intersection of the principal that called `GetFederationToken` and the session policies passed as parameters to the `GetFederationToken` API.