For more information, please visit open platform

I. Intro

Authentication provides web apps with the capability to obtain the identity of users currently using Lark and build a login process for apps using the Lark login.

II. Steps

Step 1: If a web app discovers that a user hasn't logged in, it needs to request authentication.

Step 2: Once the user has logged in, the Open Platform generates a login pre-authorization code and uses 302 to redirect the browser to an app callback URL.

Step 3: The web app backend calls the Obtain a logged-in user identity API to verify the authenticity of the pre-authorization code and obtain the user's identity.

Step 4: If you need the user's information too, the web app backend can call the Obtain user information API.

Browser web page login

There is no need for users to scan a code or use their account details to log in within the Lark app.

III. Example

1.Create an app

Go to Lark Developer, click Create Custom App and get the app_id and app_secret.

2.Configure the app redirection URL

In Security Settings, add the redirection URL under Redirect URL, for example: https://open.larksuite.com/document. The redirection URL is the API address used when the web app calls the API to obtain the user identity based on the pre-authorization code of the logged-in user. If the URL is not configured or is configured incorrectly, the Open Platform will warn that the request is illegal.

3.Request identity authentication

Assemble the request URL based on the Request authentication API description. The user is redirected to this URL to start the authentication process.

Note: The redirect_uri parameters must be processed using URLEncode, as below:

https://open.larksuite.com/open-apis/authen/v1/index?app_id=cli_9e9c461563f0d107&redirect_uri=https%3a%2f%2fopen.larksuite.com%2fdocument%2fuQjL04CN%2fucDOz4yN4MjL3gzM

When an organization hasn't installed an app, this prompt will appear:

4.Get the login pre-authorization code

After the user logged in (either by scanning a code or using their account password) in the previous step, the Open Platform will add code and state to the redirect_uri and redirects the browser to the callback request URL, as shown below:

5.Get the user's identity

In this step, use a Postman request to call the login authentication API (see details) and use code to obtain the user's information, access_token, and refresh_token. Please note that code expires after 5 minutes and can only be used once.

6.Get the user's information

In the previous step, the access_token and refresh_token are both returned along with fields containing the corresponding expiry time of the tokens. Use the access_token obtained in step 5 to obtain user information. Sensitive information will only be returned once the organization authorization is obtained.

7.Refresh the access_token

Both the access_token and refresh_token have an expiration time. The access_token expiration time is shorter, and the refresh_token expiration time is longer. After access_token has expired, you can use the refresh_token to call the Refresh access_token API and obtain a new access_token and refresh_token. The new access_token and refresh_token have the same expiration times as the first time they are generated. If the refresh fails, you can try again within two hours.