# Amazon Cognito Identity Pool Construct Library
<!--BEGIN STABILITY BANNER-->---
> The APIs of higher level constructs in this module are in **developer preview** before they
> become stable. We will only make breaking changes to address unforeseen API issues. Therefore,
> these APIs are not subject to [Semantic Versioning](https://semver.org/), and breaking changes
> will be announced in 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.
---
<!--END STABILITY BANNER-->
> **Identity Pools are in a separate module while the API is being stabilized. Once we stabilize the module, they will**
> **be included into the stable [aws-cognito](../aws-cognito) library. Please provide feedback on this experience by**
> **creating an [issue here](https://github.com/aws/aws-cdk/issues/new/choose)**
[Amazon Cognito Identity Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) enable you to grant your users access to other AWS services.
Identity Pools are one of the two main components of [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html), which provides authentication, authorization, and
user management for your web and mobile apps. Your users can sign in through a a trusted identity provider, like a user
pool or a SAML 2.0 service, as well as with third party providers such as Facebook, Amazon, Google or Apple.
The other main component in Amazon Cognito is [user pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html). User Pools are user directories that provide sign-up and
sign-in options for your app users.
This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.
```python
from aws_cdk.aws_cognito_identitypool_alpha import IdentityPool, UserPoolAuthenticationProvider
```
## Table of Contents
* [Identity Pools](#identity-pools)
* [Authenticated and Unauthenticated Identities](#authenticated-and-unauthenticated-identities)
* [Authentication Providers](#authentication-providers)
* [User Pool Authentication Provider](#user-pool-authentication-provider)
* [Server Side Token Check](#server-side-token-check)
* [Associating an External Provider Directly](#associating-an-external-provider-directly)
* [OpenIdConnect and Saml](#openid-connect-and-saml)
* [Custom Providers](#custom-providers)
* [Role Mapping](#role-mapping)
* [Provider Urls](#provider-urls)
* [Authentication Flow](#authentication-flow)
* [Cognito Sync](#cognito-sync)
* [Importing Identity Pools](#importing-identity-pools)
## Identity Pools
Identity pools provide temporary AWS credentials for users who are guests (unauthenticated) and for users who have
authenticated by presenting a token from another identity provider. 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 at [Amazon Cognito Identity Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html).
### Authenticated and Unauthenticated Identities
Identity 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:
```python
IdentityPool(self, "myIdentityPool")
```
By default, both the authenticated and unauthenticated roles will have no permissions attached. When granting permissions,
you should ensure that you are granting the least privileged permissions required for your use case. Grant permissions
to roles using the public `authenticatedRole` and `unauthenticatedRole` properties:
```python
import aws_cdk.aws_dynamodb as dynamodb
# table: dynamodb.Table
identity_pool = IdentityPool(self, "myIdentityPool")
# Grant permissions to authenticated users
table.grant_read_write_data(identity_pool.authenticated_role)
# Grant permissions to unauthenticated guest users
table.grant_read_data(identity_pool.unauthenticated_role)
# Or add policy statements straight to the role
identity_pool.authenticated_role.add_to_principal_policy(iam.PolicyStatement(
effect=iam.Effect.ALLOW,
actions=["dynamodb:UpdateItem"],
resources=[table.table_arn]
))
```
The default roles can also be supplied in `IdentityPoolProps`:
```python
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 Providers
Authenticated 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 providers](https://docs.aws.amazon.com/cognito/latest/developerguide/external-identity-providers.html) can 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 Provider
In 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 a `UserPoolAuthenticationProvider`
to gather the necessary properties from the user pool constructs.
```python
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's `addUserPoolAuthentication` method
returns the User Pool Client that has been created:
```python
# identity_pool: IdentityPool
user_pool = cognito.UserPool(self, "Pool")
user_pool_client = identity_pool.add_user_pool_authentication(UserPoolAuthenticationProvider(
user_pool=user_pool
))
```
#### Server Side Token Check
With the `IdentityPool` CDK 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.
Setting `disableServerSideTokenCheck` to true will change the default behavior to no server side token check. Learn
more [here](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_CognitoIdentityProvider.html#CognitoIdentity-Type-CognitoIdentityProvider-ServerSideTokenCheck):
```python
# identity_pool: IdentityPool
user_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 Directly
One or more [external identity providers](https://docs.aws.amazon.com/cognito/latest/developerguide/external-identity-providers.html) can be associated with an identity pool directly using
`authenticationProviders`:
```python
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 Saml
[OpenID Connect](https://docs.aws.amazon.com/cognito/latest/developerguide/open-id.html) is 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 through [AWS Identity and Access Management](http://aws.amazon.com/iam/).
An identity provider that supports [Security Assertion Markup Language 2.0 (SAML 2.0)](https://docs.aws.amazon.com/cognito/latest/developerguide/saml-identity-provider.html) 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:
```python
# open_id_connect_provider: iam.OpenIdConnectProvider
# saml_provider: iam.SamlProvider
IdentityPool(self, "myidentitypool",
identity_pool_name="myidentitypool",
authentication_providers=IdentityPoolAuthenticationProviders(
open_id_connect_providers=[open_id_connect_provider],
saml_providers=[saml_provider]
)
)
```
#### Custom Providers
The identity pool's behavior can be customized further using custom [developer authenticated identities](https://docs.aws.amazon.com/cognito/latest/developerguide/developer-authenticated-identities.html).
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.
```python
# open_id_connect_provider: iam.OpenIdConnectProvider
IdentityPool(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 Mapping
In 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, and that the least privileged
roles necessary are given for your specific use case. An in depth
review of roles and role mapping can be found [here](https://docs.aws.amazon.com/cognito/latest/developerguide/role-based-access-control.html).
Using a [token-based approach](https://docs.aws.amazon.com/cognito/latest/developerguide/role-based-access-control.html#using-tokens-to-assign-roles-to-users) to role mapping will allow mapped roles to be passed through the `cognito:roles` or
`cognito:preferred_role` claims from the identity provider:
```python
from aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl
IdentityPool(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:
```python
from aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl, RoleMappingMatchType
# admin_role: iam.Role
# non_admin_role: iam.Role
IdentityPool(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 provider
role_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's `addRoleMappings` method:
```python
from aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolRoleMapping
# identity_pool: IdentityPool
# my_added_role_mapping1: IdentityPoolRoleMapping
# my_added_role_mapping2: IdentityPoolRoleMapping
# my_added_role_mapping3: IdentityPoolRoleMapping
identity_pool.add_role_mappings(my_added_role_mapping1, my_added_role_mapping2, my_added_role_mapping3)
```
#### Provider Urls
Role mappings must be associated with the url of an Identity Provider which can be supplied
`IdentityPoolProviderUrl`. Supported Providers have static Urls that can be used:
```python
from aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl
IdentityPool(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 can be supplied:
```python
from aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl
IdentityPool(self, "myidentitypool",
identity_pool_name="myidentitypool",
role_mappings=[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:
```python
from aws_cdk.aws_cognito import UserPool, UserPoolClient
from aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl
# user_pool: UserPool
# user_pool_client: UserPoolClient
IdentityPool(self, "myidentitypool",
identity_pool_name="myidentitypool",
role_mappings=[IdentityPoolRoleMapping(
mapping_key="cognito",
provider_url=IdentityPoolProviderUrl.user_pool(user_pool, user_pool_client),
use_token=True
)]
)
```
See [here](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cognito-identitypoolroleattachment-rolemapping.html#cfn-cognito-identitypoolroleattachment-rolemapping-identityprovider) for more information.
### Authentication Flow
Identity Pool [Authentication Flow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html) defaults to the enhanced, simplified flow. The Classic (basic) Authentication Flow
can also be implemented using `allowClassicFlow`:
```python
IdentityPool(self, "myidentitypool",
identity_pool_name="myidentitypool",
allow_classic_flow=True
)
```
### Cognito Sync
It's now recommended to integrate [AWS AppSync](https://aws.amazon.com/appsync/) for synchronizing app data across devices, so
Cognito Sync features like `PushSync`, `CognitoEvents`, and `CognitoStreams` are not a part of `IdentityPool`. More
information can be found [here](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-sync.html).
### Importing Identity Pools
You can import existing identity pools into your stack using Identity Pool static methods with the Identity Pool Id or
Arn:
```python
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")
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-cognito-identitypool-alpha",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Amazon Web Services",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/61/22/f919b75e76e2544774cae47d46719aa0e7e4eb76e9bafd2cf2e1db1613d3/aws_cdk_aws_cognito_identitypool_alpha-2.170.0a0.tar.gz",
"platform": null,
"description": "# Amazon Cognito Identity Pool Construct Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> The APIs of higher level constructs in this module are in **developer preview** before they\n> become stable. We will only make breaking changes to address unforeseen API issues. Therefore,\n> these APIs are not subject to [Semantic Versioning](https://semver.org/), and breaking changes\n> will be announced in release notes. This means that while you may use them, you may need to\n> update your source code when upgrading to a newer version of this package.\n\n---\n<!--END STABILITY BANNER-->\n\n> **Identity Pools are in a separate module while the API is being stabilized. Once we stabilize the module, they will**\n> **be included into the stable [aws-cognito](../aws-cognito) library. Please provide feedback on this experience by**\n> **creating an [issue here](https://github.com/aws/aws-cdk/issues/new/choose)**\n\n[Amazon Cognito Identity Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) enable you to grant your users access to other AWS services.\n\nIdentity Pools are one of the two main components of [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html), which provides authentication, authorization, and\nuser management for your web and mobile apps. Your users can sign in through a a trusted identity provider, like a user\npool or a SAML 2.0 service, as well as with third party providers such as Facebook, Amazon, Google or Apple.\n\nThe other main component in Amazon Cognito is [user pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html). User Pools are user directories that provide sign-up and\nsign-in options for your app users.\n\nThis module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.\n\n```python\nfrom aws_cdk.aws_cognito_identitypool_alpha import IdentityPool, UserPoolAuthenticationProvider\n```\n\n## Table of Contents\n\n* [Identity Pools](#identity-pools)\n\n * [Authenticated and Unauthenticated Identities](#authenticated-and-unauthenticated-identities)\n * [Authentication Providers](#authentication-providers)\n\n * [User Pool Authentication Provider](#user-pool-authentication-provider)\n * [Server Side Token Check](#server-side-token-check)\n * [Associating an External Provider Directly](#associating-an-external-provider-directly)\n * [OpenIdConnect and Saml](#openid-connect-and-saml)\n * [Custom Providers](#custom-providers)\n * [Role Mapping](#role-mapping)\n\n * [Provider Urls](#provider-urls)\n * [Authentication Flow](#authentication-flow)\n * [Cognito Sync](#cognito-sync)\n * [Importing Identity Pools](#importing-identity-pools)\n\n## Identity Pools\n\nIdentity pools provide temporary AWS credentials for users who are guests (unauthenticated) and for users who have\nauthenticated by presenting a token from another identity provider. An identity pool is a store of user identity data\nspecific to an account.\n\nIdentity pools can be used in conjunction with Cognito User Pools or by accessing external federated identity providers\ndirectly. Learn more at [Amazon Cognito Identity Pools](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html).\n\n### Authenticated and Unauthenticated Identities\n\nIdentity pools define two types of identities: authenticated(`user`) and unauthenticated (`guest`). Every identity in\nan identity pool is either authenticated or unauthenticated. Each identity pool has a default role for authenticated\nidentities, and a default role for unauthenticated identities. Absent other overriding rules (see below), these are the\nroles that will be assumed by the corresponding users in the authentication process.\n\nA basic Identity Pool with minimal configuration has no required props, with default authenticated (user) and\nunauthenticated (guest) roles applied to the identity pool:\n\n```python\nIdentityPool(self, \"myIdentityPool\")\n```\n\nBy default, both the authenticated and unauthenticated roles will have no permissions attached. When granting permissions,\nyou should ensure that you are granting the least privileged permissions required for your use case. Grant permissions\nto roles using the public `authenticatedRole` and `unauthenticatedRole` properties:\n\n```python\nimport aws_cdk.aws_dynamodb as dynamodb\n# table: dynamodb.Table\n\n\nidentity_pool = IdentityPool(self, \"myIdentityPool\")\n\n# Grant permissions to authenticated users\ntable.grant_read_write_data(identity_pool.authenticated_role)\n# Grant permissions to unauthenticated guest users\ntable.grant_read_data(identity_pool.unauthenticated_role)\n\n# Or add policy statements straight to the role\nidentity_pool.authenticated_role.add_to_principal_policy(iam.PolicyStatement(\n effect=iam.Effect.ALLOW,\n actions=[\"dynamodb:UpdateItem\"],\n resources=[table.table_arn]\n))\n```\n\nThe default roles can also be supplied in `IdentityPoolProps`:\n\n```python\nstack = Stack()\nauthenticated_role = iam.Role(self, \"authRole\",\n assumed_by=iam.ServicePrincipal(\"service.amazonaws.com\")\n)\nunauthenticated_role = iam.Role(self, \"unauthRole\",\n assumed_by=iam.ServicePrincipal(\"service.amazonaws.com\")\n)\nidentity_pool = IdentityPool(self, \"TestIdentityPoolActions\",\n authenticated_role=authenticated_role,\n unauthenticated_role=unauthenticated_role\n)\n```\n\n### Authentication Providers\n\nAuthenticated identities belong to users who are authenticated by a public login provider (Amazon Cognito user pools,\nLogin with Amazon, Sign in with Apple, Facebook, Google, SAML, or any OpenID Connect Providers) or a developer provider\n(your own backend authentication process).\n\n[Authentication providers](https://docs.aws.amazon.com/cognito/latest/developerguide/external-identity-providers.html) can be associated with an Identity Pool by first associating them with a Cognito User Pool or by\nassociating the provider directly with the identity pool.\n\n#### User Pool Authentication Provider\n\nIn order to attach a user pool to an identity pool as an authentication provider, the identity pool needs properties\nfrom both the user pool and the user pool client. For this reason identity pools use a `UserPoolAuthenticationProvider`\nto gather the necessary properties from the user pool constructs.\n\n```python\nuser_pool = cognito.UserPool(self, \"Pool\")\n\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n authentication_providers=IdentityPoolAuthenticationProviders(\n user_pools=[UserPoolAuthenticationProvider(user_pool=user_pool)]\n )\n)\n```\n\nUser pools can also be associated with an identity pool after instantiation. The Identity Pool's `addUserPoolAuthentication` method\nreturns the User Pool Client that has been created:\n\n```python\n# identity_pool: IdentityPool\n\nuser_pool = cognito.UserPool(self, \"Pool\")\nuser_pool_client = identity_pool.add_user_pool_authentication(UserPoolAuthenticationProvider(\n user_pool=user_pool\n))\n```\n\n#### Server Side Token Check\n\nWith the `IdentityPool` CDK Construct, by default the pool is configured to check with the integrated user pools to\nmake sure that the user has not been globally signed out or deleted before the identity pool provides an OIDC token or\nAWS credentials for the user.\n\nIf the user is signed out or deleted, the identity pool will return a 400 Not Authorized error. This setting can be\ndisabled, however, in several ways.\n\nSetting `disableServerSideTokenCheck` to true will change the default behavior to no server side token check. Learn\nmore [here](https://docs.aws.amazon.com/cognitoidentity/latest/APIReference/API_CognitoIdentityProvider.html#CognitoIdentity-Type-CognitoIdentityProvider-ServerSideTokenCheck):\n\n```python\n# identity_pool: IdentityPool\n\nuser_pool = cognito.UserPool(self, \"Pool\")\nidentity_pool.add_user_pool_authentication(UserPoolAuthenticationProvider(\n user_pool=user_pool,\n disable_server_side_token_check=True\n))\n```\n\n#### Associating an External Provider Directly\n\nOne or more [external identity providers](https://docs.aws.amazon.com/cognito/latest/developerguide/external-identity-providers.html) can be associated with an identity pool directly using\n`authenticationProviders`:\n\n```python\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n authentication_providers=IdentityPoolAuthenticationProviders(\n amazon=IdentityPoolAmazonLoginProvider(\n app_id=\"amzn1.application.12312k3j234j13rjiwuenf\"\n ),\n facebook=IdentityPoolFacebookLoginProvider(\n app_id=\"1234567890123\"\n ),\n google=IdentityPoolGoogleLoginProvider(\n client_id=\"12345678012.apps.googleusercontent.com\"\n ),\n apple=IdentityPoolAppleLoginProvider(\n services_id=\"com.myappleapp.auth\"\n ),\n twitter=IdentityPoolTwitterLoginProvider(\n consumer_key=\"my-twitter-id\",\n consumer_secret=\"my-twitter-secret\"\n )\n )\n)\n```\n\nTo associate more than one provider of the same type with the identity pool, use User\nPools, OpenIdConnect, or SAML. Only one provider per external service can be attached directly to the identity pool.\n\n#### OpenId Connect and Saml\n\n[OpenID Connect](https://docs.aws.amazon.com/cognito/latest/developerguide/open-id.html) is an open standard for\nauthentication that is supported by a number of login providers. Amazon Cognito supports linking of identities with\nOpenID Connect providers that are configured through [AWS Identity and Access Management](http://aws.amazon.com/iam/).\n\nAn identity provider that supports [Security Assertion Markup Language 2.0 (SAML 2.0)](https://docs.aws.amazon.com/cognito/latest/developerguide/saml-identity-provider.html) can be used to provide a simple\nonboarding flow for users. The SAML-supporting identity provider specifies the IAM roles that can be assumed by users\nso that different users can be granted different sets of permissions. Associating an OpenId Connect or Saml provider\nwith an identity pool:\n\n```python\n# open_id_connect_provider: iam.OpenIdConnectProvider\n# saml_provider: iam.SamlProvider\n\n\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n authentication_providers=IdentityPoolAuthenticationProviders(\n open_id_connect_providers=[open_id_connect_provider],\n saml_providers=[saml_provider]\n )\n)\n```\n\n#### Custom Providers\n\nThe identity pool's behavior can be customized further using custom [developer authenticated identities](https://docs.aws.amazon.com/cognito/latest/developerguide/developer-authenticated-identities.html).\nWith developer authenticated identities, users can be registered and authenticated via an existing authentication\nprocess while still using Amazon Cognito to synchronize user data and access AWS resources.\n\nLike the supported external providers, though, only one custom provider can be directly associated with the identity\npool.\n\n```python\n# open_id_connect_provider: iam.OpenIdConnectProvider\n\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n authentication_providers=IdentityPoolAuthenticationProviders(\n google=IdentityPoolGoogleLoginProvider(\n client_id=\"12345678012.apps.googleusercontent.com\"\n ),\n open_id_connect_providers=[open_id_connect_provider],\n custom_provider=\"my-custom-provider.example.com\"\n )\n)\n```\n\n### Role Mapping\n\nIn addition to setting default roles for authenticated and unauthenticated users, identity pools can also be used to\ndefine rules to choose the role for each user based on claims in the user's ID token by using Role Mapping. When using\nrole mapping, it's important to be aware of some of the permissions the role will need, and that the least privileged\nroles necessary are given for your specific use case. An in depth\nreview of roles and role mapping can be found [here](https://docs.aws.amazon.com/cognito/latest/developerguide/role-based-access-control.html).\n\nUsing a [token-based approach](https://docs.aws.amazon.com/cognito/latest/developerguide/role-based-access-control.html#using-tokens-to-assign-roles-to-users) to role mapping will allow mapped roles to be passed through the `cognito:roles` or\n`cognito:preferred_role` claims from the identity provider:\n\n```python\nfrom aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl\n\n\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n role_mappings=[IdentityPoolRoleMapping(\n provider_url=IdentityPoolProviderUrl.AMAZON,\n use_token=True\n )]\n)\n```\n\nUsing a rule-based approach to role mapping allows roles to be assigned based on custom claims passed from the identity provider:\n\n```python\nfrom aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl, RoleMappingMatchType\n\n# admin_role: iam.Role\n# non_admin_role: iam.Role\n\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n # Assign specific roles to users based on whether or not the custom admin claim is passed from the identity provider\n role_mappings=[IdentityPoolRoleMapping(\n provider_url=IdentityPoolProviderUrl.AMAZON,\n rules=[RoleMappingRule(\n claim=\"custom:admin\",\n claim_value=\"admin\",\n mapped_role=admin_role\n ), RoleMappingRule(\n claim=\"custom:admin\",\n claim_value=\"admin\",\n match_type=RoleMappingMatchType.NOTEQUAL,\n mapped_role=non_admin_role\n )\n ]\n )]\n)\n```\n\nRole mappings can also be added after instantiation with the Identity Pool's `addRoleMappings` method:\n\n```python\nfrom aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolRoleMapping\n\n# identity_pool: IdentityPool\n# my_added_role_mapping1: IdentityPoolRoleMapping\n# my_added_role_mapping2: IdentityPoolRoleMapping\n# my_added_role_mapping3: IdentityPoolRoleMapping\n\n\nidentity_pool.add_role_mappings(my_added_role_mapping1, my_added_role_mapping2, my_added_role_mapping3)\n```\n\n#### Provider Urls\n\nRole mappings must be associated with the url of an Identity Provider which can be supplied\n`IdentityPoolProviderUrl`. Supported Providers have static Urls that can be used:\n\n```python\nfrom aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl\n\n\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n role_mappings=[IdentityPoolRoleMapping(\n provider_url=IdentityPoolProviderUrl.FACEBOOK,\n use_token=True\n )]\n)\n```\n\nFor identity providers that don't have static Urls, a custom Url can be supplied:\n\n```python\nfrom aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl\n\n\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n role_mappings=[IdentityPoolRoleMapping(\n provider_url=IdentityPoolProviderUrl.custom(\"my-custom-provider.com\"),\n use_token=True\n )\n ]\n)\n```\n\nIf 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.\nThis is because by default, the key in the Cloudformation role mapping hash is the providerUrl, and Cloudformation map keys must be concrete strings, they\ncannot be references. For example:\n\n```python\nfrom aws_cdk.aws_cognito import UserPool, UserPoolClient\nfrom aws_cdk.aws_cognito_identitypool_alpha import IdentityPoolProviderUrl\n\n# user_pool: UserPool\n# user_pool_client: UserPoolClient\n\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n role_mappings=[IdentityPoolRoleMapping(\n mapping_key=\"cognito\",\n provider_url=IdentityPoolProviderUrl.user_pool(user_pool, user_pool_client),\n use_token=True\n )]\n)\n```\n\nSee [here](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cognito-identitypoolroleattachment-rolemapping.html#cfn-cognito-identitypoolroleattachment-rolemapping-identityprovider) for more information.\n\n### Authentication Flow\n\nIdentity Pool [Authentication Flow](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication-flow.html) defaults to the enhanced, simplified flow. The Classic (basic) Authentication Flow\ncan also be implemented using `allowClassicFlow`:\n\n```python\nIdentityPool(self, \"myidentitypool\",\n identity_pool_name=\"myidentitypool\",\n allow_classic_flow=True\n)\n```\n\n### Cognito Sync\n\nIt's now recommended to integrate [AWS AppSync](https://aws.amazon.com/appsync/) for synchronizing app data across devices, so\nCognito Sync features like `PushSync`, `CognitoEvents`, and `CognitoStreams` are not a part of `IdentityPool`. More\ninformation can be found [here](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-sync.html).\n\n### Importing Identity Pools\n\nYou can import existing identity pools into your stack using Identity Pool static methods with the Identity Pool Id or\nArn:\n\n```python\nIdentityPool.from_identity_pool_id(self, \"my-imported-identity-pool\", \"us-east-1:dj2823ryiwuhef937\")\nIdentityPool.from_identity_pool_arn(self, \"my-imported-identity-pool\", \"arn:aws:cognito-identity:us-east-1:123456789012:identitypool/us-east-1:dj2823ryiwuhef937\")\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS::Cognito Identity Pools",
"version": "2.170.0a0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b9d8443f97bb59442fc82e5f66a3f52bb61de042a47fd963b8780a2d81838667",
"md5": "9ae3ec5e7d155ca29aa4286074f43d05",
"sha256": "51025006390e83cfa194c908265c631d2946a64eb2b7b5cbd33db7033c8fe9c5"
},
"downloads": -1,
"filename": "aws_cdk.aws_cognito_identitypool_alpha-2.170.0a0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ae3ec5e7d155ca29aa4286074f43d05",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 98439,
"upload_time": "2024-11-22T04:41:27",
"upload_time_iso_8601": "2024-11-22T04:41:27.567311Z",
"url": "https://files.pythonhosted.org/packages/b9/d8/443f97bb59442fc82e5f66a3f52bb61de042a47fd963b8780a2d81838667/aws_cdk.aws_cognito_identitypool_alpha-2.170.0a0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6122f919b75e76e2544774cae47d46719aa0e7e4eb76e9bafd2cf2e1db1613d3",
"md5": "39257fc1cadfc58420f20a8e269fff20",
"sha256": "6cf272af6fc7e5b778d62e08599f85867a4496a1dfa14b13160a01d1328fdd17"
},
"downloads": -1,
"filename": "aws_cdk_aws_cognito_identitypool_alpha-2.170.0a0.tar.gz",
"has_sig": false,
"md5_digest": "39257fc1cadfc58420f20a8e269fff20",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 99210,
"upload_time": "2024-11-22T04:42:17",
"upload_time_iso_8601": "2024-11-22T04:42:17.696462Z",
"url": "https://files.pythonhosted.org/packages/61/22/f919b75e76e2544774cae47d46719aa0e7e4eb76e9bafd2cf2e1db1613d3/aws_cdk_aws_cognito_identitypool_alpha-2.170.0a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 04:42:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-cognito-identitypool-alpha"
}
JSON
