create_user_pool_client
¶
create_user_pool_client(
user_pool_id: UserPoolIdType,
client_name: ClientNameType,
*,
config_overrides: Optional[CognitoIdentityProviderClientConfig] = None,
generate_secret: Optional[GenerateSecret] = None,
client_secret: Optional[ClientSecretType] = None,
refresh_token_validity: Optional[RefreshTokenValidityType] = None,
access_token_validity: Optional[AccessTokenValidityType] = None,
id_token_validity: Optional[IdTokenValidityType] = None,
token_validity_units: Optional[TokenValidityUnitsType] = None,
read_attributes: Optional[ClientPermissionListType] = None,
write_attributes: Optional[ClientPermissionListType] = None,
explicit_auth_flows: Optional[ExplicitAuthFlowsListType] = None,
supported_identity_providers: Optional[SupportedIdentityProvidersListType] = None,
callback_ur_ls: Optional[CallbackURLsListType] = None,
logout_ur_ls: Optional[LogoutURLsListType] = None,
default_redirect_uri: Optional[RedirectUrlType] = None,
allowed_o_auth_flows: Optional[OAuthFlowsType] = None,
allowed_o_auth_scopes: Optional[ScopeListType] = None,
allowed_o_auth_flows_user_pool_client: Optional[BooleanType] = None,
analytics_configuration: Optional[AnalyticsConfigurationType] = None,
prevent_user_existence_errors: Optional[PreventUserExistenceErrorTypes] = None,
enable_token_revocation: Optional[WrappedBooleanType] = None,
enable_propagate_additional_user_context_data: Optional[WrappedBooleanType] = None,
auth_session_validity: Optional[AuthSessionValidityType] = None,
refresh_token_rotation: Optional[RefreshTokenRotationType] = None,
) -> CreateUserPoolClientResponse
Creates an app client in a user pool. This operation sets basic and advanced configuration options.
Unlike app clients created in the console, Amazon Cognito doesn't automatically assign a branding style to app clients that you configure with this API operation. Managed login and classic hosted UI pages aren't available for your client until after you apply a branding style.
If you don't provide a value for an attribute, Amazon Cognito sets it to its default value.
Amazon Cognito evaluates Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy.
Learn more
Parameters:
-
user_pool_id(UserPoolIdType) –The ID of the user pool where you want to create an app client.
-
client_name(ClientNameType) –A friendly name for the app client that you want to create.
-
generate_secret(Optional[GenerateSecret], default:None) –When
true, generates a client secret for the app client. Client secrets are used with server-side and machine-to-machine applications. Client secrets are automatically generated; you can't specify a secret value. For more information, see App client types. -
client_secret(Optional[ClientSecretType], default:None) –A custom client secret that you want to use for the app client. You cannot specify both GenerateSecret as true and provide a ClientSecret value.
-
refresh_token_validity(Optional[RefreshTokenValidityType], default:None) –The refresh token time limit. After this limit expires, your user can't use their refresh token. To specify the time unit for
RefreshTokenValidityasseconds,minutes,hours, ordays, set aTokenValidityUnitsvalue in your API request.For example, when you set
RefreshTokenValidityas10andTokenValidityUnitsasdays, your user can refresh their session and retrieve new access and ID tokens for 10 days.The default time unit for
RefreshTokenValidityin an API request is days. You can't setRefreshTokenValidityto 0. If you do, Amazon Cognito overrides the value with the default value of 30 days. Valid range is displayed below in seconds.If you don't specify otherwise in the configuration of your app client, your refresh tokens are valid for 30 days.
-
access_token_validity(Optional[AccessTokenValidityType], default:None) –The access token time limit. After this limit expires, your user can't use their access token. To specify the time unit for
AccessTokenValidityasseconds,minutes,hours, ordays, set aTokenValidityUnitsvalue in your API request.For example, when you set
AccessTokenValidityto10andTokenValidityUnitstohours, your user can authorize access with their access token for 10 hours.The default time unit for
AccessTokenValidityin an API request is hours. Valid range is displayed below in seconds.If you don't specify otherwise in the configuration of your app client, your access tokens are valid for one hour.
-
id_token_validity(Optional[IdTokenValidityType], default:None) –The ID token time limit. After this limit expires, your user can't use their ID token. To specify the time unit for
IdTokenValidityasseconds,minutes,hours, ordays, set aTokenValidityUnitsvalue in your API request.For example, when you set
IdTokenValidityas10andTokenValidityUnitsashours, your user can authenticate their session with their ID token for 10 hours.The default time unit for
IdTokenValidityin an API request is hours. Valid range is displayed below in seconds.If you don't specify otherwise in the configuration of your app client, your ID tokens are valid for one hour.
-
token_validity_units(Optional[TokenValidityUnitsType], default:None) –The units that validity times are represented in. The default unit for refresh tokens is days, and the default for ID and access tokens are hours.
-
read_attributes(Optional[ClientPermissionListType], default:None) –The list of user attributes that you want your app client to have read access to. After your user authenticates in your app, their access token authorizes them to read their own attribute value for any attribute in this list.
When you don't specify the
ReadAttributesfor your app client, your app can read the values ofemail_verified,phone_number_verified, and the standard attributes of your user pool. When your user pool app client has read access to these default attributes,ReadAttributesdoesn't return any information. Amazon Cognito only populatesReadAttributesin the API response if you have specified your own custom set of read attributes. -
write_attributes(Optional[ClientPermissionListType], default:None) –The list of user attributes that you want your app client to have write access to. After your user authenticates in your app, their access token authorizes them to set or modify their own attribute value for any attribute in this list.
When you don't specify the
WriteAttributesfor your app client, your app can write the values of the Standard attributes of your user pool. When your user pool has write access to these default attributes,WriteAttributesdoesn't return any information. Amazon Cognito only populatesWriteAttributesin the API response if you have specified your own custom set of write attributes.If your app client allows users to sign in through an IdP, this array must include all attributes that you have mapped to IdP attributes. Amazon Cognito updates mapped attributes when users sign in to your application through an IdP. If your app client does not have write access to a mapped attribute, Amazon Cognito throws an error when it tries to update the attribute. For more information, see Specifying IdP Attribute Mappings for Your user pool.
-
explicit_auth_flows(Optional[ExplicitAuthFlowsListType], default:None) –The authentication flows that you want your user pool client to support. For each app client in your user pool, you can sign in your users with any combination of one or more flows, including with a user name and Secure Remote Password (SRP), a user name and password, or a custom authentication process that you define with Lambda functions.
If you don't specify a value for
ExplicitAuthFlows, your app client supportsALLOW_REFRESH_TOKEN_AUTH,ALLOW_USER_SRP_AUTH, andALLOW_CUSTOM_AUTH.The values for authentication flow options include the following.
-
ALLOW_USER_AUTH: Enable selection-based sign-in withUSER_AUTH. This setting covers username-password, secure remote password (SRP), passwordless, and passkey authentication. This authentiation flow can do username-password and SRP authentication without otherExplicitAuthFlowspermitting them. For example users can complete an SRP challenge throughUSER_AUTHwithout the flowUSER_SRP_AUTHbeing active for the app client. This flow doesn't includeCUSTOM_AUTH.To activate this setting, your user pool must be in the Essentials tier or higher.
-
ALLOW_ADMIN_USER_PASSWORD_AUTH: Enable admin based user password authentication flowADMIN_USER_PASSWORD_AUTH. This setting replaces theADMIN_NO_SRP_AUTHsetting. With this authentication flow, your app passes a user name and password to Amazon Cognito in the request, instead of using the Secure Remote Password (SRP) protocol to securely transmit the password. -
ALLOW_CUSTOM_AUTH: Enable Lambda trigger based authentication. -
ALLOW_USER_PASSWORD_AUTH: Enable user password-based authentication. In this flow, Amazon Cognito receives the password in the request instead of using the SRP protocol to verify passwords. -
ALLOW_USER_SRP_AUTH: Enable SRP-based authentication. -
ALLOW_REFRESH_TOKEN_AUTH: Enable authflow to refresh tokens.
In some environments, you will see the values
ADMIN_NO_SRP_AUTH,CUSTOM_AUTH_FLOW_ONLY, orUSER_PASSWORD_AUTH. You can't assign these legacyExplicitAuthFlowsvalues to user pool clients at the same time as values that begin withALLOW_, likeALLOW_USER_SRP_AUTH. -
-
supported_identity_providers(Optional[SupportedIdentityProvidersListType], default:None) –A list of provider names for the identity providers (IdPs) that are supported on this client. The following are supported:
COGNITO,Facebook,Google,SignInWithApple, andLoginWithAmazon. You can also specify the names that you configured for the SAML and OIDC IdPs in your user pool, for exampleMySAMLIdPorMyOIDCIdP.This parameter sets the IdPs that managed login will display on the login page for your app client. The removal of
COGNITOfrom this list doesn't prevent authentication operations for local users with the user pools API in an Amazon Web Services SDK. The only way to prevent SDK-based authentication is to block access with a WAF rule. -
callback_ur_ls(Optional[CallbackURLsListType], default:None) –A list of allowed redirect, or callback, URLs for managed login authentication. These URLs are the paths where you want to send your users' browsers after they complete authentication with managed login or a third-party IdP. Typically, callback URLs are the home of an application that uses OAuth or OIDC libraries to process authentication outcomes.
A redirect URI must meet the following requirements:
-
Be an absolute URI.
-
Be registered with the authorization server. Amazon Cognito doesn't accept authorization requests with
redirect_urivalues that aren't in the list ofCallbackURLsthat you provide in this parameter. -
Not include a fragment component.
See OAuth 2.0 - Redirection Endpoint.
Amazon Cognito requires HTTPS over HTTP except for callback URLs to
http://localhost,http://127.0.0.1andhttp://[::1]. These callback URLs are for testing purposes only. You can specify custom TCP ports for your callback URLs.App callback URLs such as
myapp://exampleare also supported. -
-
logout_ur_ls(Optional[LogoutURLsListType], default:None) –A list of allowed logout URLs for managed login authentication. When you pass
logout_uriandclient_idparameters to/logout, Amazon Cognito signs out your user and redirects them to the logout URL. This parameter describes the URLs that you want to be the permitted targets oflogout_uri. A typical use of these URLs is when a user selects "Sign out" and you redirect them to your public homepage. For more information, see Logout endpoint. -
default_redirect_uri(Optional[RedirectUrlType], default:None) –The default redirect URI. In app clients with one assigned IdP, replaces
redirect_uriin authentication requests. Must be in theCallbackURLslist. -
allowed_o_auth_flows(Optional[OAuthFlowsType], default:None) –The OAuth grant types that you want your app client to generate for clients in managed login authentication. To create an app client that generates client credentials grants, you must add
client_credentialsas the only allowed OAuth flow.- code
-
Use a code grant flow, which provides an authorization code as the response. This code can be exchanged for access tokens with the
/oauth2/tokenendpoint. - implicit
-
Issue the access token, and the ID token when scopes like
openidandprofileare requested, directly to your user. - client_credentials
-
Issue the access token from the
/oauth2/tokenendpoint directly to a non-person user, authorized by a combination of the client ID and client secret.
-
allowed_o_auth_scopes(Optional[ScopeListType], default:None) –The OAuth, OpenID Connect (OIDC), and custom scopes that you want to permit your app client to authorize access with. Scopes govern access control to user pool self-service API operations, user data from the
userInfoendpoint, and third-party APIs. Scope values includephone,email,openid, andprofile. Theaws.cognito.signin.user.adminscope authorizes user self-service operations. Custom scopes with resource servers authorize access to external APIs. -
allowed_o_auth_flows_user_pool_client(Optional[BooleanType], default:None) –Set to
trueto use OAuth 2.0 authorization server features in your app client.This parameter must have a value of
truebefore you can configure the following features in your app client.-
CallBackURLs: Callback URLs. -
LogoutURLs: Sign-out redirect URLs. -
AllowedOAuthScopes: OAuth 2.0 scopes. -
AllowedOAuthFlows: Support for authorization code, implicit, and client credentials OAuth 2.0 grants.
To use authorization server features, configure one of these features in the Amazon Cognito console or set
AllowedOAuthFlowsUserPoolClienttotruein aCreateUserPoolClientorUpdateUserPoolClientAPI request. If you don't set a value forAllowedOAuthFlowsUserPoolClientin a request with the CLI or SDKs, it defaults tofalse. Whenfalse, only SDK-based API sign-in is permitted. -
-
analytics_configuration(Optional[AnalyticsConfigurationType], default:None) –The user pool analytics configuration for collecting metrics and sending them to your Amazon Pinpoint campaign.
In Amazon Web Services Regions where Amazon Pinpoint isn't available, user pools might not have access to analytics or might be configurable with campaigns in the US East (N. Virginia) Region. For more information, see Using Amazon Pinpoint analytics.
-
prevent_user_existence_errors(Optional[PreventUserExistenceErrorTypes], default:None) –When
ENABLED, suppresses messages that might indicate a valid user exists when someone attempts sign-in. This parameters sets your preference for the errors and responses that you want Amazon Cognito APIs to return during authentication, account confirmation, and password recovery when the user doesn't exist in the user pool. When set toENABLEDand the user doesn't exist, authentication returns an error indicating either the username or password was incorrect. Account confirmation and password recovery return a response indicating a code was sent to a simulated destination. When set toLEGACY, those APIs return aUserNotFoundExceptionexception if the user doesn't exist in the user pool.Defaults to
LEGACY. -
enable_token_revocation(Optional[WrappedBooleanType], default:None) –Activates or deactivates token revocation in the target app client.
If you don't include this parameter, token revocation is automatically activated for the new user pool client.
-
enable_propagate_additional_user_context_data(Optional[WrappedBooleanType], default:None) –When
true, your application can include additionalUserContextDatain authentication requests. This data includes the IP address, and contributes to analysis by threat protection features. For more information about propagation of user context data, see Adding session data to API requests. If you don’t include this parameter, you can't send the source IP address to Amazon Cognito threat protection features. You can only activateEnablePropagateAdditionalUserContextDatain an app client that has a client secret. -
auth_session_validity(Optional[AuthSessionValidityType], default:None) –Amazon Cognito creates a session token for each API request in an authentication flow.
AuthSessionValidityis the duration, in minutes, of that session token. Your user pool native user must respond to each authentication challenge before the session expires. -
refresh_token_rotation(Optional[RefreshTokenRotationType], default:None) –The configuration of your app client for refresh token rotation. When enabled, your app client issues new ID, access, and refresh tokens when users renew their sessions with refresh tokens. When disabled, token refresh issues only ID and access tokens.
Raises:
-
FeatureUnavailableInTierException–This exception is thrown when a feature that you attempted to use or configure isn't included in your user pool's current feature plan. This can occur when:
-
You configure a feature that your feature plan doesn't support.
-
You make a request that uses a feature that requires a higher feature plan.
To resolve this issue, upgrade your user pool to a feature plan that includes the feature.
-
-
InternalErrorException–This exception is thrown when Amazon Cognito encounters an internal error.
-
InvalidOAuthFlowException–This exception is thrown when the specified OAuth flow is not valid.
-
InvalidParameterException–This exception is thrown when the Amazon Cognito service encounters an invalid parameter.
-
LimitExceededException–This exception is thrown when a user exceeds the limit for a requested Amazon Web Services resource.
-
NotAuthorizedException–This exception is thrown when a user isn't authorized.
-
OperationNotEnabledException–This exception is thrown when an operation is not available in the current region or for the current user pool configuration. This can occur when attempting to perform operations that are not supported in secondary replica regions.
-
ResourceNotFoundException–This exception is thrown when the Amazon Cognito service can't find the requested resource.
-
ScopeDoesNotExistException–This exception is thrown when the specified scope doesn't exist.
-
TooManyRequestsException–This exception is thrown when the user has made too many requests for a given operation.
-
UnknownServiceError–The service returned an error code this client does not model.
Examples:
Example user pool app client with email and username sign-in The following example creates an app client with all configurable properties set to an example value. The resulting user pool client connects to an analytics client, allows sign-in with username and password, and has two external identity providers associated with it.
>>> client.create_user_pool_client(access_token_validity=6, allowed_o_auth_flows=['code'], allowed_o_auth_flows_user_pool_client=True, allowed_o_auth_scopes=['aws.cognito.signin.user.admin', 'openid'], analytics_configuration={'ApplicationId': 'd70b2ba36a8c4dc5a04a0451a31a1e12', 'ExternalId': 'my-external-id', 'RoleArn': 'arn:aws:iam::123456789012:role/test-cognitouserpool-role', 'UserDataShared': True}, callback_ur_ls=['https://example.com', 'http://localhost', 'myapp://example'], client_name='my-test-app-client', default_redirect_uri='https://example.com', explicit_auth_flows=['ALLOW_ADMIN_USER_PASSWORD_AUTH', 'ALLOW_USER_PASSWORD_AUTH', 'ALLOW_REFRESH_TOKEN_AUTH'], generate_secret=True, id_token_validity=6, logout_ur_ls=['https://example.com/logout'], prevent_user_existence_errors='ENABLED', read_attributes=['email', 'address', 'preferred_username'], refresh_token_validity=6, supported_identity_providers=['SignInWithApple', 'MySSO'], token_validity_units={'AccessToken': 'hours', 'IdToken': 'minutes', 'RefreshToken': 'days'}, user_pool_id='us-east-1_EXAMPLE', write_attributes=['family_name', 'email'])
Source code in docs_src/capo_cognito_identity_provider/_services/cognito_identity_provider.py
4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 | |