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 AWS 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

• Signing AWS API Requests

• Using the Amazon Cognito user pools API and user pool endpoints

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 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.

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 the ProviderAttributeName to Cognito_Subject. For social IdPs, the ProviderName will be Facebook, Google, or LoginWithAmazon, and Amazon 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 IdP token.

For OIDC, the ProviderAttributeName can be any mapped value from a claim in the ID token, or that your app retrieves from the userInfo endpoint. For SAML, the ProviderAttributeName can be any mapped value from a claim in the SAML assertion.

The following additional considerations apply to SourceUser for OIDC and SAML providers.

• You must map the claim to a user pool attribute in your IdP configuration, and set the user pool attribute name as the value of ProviderAttributeName in your AdminLinkProviderForUser request. For example, email.

• When you set ProviderAttributeName to Cognito_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 ID of the user pool where you want to link a federated identity.

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 AWS 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

The following example links a Facebook user to the user pool user "adminlink-testuser." The user's unique identifier with Facebook is represented in the value of ProviderAttributeValue.

Sample Request

POST HTTP/1.1
Host: cognito-idp.us-west-2.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": "adminlink-testuser",
    "ProviderName": "Cognito"
  },
  "SourceUser": { 
    "ProviderAttributeName": "Cognito_Subject",
    "ProviderAttributeValue": "123456789012345",
    "ProviderName": "Facebook"
  },
  "UserPoolId": "us-west-2_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
{}

Example

The following example links a Google user to the user pool user "adminlink-testuser." The user's unique identifier with Google is represented in the value of ProviderAttributeValue.

Sample Request

POST HTTP/1.1
Host: cognito-idp.us-west-2.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": "adminlink-testuser",
    "ProviderName": "Cognito"
  },
  "SourceUser": { 
    "ProviderAttributeName": "Cognito_Subject",
    "ProviderAttributeValue": "5432109876543210",
    "ProviderName": "Google"
  },
  "UserPoolId": "us-west-2_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
{}

Example

The following example links a Login With Amazon user to the user pool user "adminlink-testuser." The user's unique identifier with Amazon is represented in the value of ProviderAttributeValue.

Sample Request

POST HTTP/1.1
Host: cognito-idp.us-west-2.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": "adminlink-testuser",
    "ProviderName": "Cognito"
  },
  "SourceUser": { 
    "ProviderAttributeName": "Cognito_Subject",
    "ProviderAttributeValue": "amzn1.account.AFALI...",
    "ProviderName": "LoginWithAmazon"
  },
  "UserPoolId": "us-west-2_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
{}

Example

The following example links a Sign In With Apple user to the user pool user "adminlink-testuser." The user's unique identifier with Apple is represented in the value of ProviderAttributeValue.

Sample Request

POST HTTP/1.1
Host: cognito-idp.us-west-2.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": "adminlink-testuser",
		"ProviderName": "Cognito"
	},
	"SourceUser": {
		"ProviderAttributeName": "Cognito_Subject",
		"ProviderAttributeValue": "000111.11111111111111111111111111111111111111.1111",
		"ProviderName": "SignInWithApple"
	},
	"UserPoolId": "us-west-2_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
{}

Example

The following example links a user from OIDC provider "MyOIDCProvider" to the user pool user "adminlink-testuser." This request links the local user to an IdP user that has a preferred_username attribute of [e-mail]. For this user to sync, your application must request scopes that return the preferred_username attribute from the IdP.

Sample Request

POST HTTP/1.1
Host: cognito-idp.us-west-2.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": "adminlink-testuser",
		"ProviderName": "Cognito"
	},
	"SourceUser": {
		"ProviderAttributeName": "preferred_username",
		"ProviderAttributeValue": "[e-mail]",
		"ProviderName": "MyOIDCProvider"
	},
	"UserPoolId": "us-west-2_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
{}

Example

The following example links a user from SAML 2.0 provider "MySAMLProvider" to the user pool user "adminlink-testuser." This request links the local user to an IdP user that has a email attribute of [e-mail]. For this user to sync, your application must receive an email claim in the SAML assertion.

Sample Request

POST HTTP/1.1
Host: cognito-idp.us-west-2.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": "adminlink-testuser",
		"ProviderName": "Cognito"
	},
	"SourceUser": {
		"ProviderAttributeName": "email",
		"ProviderAttributeValue": "[e-mail]",
		"ProviderName": "MySAMLProvider"
	},
	"UserPoolId": "us-west-2_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 AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go v2

• AWS SDK for Java V2

• AWS SDK for JavaScript V3

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3