AdminLinkProviderForUser

Links an existing user account in a user pool (DestinationUser) to an
identity from an external identity provider (SourceUser) based on a
specified attribute name and value from the external identity provider. This allows
you
to create a link from the existing user account to an external federated user identity
that has not yet been used to sign in, so that the federated user identity can be
used
to sign in as the existing user account.

For example, if there is an existing user with a username and password, this API
links that user to a federated user identity, so that when the federated user identity
is used, the user signs in as the existing user account.

Important

Because this API allows a user with an external federated identity to sign in
as an existing user in the user pool, it is critical that it only be used with
external identity providers and provider attributes that have been trusted by the
application owner.

Request Parameters

The existing user in the user pool to be linked to the external identity provider
user account. Can be a native (Username + Password) Cognito User Pools user or a
federated user (for example, a SAML or Facebook user). If the user doesn't exist,
an
exception is thrown. This is the user that is returned when the new user (with the
linked identity provider attribute) signs in.

For a native username + password user, the ProviderAttributeValue for
the DestinationUser should be the username in the user pool. For a
federated user, it should be the provider-specific user_id.

The ProviderAttributeName of the DestinationUser is
ignored.

The ProviderName should be set to Cognito for users in
Cognito user pools.

An external identity provider account for a user who does not currently exist yet
in the user pool. This user must be a federated user (for example, a SAML or Facebook
user), not another native user.

If the SourceUser is a federated social identity provider user
(Facebook, Google, or Login with Amazon), you must set the
ProviderAttributeName to Cognito_Subject. For social
identity providers, the ProviderName will be Facebook,
Google, or LoginWithAmazon, and Cognito will automatically
parse the Facebook, Google, and Login with Amazon tokens for id,
sub, and user_id, respectively. The
ProviderAttributeValue for the user must be the same value as the
id, sub, or user_id value found in the social
identity provider token.

For SAML, the ProviderAttributeName can be any value that matches a
claim in the SAML assertion. If you wish to link SAML users based on the subject of
the
SAML assertion, you should map the subject to a claim through the SAML identity provider
and submit that claim name as the ProviderAttributeName. If you set
ProviderAttributeName to Cognito_Subject, Cognito will
automatically parse the default unique identifier found in the subject from the SAML
token.

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty
HTTP body.

Errors

For information about the errors that are common to all actions, see Common Errors.

AliasExistsException

This exception is thrown when a user tries to confirm the account with an email or
phone number that has already been supplied as an alias from a different account.
This
exception tells user that an account with this email or phone already exists.

HTTP Status Code: 400

InternalErrorException

This exception is thrown when Amazon Cognito encounters an internal
error.

HTTP Status Code: 500

InvalidParameterException

This exception is thrown when the Amazon Cognito service encounters an invalid
parameter.

HTTP Status Code: 400

NotAuthorizedException

This exception is thrown when a user is not authorized.

HTTP Status Code: 400

ResourceNotFoundException

This exception is thrown when the Amazon Cognito service cannot find the requested
resource.

HTTP Status Code: 400

TooManyRequestsException

This exception is thrown when the user has made too many requests for a given
operation.

HTTP Status Code: 400

UserNotFoundException

This exception is thrown when a user is not found.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs,
see the following: