Package: aws-cdk.aws-cognito-identitypool-alpha
Amazon Cognito Identity Pool Construct LibraryIdentity Pools are in a separate module while the API is being stabilized. Once we stabilize the module, they willbe included into the stableaws-cognitolibrary. Please provide feedback on this experience bycreating anissue here---The APIs of higher level constructs in this module are experimental and under active development.
They are subject to non-backward compatible changes or removal in any future version. These are
not subject to theSemantic Versioningmodel and breaking changes will be
announced in the release notes. This means that while you may use them, you may need to update
your source code when upgrading to a newer version of this package.Amazon Cognito Identity Poolsenable you to grant your users access to other AWS services.Identity Pools are one of the two main components ofAmazon Cognito, which provides authentication, authorization, and
user management for your web and mobile apps. Your users can sign in directly with a user name and password, or through
a third party such as Facebook, Amazon, Google or Apple.The other main component in Amazon Cognito isuser pools. User Pools are user directories that provide sign-up and
sign-in options for your app users.This module is part of theAWS Cloud Development Kitproject.fromaws_cdk.aws_cognito_identitypool_alphaimportIdentityPool,UserPoolAuthenticationProviderTable of ContentsIdentity PoolsAuthenticated and Unauthenticated IdentitiesAuthentication ProvidersUser Pool Authentication ProviderServer Side Token CheckAssociating an External Provider DirectlyOpenIdConnect and SamlCustom ProvidersRole MappingProvider UrlsAuthentication FlowCognito SyncImporting Identity PoolsIdentity PoolsIdentity pools provide temporary AWS credentials for users who are guests (unauthenticated) and for users who have been
authenticated and received a token. An identity pool is a store of user identity data specific to an account.Identity pools can be used in conjunction with Cognito User Pools or by accessing external federated identity providers
directly. Learn more atAmazon Cognito Identity Pools.Authenticated and Unauthenticated IdentitiesIdentity pools define two types of identities: authenticated(user) and unauthenticated (guest). Every identity in
an identity pool is either authenticated or unauthenticated. Each identity pool has a default role for authenticated
identities, and a default role for unauthenticated identities. Absent other overriding rules (see below), these are the
roles that will be assumed by the corresponding users in the authentication process.A basic Identity Pool with minimal configuration has no required props, with default authenticated (user) and
unauthenticated (guest) roles applied to the identity pool:IdentityPool(self,"myIdentityPool")By default, both the authenticated and unauthenticated roles will have no permissions attached. Grant permissions
to roles using the publicauthenticatedRoleandunauthenticatedRoleproperties:importaws_cdk.aws_dynamodbasdynamodb# table: dynamodb.Tableidentity_pool=IdentityPool(self,"myIdentityPool")# Grant permissions to authenticated userstable.grant_read_write_data(identity_pool.authenticated_role)# Grant permissions to unauthenticated guest userstable.grant_read_data(identity_pool.unauthenticated_role)# Or add policy statements straight to the roleidentity_pool.authenticated_role.add_to_principal_policy(iam.PolicyStatement(effect=iam.Effect.ALLOW,actions=["dynamodb:*"],resources=["*"]))The default roles can also be supplied inIdentityPoolProps:stack=Stack()authenticated_role=iam.Role(self,"authRole",assumed_by=iam.ServicePrincipal("service.amazonaws.com"))unauthenticated_role=iam.Role(self,"unauthRole",assumed_by=iam.ServicePrincipal("service.amazonaws.com"))identity_pool=IdentityPool(self,"TestIdentityPoolActions",authenticated_role=authenticated_role,unauthenticated_role=unauthenticated_role)Authentication ProvidersAuthenticated identities belong to users who are authenticated by a public login provider (Amazon Cognito user pools,
Login with Amazon, Sign in with Apple, Facebook, Google, SAML, or any OpenID Connect Providers) or a developer provider
(your own backend authentication process).Authentication providerscan be associated with an Identity Pool by first associating them with a Cognito User Pool or by
associating the provider directly with the identity pool.User Pool Authentication ProviderIn order to attach a user pool to an identity pool as an authentication provider, the identity pool needs properties
from both the user pool and the user pool client. For this reason identity pools use aUserPoolAuthenticationProviderto gather the necessary properties from the user pool constructs.user_pool=cognito.UserPool(self,"Pool")IdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",authentication_providers=IdentityPoolAuthenticationProviders(user_pools=[UserPoolAuthenticationProvider(user_pool=user_pool)]))User pools can also be associated with an identity pool after instantiation. The Identity Pool'saddUserPoolAuthenticationmethod
returns the User Pool Client that has been created:# identity_pool: IdentityPooluser_pool=cognito.UserPool(self,"Pool")user_pool_client=identity_pool.add_user_pool_authentication(UserPoolAuthenticationProvider(user_pool=user_pool))Server Side Token CheckWith theIdentityPoolCDK Construct, by default the pool is configured to check with the integrated user pools to
make sure that the user has not been globally signed out or deleted before the identity pool provides an OIDC token or
AWS credentials for the user.If the user is signed out or deleted, the identity pool will return a 400 Not Authorized error. This setting can be
disabled, however, in several ways.SettingdisableServerSideTokenCheckto true will change the default behavior to no server side token check. Learn
morehere:# identity_pool: IdentityPooluser_pool=cognito.UserPool(self,"Pool")identity_pool.add_user_pool_authentication(UserPoolAuthenticationProvider(user_pool=user_pool,disable_server_side_token_check=True))Associating an External Provider DirectlyOne or moreexternal identity providerscan be associated with an identity pool directly usingauthenticationProviders:IdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",authentication_providers=IdentityPoolAuthenticationProviders(amazon=IdentityPoolAmazonLoginProvider(app_id="amzn1.application.12312k3j234j13rjiwuenf"),facebook=IdentityPoolFacebookLoginProvider(app_id="1234567890123"),google=IdentityPoolGoogleLoginProvider(client_id="12345678012.apps.googleusercontent.com"),apple=IdentityPoolAppleLoginProvider(services_id="com.myappleapp.auth"),twitter=IdentityPoolTwitterLoginProvider(consumer_key="my-twitter-id",consumer_secret="my-twitter-secret")))To associate more than one provider of the same type with the identity pool, use User
Pools, OpenIdConnect, or SAML. Only one provider per external service can be attached directly to the identity pool.OpenId Connect and SamlOpenID Connectis an open standard for
authentication that is supported by a number of login providers. Amazon Cognito supports linking of identities with
OpenID Connect providers that are configured throughAWS Identity and Access Management.An identity provider that supportsSecurity Assertion Markup Language 2.0 (SAML 2.0)can be used to provide a simple
onboarding flow for users. The SAML-supporting identity provider specifies the IAM roles that can be assumed by users
so that different users can be granted different sets of permissions. Associating an OpenId Connect or Saml provider
with an identity pool:# open_id_connect_provider: iam.OpenIdConnectProvider# saml_provider: iam.SamlProviderIdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",authentication_providers=IdentityPoolAuthenticationProviders(open_id_connect_providers=[open_id_connect_provider],saml_providers=[saml_provider]))Custom ProvidersThe identity pool's behavior can be customized further using customdeveloper authenticated identities.
With developer authenticated identities, users can be registered and authenticated via an existing authentication
process while still using Amazon Cognito to synchronize user data and access AWS resources.Like the supported external providers, though, only one custom provider can be directly associated with the identity
pool.# open_id_connect_provider: iam.OpenIdConnectProviderIdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",authentication_providers=IdentityPoolAuthenticationProviders(google=IdentityPoolGoogleLoginProvider(client_id="12345678012.apps.googleusercontent.com"),open_id_connect_providers=[open_id_connect_provider],custom_provider="my-custom-provider.example.com"))Role MappingIn addition to setting default roles for authenticated and unauthenticated users, identity pools can also be used to
define rules to choose the role for each user based on claims in the user's ID token by using Role Mapping. When using
role mapping, it's important to be aware of some of the permissions the role will need. An in depth
review of roles and role mapping can be foundhere.Using atoken-based approachto role mapping will allow mapped roles to be passed through thecognito:rolesorcognito:preferred_roleclaims from the identity provider:fromaws_cdk.aws_cognito_identitypool_alphaimportIdentityPoolProviderUrlIdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",role_mappings=[IdentityPoolRoleMapping(provider_url=IdentityPoolProviderUrl.AMAZON,use_token=True)])Using a rule-based approach to role mapping allows roles to be assigned based on custom claims passed from the identity provider:fromaws_cdk.aws_cognito_identitypool_alphaimportIdentityPoolProviderUrl,RoleMappingMatchType# admin_role: iam.Role# non_admin_role: iam.RoleIdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",# Assign specific roles to users based on whether or not the custom admin claim is passed from the identity providerrole_mappings=[IdentityPoolRoleMapping(provider_url=IdentityPoolProviderUrl.AMAZON,rules=[RoleMappingRule(claim="custom:admin",claim_value="admin",mapped_role=admin_role),RoleMappingRule(claim="custom:admin",claim_value="admin",match_type=RoleMappingMatchType.NOTEQUAL,mapped_role=non_admin_role)])])Role mappings can also be added after instantiation with the Identity Pool'saddRoleMappingsmethod:fromaws_cdk.aws_cognito_identitypool_alphaimportIdentityPoolRoleMapping# identity_pool: IdentityPool# my_added_role_mapping1: IdentityPoolRoleMapping# my_added_role_mapping2: IdentityPoolRoleMapping# my_added_role_mapping3: IdentityPoolRoleMappingidentity_pool.add_role_mappings(my_added_role_mapping1,my_added_role_mapping2,my_added_role_mapping3)Provider UrlsRole mappings must be associated with the url of an Identity Provider which can be suppliedIdentityPoolProviderUrl. Supported Providers have static Urls that can be used:fromaws_cdk.aws_cognito_identitypool_alphaimportIdentityPoolProviderUrlIdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",role_mappings=[IdentityPoolRoleMapping(provider_url=IdentityPoolProviderUrl.FACEBOOK,use_token=True)])For identity providers that don't have static Urls, a custom Url or User Pool Client Url can be supplied:fromaws_cdk.aws_cognito_identitypool_alphaimportIdentityPoolProviderUrlIdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",role_mappings=[IdentityPoolRoleMapping(provider_url=IdentityPoolProviderUrl.user_pool("cognito-idp.my-idp-region.amazonaws.com/my-idp-region_abcdefghi:app_client_id"),use_token=True),IdentityPoolRoleMapping(provider_url=IdentityPoolProviderUrl.custom("my-custom-provider.com"),use_token=True)])If a provider URL is a CDK Token, as it will be if you are trying to use a previously defined Cognito User Pool, you will need to also provide a mappingKey.
This is because by default, the key in the Cloudformation role mapping hash is the providerUrl, and Cloudformation map keys must be concrete strings, they
cannot be references. For example:fromaws_cdk.aws_cognitoimportUserPoolfromaws_cdk.aws_cognito_identitypool_alphaimportIdentityPoolProviderUrl# user_pool: UserPoolIdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",role_mappings=[IdentityPoolRoleMapping(mapping_key="cognito",provider_url=IdentityPoolProviderUrl.user_pool(user_pool.user_pool_provider_url),use_token=True)])Seeherefor more information.Authentication FlowIdentity PoolAuthentication Flowdefaults to the enhanced, simplified flow. The Classic (basic) Authentication Flow
can also be implemented usingallowClassicFlow:IdentityPool(self,"myidentitypool",identity_pool_name="myidentitypool",allow_classic_flow=True)Cognito SyncIt's now recommended to integrateAWS AppSyncfor synchronizing app data across devices, so
Cognito Sync features likePushSync,CognitoEvents, andCognitoStreamsare not a part ofIdentityPool. More
information can be foundhere.Importing Identity PoolsYou can import existing identity pools into your stack using Identity Pool static methods with the Identity Pool Id or
Arn:IdentityPool.from_identity_pool_id(self,"my-imported-identity-pool","us-east-1:dj2823ryiwuhef937")IdentityPool.from_identity_pool_arn(self,"my-imported-identity-pool","arn:aws:cognito-identity:us-east-1:123456789012:identitypool/us-east-1:dj2823ryiwuhef937")