Account link sequence

The account link sequence is as follows:

1. The bot server calls the API that issues a link token from the LINE user ID.
2. The LINE Platform returns the link token to the bot server.
3. The bot server calls the Messaging API to send a linking URL to the user.
4. The LINE Platform sends a linking URL to the user.
5. The user accesses the linking URL.
6. The web server displays the login screen.
7. The user enters his/her credentials.
8. The web server acquires the user ID from the provider\’s service and uses that to generate a nonce.
9. The web server redirects the user to the account-linking endpoint.
10. The user accesses the account-linking endpoint.
11. The LINE Platform sends an event (which includes the LINE user ID and nonce) via webhook to the bot server.
12. The bot server uses the nonce to acquire the user ID of the provider\’s service.

Though this sort of functionality could be implemented independently, it could lead to security issues. By sending a linking URL to a different user, an attacker could link its own LINE account to a service used by the victim. By using the account link feature provided by the Messaging API, you are able to securely link accounts since LINE will be performing the validation on its end of whether the user who issued the linking URL is actually the same as the user who was attempted to be linked.

Implementing the account link feature

To link your service\’s user accounts with LINE\’s user accounts, follow the steps below.

1. Issue the link token

Send an HTTP POST request to the /bot/user/{userId}/linkToken endpoint, and issue a link token for the user you are attempting to link.

curl -X POST https://api.line.me/v2/bot/user/{userId}/linkToken \\
-H \'Authorization: Bearer {channel access token}\'

If the request succeeds, the status code 200 and a link token will be returned. Link tokens are valid for 10 minutes and can only be used once.

{
  \"linkToken\": \"NMZTNuVrPTqlr2IF8Bnymkb7rXfYv5EY\"
}

2. Redirect users to the linking URL

The bot sends the user a message to open the linking URL. For example, the linking URL can be specified in a URI action of a template message. Specify the link token acquired in step 1 as a URL query parameter.
Example request

curl -v -X POST https://api.line.me/v2/bot/message/push \\
-H \'Content-Type:application/json\' \\
-H \'Authorization: Bearer {channel access token}\' \\
-d \'{
    \"to\": \"{user id}\",
    \"messages\": [{
        \"type\": \"template\",
        \"altText\": \"Account Link\",
        \"template\": {
            \"type\": \"buttons\",
            \"text\": \"Account Link\",
            \"actions\": [{
                \"type\": \"uri\",
                \"label\": \"Account Link\",
                \"uri\": \"http://example.com/link?linkToken=xxx\"
            }]
        }
    }]
}\'

3. Acquire the user ID for your service

When the user accesses the linking URL, he/she will be shown a login screen for your service. Upon logging in, you can acquire the user\’s ID from within your service.

4. Generate a nonce and redirect the user to the LINE Platform

Generate a nonce with the user ID acquired in step 3. The nonce requirements are as follows:

• It must be a string that is difficult to predict and can only be used once. Due to security considerations, please do not use predictable values, such as your service user IDs.
• The string must be between 10 and 255 characters.

The following conditions are recommended when generating a random value for the nonce.

• Use a secure random number generator function (e.g., SecureRandom) using data that is 128 bits (16 bytes) or greater.
• Encode in Base64.

Associate the nonce with the acquired user ID and save it. For example, when using a key-value store such as Redis, it would probably be best to save the nonce as the key paired with the user ID as the value.
When the nonce and user ID have been saved, redirect the user to the following endpoint.

https://access.line.me/dialog/bot/accountLink?linkToken={link token}&nonce={nonce}

When the user accesses this endpoint, the LINE Platform will verify if the user is the user the link token was issued for.

• If the account can be successfully linked: an account link event with the result property value of ok will be sent via webhook to the bot server.
• If the account cannot be linked for any reason, such as due to user impersonation: an account link event with the result property value of failed will be sent via webhook to the bot server.
• If the link token has expired or has already been used: no webhook event will be sent and the user will be shown an error.

5. Linking accounts

Execute the link processing once the bot server receives the account link event.
The LINE user ID to be linked and the nonce generated in step 4 are included in the webhook event. Use this nonce to identify the user ID from your service that was previously associated with the nonce and saved. Upon linking this ID to the LINE user ID, the account linking will be complete.

Unlinking

Please comply with the following two terms when using the account link feature:

• you must provide the user with an unlinking feature
• notify the user that there is an unlinking feature when he/she links his/her account

For example, you can use the Messaging API to change the rich menu shown to individual users. You could make it easy for users and provide the account link feature by showing an account link menu item to users that have not yet linked their accounts, and showing an unlinking menu item to those that have already linked their accounts.

Related pages

• Messaging API reference