AdminLinkProviderForUser
Links an existing user account in a user pool (DestinationUser
) to an
identity from an external IdP (SourceUser
) based on a specified attribute
name and value from the external IdP. 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. You can then use the federated user identity 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. When the user signs in with a federated user identity, they sign in as the existing user account.
Note
The maximum number of federated identities linked to a user is five.
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 IdPs and provider attributes that have been trusted by the application owner.
See also AdminDisableProviderForUser.
Note
Amazon Cognito evaluates Amazon 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.
Request Syntax
{
"DestinationUser": {
"ProviderAttributeName": "string
",
"ProviderAttributeValue": "string
",
"ProviderName": "string
"
},
"SourceUser": {
"ProviderAttributeName": "string
",
"ProviderAttributeValue": "string
",
"ProviderName": "string
"
},
"UserPoolId": "string
"
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- DestinationUser
-
The existing user in the user pool that you want to assign to the external IdP user account. This user can be a local (Username + Password) Amazon Cognito user pools user or a federated user (for example, a SAML or Facebook user). If the user doesn't exist, Amazon Cognito generates an exception. Amazon Cognito returns this user when the new user (with the linked IdP attribute) signs in.
For a native username + password user, the
ProviderAttributeValue
for theDestinationUser
should be the username in the user pool. For a federated user, it should be the provider-specificuser_id
.The
ProviderAttributeName
of theDestinationUser
is ignored.The
ProviderName
should be set toCognito
for users in Cognito user pools.Important
All attributes in the DestinationUser profile must be mutable. If you have assigned the user any immutable custom attributes, the operation won't succeed.
Type: ProviderUserIdentifierType object
Required: Yes
- SourceUser
-
An external IdP account for a user who doesn't 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 using a federated social IdP, such as Facebook, Google, or Login with Amazon, you must set theProviderAttributeName
toCognito_Subject
. For social IdPs, theProviderName
will beFacebook
,Google
, orLoginWithAmazon
, and Amazon Cognito will automatically parse the Facebook, Google, and Login with Amazon tokens forid
,sub
, anduser_id
, respectively. TheProviderAttributeValue
for the user must be the same value as theid
,sub
, oruser_id
value found in the social IdP token.For OIDC, the
ProviderAttributeName
can be any value that matches a claim in the ID token, or that your app retrieves from theuserInfo
endpoint. You must map the claim to a user pool attribute in your IdP configuration, and set the user pool attribute name as the value ofProviderAttributeName
in yourAdminLinkProviderForUser
request.For SAML, the
ProviderAttributeName
can be any value that matches a claim in the SAML assertion. To link SAML users based on the subject of the SAML assertion, map the subject to a claim through the SAML IdP and set that claim name as the value ofProviderAttributeName
in yourAdminLinkProviderForUser
request.For both OIDC and SAML users, when you set
ProviderAttributeName
toCognito_Subject
, Amazon Cognito will automatically parse the default unique identifier found in the subject from the IdP token.Type: ProviderUserIdentifierType object
Required: Yes
- UserPoolId
-
The user pool ID for the user pool.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 131072.
Required: Yes
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 address or phone number that has already been supplied as an alias for a different user profile. This exception indicates that an account with this email address or phone already exists in a user pool that you've configured to use email address or phone number as a sign-in alias.
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
- LimitExceededException
-
This exception is thrown when a user exceeds the limit for a requested Amazon resource.
HTTP Status Code: 400
- NotAuthorizedException
-
This exception is thrown when a user isn't authorized.
HTTP Status Code: 400
- ResourceNotFoundException
-
This exception is thrown when the Amazon Cognito service can't 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 isn't found.
HTTP Status Code: 400
Examples
Example
An AdminLinkProviderForUser request that links a Sign In With Apple unique
identifier to a test user with the username akua_mansa
.
Sample Request
POST HTTP/1.1
Host: cognito-idp.us-east-1.amazonaws.com
X-Amz-Date: 20230613T200059Z
Accept-Encoding: gzip, deflate, br
X-Amz-Target: AWSCognitoIdentityProviderService.AdminLinkProviderForUser
User-Agent: <UserAgentString>
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
Content-Length: <PayloadSizeBytes>
{
"DestinationUser": {
"ProviderAttributeValue": "akua_mansa",
"ProviderName": "Cognito"
},
"SourceUser": {
"ProviderAttributeName": "Cognito_Subject",
"ProviderAttributeValue": "000001.abc123d1234567ef12gh12i1jk1lm123.0001",
"ProviderName": "SignInWithApple"
},
"UserPoolId": "us-east-1_EXAMPLE"
}
Sample Response
HTTP/1.1 200 OK
Date: Tue, 13 Jun 2023 20:00:59 GMT
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>
x-amzn-requestid: a1b2c3d4-e5f6-a1b2-c3d4-EXAMPLE11111
Connection: keep-alive
{}
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: