AWS verifiedpermissions documentation change
Summary
Restructured documentation to focus on security aspects of identity sources, added guidance for choosing identity providers, removed technical implementation details about JWT handling, and reorganized content sections
Security assessment
The changes emphasize security considerations when choosing identity providers (highlighting AWS-managed security features and compliance requirements) but do not address any specific vulnerability or incident. The documentation now better guides users toward secure configurations without evidence of patching existing flaws.
Diff
diff --git a/verifiedpermissions/latest/userguide/identity-sources.md b/verifiedpermissions/latest/userguide/identity-sources.md index 48d4aa019..60589c6fc 100644 --- a//verifiedpermissions/latest/userguide/identity-sources.md +++ b//verifiedpermissions/latest/userguide/identity-sources.md @@ -5 +5 @@ -Working with Amazon Cognito identity sourcesWorking with OIDC identity sourcesClient and audience validationClient-side authorization for JWTs +Choosing the right identity provider @@ -7 +7 @@ Working with Amazon Cognito identity sourcesWorking with OIDC identity sourcesCl -# Using Amazon Verified Permissions with identity providers +# Secure your applications with identity sources and tokens @@ -9 +9 @@ Working with Amazon Cognito identity sourcesWorking with OIDC identity sourcesCl -An _identity source_ is a representation of an external identity provider (IdP) in Amazon Verified Permissions. Identity sources provide information from a user who authenticated with an IdP that has a trust relationship with your policy store. When your application makes an authorization request with a token from an identity source, your policy store can make authorization decisions from user properties and access permissions. You can add an Amazon Cognito user pool or a custom OpenID Connect (OIDC) IdP as your identity source. +Secure you applications quickly by creating an _identity source_ to represent an external identity provider (IdP) in Amazon Verified Permissions. Identity sources provide information from a user who authenticated with an IdP that has a trust relationship with your policy store. When your application makes an authorization request with a token from an identity source, your policy store can make authorization decisions from user properties and access permissions. You can add an Amazon Cognito user pool or a custom OpenID Connect (OIDC) IdP as your identity source. @@ -21 +21 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga - * Working with Amazon Cognito identity sources + * Choosing the right identity provider @@ -23 +23 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga - * Working with OIDC identity sources + * [Working with Amazon Cognito identity sources](./identity-sources-cognito.html) @@ -25 +25 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga - * Client and audience validation + * [Working with OIDC identity sources](./identity-sources-oidc.html) @@ -27 +26,0 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga - * Client-side authorization for JWTs @@ -29 +27,0 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga - * [Creating Amazon Verified Permissions identity sources](./identity-sources-create.html) @@ -31 +28,0 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga - * [Editing Amazon Verified Permissions identity sources](./identity-sources-edit.html) @@ -33 +30 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga - * [Mapping identity provider tokens to schema](./identity-sources-map-token-to-schema.html) +## Choosing the right identity provider @@ -34,0 +32 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga +While Verified Permissions works with a variety of IdPs, consider the following when deciding which one to use in your application: @@ -35,0 +34 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga +Use Amazon Cognito when: @@ -38 +37 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga -## Working with Amazon Cognito identity sources + * You're building new applications without existing identity infrastructure @@ -40 +39 @@ For a step-by-step walkthrough that builds authorization logic for Amazon API Ga -Verified Permissions works closely with Amazon Cognito user pools. Amazon Cognito JWTs have a predictable structure. Verified Permissions recognizes this structure and draws maximum benefit from the information that it contains. For example, you can implement a role-based access control (RBAC) authorization model with either ID tokens or access tokens. + * You want AWS-managed user pools with built-in security features @@ -42 +41 @@ Verified Permissions works closely with Amazon Cognito user pools. Amazon Cognit -A new Amazon Cognito user pools identity source requires the following information: + * You need social identity provider integration @@ -44 +43 @@ A new Amazon Cognito user pools identity source requires the following informati - * The AWS Region. + * You want simplified token management @@ -46 +44,0 @@ A new Amazon Cognito user pools identity source requires the following informati - * The user pool ID. @@ -48 +45,0 @@ A new Amazon Cognito user pools identity source requires the following informati - * The principal entity type that you want to associate with your identity source, for example `MyCorp::User`. @@ -50 +46,0 @@ A new Amazon Cognito user pools identity source requires the following informati - * The principal group entity type that you want to associate with your identity source, for example `MyCorp::UserGroup`. @@ -52 +48 @@ A new Amazon Cognito user pools identity source requires the following informati - * The client IDs from your user pool that you want to authorize to make requests to your policy store. +Use OIDC providers when: @@ -54,0 +51 @@ A new Amazon Cognito user pools identity source requires the following informati + * You have existing identity infrastructure (Auth0, Okta, Azure AD) @@ -55,0 +53 @@ A new Amazon Cognito user pools identity source requires the following informati + * You need to maintain centralized user management @@ -57 +55 @@ A new Amazon Cognito user pools identity source requires the following informati -Because Verified Permissions only works with Amazon Cognito user pools in the same AWS account, you can't specify an identity source in another account. Verified Permissions sets the _entity prefix_ —the identity-source identifier that you must reference in policies that act on user pool principals—to the ID of your user pool, for example `us-west-2_EXAMPLE`. In this case, you would reference a user in that user pool with ID `a1b2c3d4-5678-90ab-cdef-EXAMPLE22222` as `us-west-2_EXAMPLE|a1b2c3d4-5678-90ab-cdef-EXAMPLE22222` + * You have compliance requirements for specific IdPs @@ -59 +56,0 @@ Because Verified Permissions only works with Amazon Cognito user pools in the sa -User pool token _claims_ can contain attributes, scopes, groups, client IDs, and custom data. [Amazon Cognito JWTs](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) have the ability to include a variety of information that can contribute to authorization decisions in Verified Permissions. These include: @@ -61 +57,0 @@ User pool token _claims_ can contain attributes, scopes, groups, client IDs, and - 1. Username and group claims with a `cognito:` prefix @@ -63,202 +58,0 @@ User pool token _claims_ can contain attributes, scopes, groups, client IDs, and - 2. [Custom user attributes](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#user-pool-settings-custom-attributes) with a `custom: prefix` - - 3. Custom claims added at runtime - - 4. OIDC standard claims like `sub` and `email` - - - - -We cover these claims in detail, and how to manage them in Verified Permissions policies, in [Mapping identity provider tokens to schema](./identity-sources-map-token-to-schema.html). - -###### Important - -Although you can revoke Amazon Cognito tokens before they expire, JWTs are considered to be stateless resources that are self-contained with a signature and validity. Services that conform with [the JSON Web Token RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) are expected to validate tokens remotely and aren't required to validate them with the issuer. This means that it is possible for Verified Permissions to grant access based on a token that was revoked or issued for a user that was later deleted. To mitigate this risk, we recommend that you create your tokens with the shortest possible validity duration and revoke refresh tokens when you want to remove authorization to continue a user's session. For more information, see [Ending user sessions with token revocation](https://docs.aws.amazon.com/cognito/latest/developerguide/token-revocation.html) - -This following example shows how you might create a policy that references some of the Amazon Cognito user pools claims associated with a principal. - - - permit( - principal, - action, - resource == ExampleCo::Photo::"VacationPhoto94.jpg" - ) - when { - principal["cognito:username"]) == "alice" && - principal["custom:department"]) == "Finance" - }; - -This following example shows how you might create a policy that references a principal that's a user in a Cognito user pool. Note that the principal ID takes the form of `"<userpool-id>|<sub>"`. - - - permit( - principal == ExampleCo::User::"us-east-1_example|a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", - action, - resource == ExampleCo::Photo::"VacationPhoto94.jpg" - ); - -Cedar policies for user pool identity sources in Verified Permissions use a special syntax for claim names that contain characters other than alphanumeric and underscore (`_`). This includes user pool prefix claims that contain a `:` character, like `cognito:username` and `custom:department`. To write a policy condition that references the `cognito:username` or `custom:department` claim, write them as `principal["cognito:username"]` and `principal["custom:department"]`, respectively. - -###### Note - -If a token contains a claim with a `cognito:` or `custom:` prefix and a claim name with the literal value `cognito` or `custom`, an authorization request with [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html) will fail with a `ValidationException`. - -For more information about mapping claims, see [Mapping ID tokens to schema](./identity-sources-map-token-to-schema.html#identity-sources-map-id-token). For more information about authorization for Amazon Cognito users, see [Authorization with Amazon Verified Permissions](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html) in the _Amazon Cognito Developer Guide_. - -## Working with OIDC identity sources - -You can also configure any compliant OpenID Connect (OIDC) IdP as the identity source of a policy store. OIDC providers are similar to Amazon Cognito user pools: they produce JWTs as the product of authentication. To add an OIDC provider, you must provide an issuer URL - -A new OIDC identity source requires the following information: - - * The issuer URL. Verified Permissions must be able to discover a `.well-known/openid-configuration` endpoint at this URL. - - * CNAME records that don't include wild cards. For example, `a.example.com` can't be mapped to `*.example.net`. Conversely, `*.example.com` can't be mapped to `a.example.net`. - - * The token type that you want to use in authorization requests. In this case, you chose **Identity token**. - - * The user entity type that you want to associate with your identity source, for example `MyCorp::User`. - - * The group entity type that you want to associate with your identity source, for example `MyCorp::UserGroup`. - - * An example ID token, or a definition of the claims in the ID token. - - * The prefix that you want to apply to user and group entity IDs. In the CLI and API, you can choose this prefix. In policy stores that you create with the **Set up with API Gateway and an identity provider** or **Guided setup** option, Verified Permissions assigns a prefix of the issuer name minus `https://`, for example `MyCorp::User::"auth.example.com|a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"`. - - - - -For more information about using API operations to authorize requests from OIDC sources, see [Available API operations for authorization](./authorization.html#authorization-operations). - -This following example shows how you might create a policy that permits access to year-end reports for employees in the accounting department, have a confidential classification, and aren't in a satellite office. Verified Permissions derives these attributes from the claims in the principal's ID token. - -Note that when referencing a group in the principal, you must use the `in` operator for the policy to be evaluated correctly. - - - permit( - principal in MyCorp::UserGroup::"MyOIDCProvider|Accounting", - action, - resource in MyCorp::Folder::"YearEnd2024" - ) when { - principal.jobClassification == "Confidential" && - !(principal.location like "SatelliteOffice*") - }; - -## Client and audience validation - -When you add an identity source to a policy store, Verified Permissions has configuration options that verify that ID and access tokens are being used as intended. This validation happens in the processing of `IsAuthorizedWithToken` and `BatchIsAuthorizedWithToken` API requests. The behavior differs between ID and access tokens, and between Amazon Cognito and OIDC identity sources. With Amazon Cognito user pools providers, Verified Permissions can validate the client ID in both ID and access tokens. With OIDC providers, Verified Permissions can validate the client ID in ID tokens, and the audience in access tokens. - -A _client ID_ is an identifier associated with the identity provider instance that your application uses, for example `1example23456789`. An _audience_ is a URL path associated with the intended _relying party_ , or destination, of the access token, for example `https://mytoken.example.com`. When using access tokens, the `aud` claim is always associated with the audience. - -Verified Permissions performs identity source audience and client validation as follows: - -Amazon Cognito - - -Amazon Cognito ID tokens have an `aud` claim that contains the [app client](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-client-apps.html) ID. Access tokens have a `client_id` claim that also contains the app client ID. - -When you enter one or more values for **Client application validation** in your identity source, Verified Permissions compares this list of app client IDs to the ID token `aud` claim or the access token `client_id` claim. Verified Permissions doesn't validate a relying-party audience URL for Amazon Cognito identity sources. - -OIDC - - -OIDC ID tokens have an `aud` claim that contains client IDs, such as `1example23456789`. - -OIDC Access tokens have an `aud` claim that contains the audience URL for the token, such as `https://myapplication.example.com`, and a `client_id` claim that contains client IDs, such as `1example23456789`. - -When setting up your policy store, enter one or more values for **Audience validation** that your policy store with use to validate the audience of a token. - - * **ID tokens** – Verified Permissions validates the client ID by checking that at least one member of the client IDs in the `aud` claim matches an audience validation value. - - * **Access tokens** – Verified Permissions validates the audience by checking that the URL in the `aud` claim matches an audience validation value. If no `aud` claim exists, the audience can be validated using the `cid` or `client_id` claims. Check with your identity provider for the correct audience claim and format. - - - - -## Client-side authorization for JWTs - -You might want to process JSON web tokens in your application and pass their claims to Verified Permissions without using a policy store identity source. You can extract your entity attributes from a JSON Web Token (JWT) and parse it into Verified Permissions. - -This example shows how you might call Verified Permissions from an application using a JWT.¹ - - - async function authorizeUsingJwtToken(jwtToken) { - - const payload = await verifier.verify(jwtToken); - - let principalEntity = { - entityType: "PhotoFlash::User", // the application needs to fill in the relevant user type - entityId: payload["sub"], // the application need to use the claim that represents the user-id - }; - let resourceEntity = { - entityType: "PhotoFlash::Photo", //the application needs to fill in the relevant resource type