Integrating web login v1

This page explains how to integrate Web Login v1 for the website you are developing.

Deprecated version

This page describes Web Login v1 which is a deprecated version of Web Login. For information on the latest version of Web Login, see Web Login v2.

Note: Web Login v1 will only be supported until January 2018 and it is recommended that you use Web Login v2.

 

Integration steps

An access token is required to call APIs. To securely perform verification, users are transferred to the LINE domain to log in and agree to permissions. After verification, users are redirected to your website and an access token is retrieved. The following describes the process of calling APIs.

  1. User transferred from website to the LINE domain.
  2. Login, PIN code verification, and permission screens displayed. User enters required information and agrees to conditions.
  3. User redirected to your website with an authorization code.
  4. Authorization code sent from your website's server to the LINE server to retrieve an access token.
  5. Access token is used to call APIs.

Prerequisites

To integrate your website with LINE, the following information must be retrieved or specified.

  • Channel ID
  • Channel secret
  • Callback URL

The Channel ID and Channel secret are identifiers which are issued when registering your Channel. After the user has logged in and agreed to the permissions on the LINE domain, control is returned to your website. For security reasons, register a callback URL on the Channel Console. Multiple callback URLS can be registered.

Retrieving authorization codes

Before integrating LINE with your website, it is necessary to retrieve an authorization code. Authorization codes are retrieved as follows.

Login Screen

When a user presses the LINE Login button on your website, the user is redirected to the login screen of the LINE Platform for authentication and authorization. The URL is as follows.

https://access.line.me/dialog/oauth/weblogin?response_type=code&client_id={Channel ID}&redirect_uri={Callback URL}&state={State}

For query parameters, the following must be specified.

Parameter name Parameter value Type Description
response_type Fixed "code". String Mandatory.
client_id Channel ID String Channel ID string issued by LINE.
redirect_uri Callback URL String URL which users are redirected to in order to return control to the website after authentication and authorization.
state Any alphanumeric string. String Optional. Used when redirecting to the callback URL. Cannot be a URL encoded string. See "Note" below.

The callback URL must match one of the URLs specified when registering your Channel. The comparison target is from the scheme to the path of the URL. The query parameter is not included as a comparison target. Specify a URL encoded string to specify the query parameter value.

For the state query parameter, the string given to the URL above will be returned unchanged to the callback URL. The state query parameter can be used to maintain the website session. The state query parameter can also be used to defend against CSRF attacks. The string which corresponds to the session in progress on the website will be specified as a state query parameter value. Regarding the state query parameter value which is returned to the callback URL, the string will be verified as to whether or not it is the correct string for the corresponding session on the website. By doing this, it is possible to identify the website user and the user who performed the authentication and authorization in order to integrate with LINE as the same individual.

Note: Do not use a URL encoded string for the state parameter because it is URL decoded when redirected from the LINE Platform. This is a known issue and we are working to fix it so that the state parameter is passed to the callback URL unchanged as specified by the OAuth 2.0 protocol.

Redirecting to your website

Once authentication and authorization is performed, the user is redirected to the specified URL from the LINE Platform. The results of the authentication and authorization process is granted by the query parameter. When authentication and authorization is successful, the following query parameter is granted.

Name Type Description
code String String required for displaying the results of the authentication and authorization and for issuing the access token. The authorization code is valid for 10 minutes.
state String State query parameter string specified at authentication and authorization.

For example, if authentication and authorization are performed as follows.

https://access.line.me/dialog/oauth/weblogin?response_type=code&client_id=12345&redirect_uri=https%3A%2F%2Fsample.com%2Fauth&state=123abc

If authentication and authorization is successful, the user is redirected from the LINE Platform as follows. Make sure necessary procedures are in place to defend against CSRF attacks.

http://sample.com/callback?code=b5fd32eacc791df&state=123abc

If authentication and authorization fails, the following query parameters are granted.

Parameter Type Description
error String Error code
state String State query parameter string specified at authentication and authorization
errorCode Integer Code value assigned to all error types
errorMessage String Message string displaying the reason for error

The following errorCode and errorMessage values are returned.

errorCode errorMessage Description
417 DISALLOWED User presses the cancel button on the permissions page.

In the above example, the user is redirected from the LINE Platform to the URL below.

http://sample.com/{Callback URL}?error=access_denied&state=[state]&errorCode=417&errorMessage=DISALLOWED

Retrieving access tokens

If the authentication and authorization process is successful, an authorization code is issued. To call an API, use the authorization code to issue an access token. The access token is issued at the following endpoint.

 

Request

HTTP Method POST
Endpoint URL https://api.line.me/v1/oauth/accessToken
Required request header Content-Type: application/x-www-form-urlencoded

The following information is specified in the request body in form-encoded format.

Name Type Description
grant_type String Fixed "authorization_code".
client_id String Channel ID.
client_secret String Channel Secret string issued when registering your Channel.
code String Acquired authorization code.
redirect_uri String Callback URL string passed at issuing the authorization code.

The following will occur.

grant_type=authorization_code&code=b5fd32eacc791df&client_id=12345&client_secret=d6524edacc8742aeedf98f&redirect_uri=https%3A%2F%2Fsample.com%2Fauth

Response

If the access token is processed successfully, the following information is returned in JSON format.

Property Type Description
mid String ID of authorized user
access_token String Access token string
token_type String Fixed "Bearer".
expires_in Integer Validity of access token. Elapsed time in seconds from when the access token is issued.
refresh_token String Token string necessary to reissue (refresh) a new access token
scope --- Fixed null value

The result is displayed as follows.

{
   "mid":"u668d5ad7e289428ef97d4ceb7841b0ad",
   "access_token":"bNl4YEFPI/hjFWhTqexp4MuEw5YPs7qhr6dJDXKwNPuLka...",
   "token_type":"Bearer",
   "expires_in":2591977,
   "refresh_token":"8iFFRdyxNVNLWYeteMMJ",
   "scope":null
 }

This information is kept on your server and APIs can be called as required. For more information on how to call APIs, see REST APIs.

Error responses

The following responses may be returned when an error occurs.

Reason HTTP status code Response body
A request token which was not issued has been specified
A request token which has already been exchanged for an access token was specified
404 {"error":"412","error_description":"TOKEN_NOT_FOUND:b5fd32eacc791df"}
An expired request token was specified 401 {"error":"412","error_description":"request token expired."}
No consumer credentials for the Channel exists for the specified Channel ID 401 {"error":"404","error_description":"CONSUMER_CREDENTIAL_NOT_FOUND"}
The use of the specified Channel ID of the Channel has been stopped 401 403 {"error":"405","error_description":"REVOKED or SUSPENDED"} {"error":"418","error_description":"CHANNEL_INACTIVE"}
The specified Channel secret does not match 401 {"error":"401","error_description":"channel secret is not matched. maybe abusing?"}
The specified Channel of the Channel ID does not exist 404 {"error":"404","error_description":"12345"}

Using APIs

After retrieving the access token, you can use REST APIs. For more information, see REST APIs.