Linking user accounts

# Linking user accounts

By using the account link feature, providers (businesses and developers) can securely link the existing user accounts from their service with accounts belonging to LINE users that have friended providers' LINE Official Account. This will allow providers to utilize the user data they've acquired and use LINE Official Accounts to provide even better services.

For example, these services can be provided by linking user accounts on a shopping site with LINE user accounts:

  • Send messages from a LINE Official Account when the user purchases a product from the shopping site.
  • Accept and process orders when users send messages to a LINE Official Account.

Accounts can also be linked through LINE Login, but a LINE Login channel will also be required to do so. The account link feature can be implemented even when only the Messaging API is being used.

The account link sequence is as follows:

Account link sequence

  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 their credentials.
  8. The web server acquires the user ID from the provider's service and uses that to generate a nonce (number used once).
  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 can be implemented independently, it can lead to security issues. By sending a linking URL to a different user, an attacker can 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.

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

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, 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, they 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, don't 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 using data that is 128 bits (16 bytes) or greater.
  • Encode in Base64.

Associate the nonce with the acquired user ID and save it.

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

Comply with these 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 they link their account

For example, you can use the Messaging API to change the rich menu shown to individual users. You can 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.