身份授权

开发帮助更新于 2026-08-28 阅读 11

认证授权流程

OAuth是一个开放授权协议 (参见：https://oauth.net/2/)，该协议允许资源所有者授权应用使用该资源所有者的某一些HTTP服务中的资源，例如使用微博的账户登录美团，就是微博账户所有者授权美团使用该人在微博里的用户信息（包括用户名，头像，名称等）。

蓝信开放平台提供标准OAuth2.0协议实现，蓝信用户可授权接入蓝信开放平台的应用使用该用户在蓝信中的信息。蓝信开放平台提供了以下OAuth流程的实现：

基于web的标准OAuth流程。
OAuth优化流程。对于在蓝信客户端内使用的H5应用，我们推荐使用OAuth优化流程。
针对PC端使用外部浏览器打开应用场景的前置授权。PC端外部浏览器打开应用时的免登解决方案。

认证授权接入地址(注：不同蓝信部署环境对应地址不同)

蓝信认证授权服务器地址(OAuth授权页)： https://passport-example.domain, 蓝信用户登录认证授权服务器，提供蓝信用户登录web页面，负责端蓝信用户的登录接入和登录状态维护。

开放平台网关地址：https://apigw-example.domain, 用于访问蓝信开放平台的服务端接口。

基于web的标准OAuth流程

下面基于Web重定向的标准OAuth授权流程, 在浏览器内打开的纯web应用需要对接该流程：

标准OAuth授权流程

step1：用户在蓝信客户端工作台打开H5应用，应用前端访问应用服务端接口。step2： 应用服务端根据前端携带的cookie信息判断该用户是否已经被用户授权并已获取用户在蓝信中身份信息。

如果是，则继续应用逻辑
如果否，则通过302页面的跳转方式，发起到开放平台授权页的重定向（获取人员免登授权码），携带redirect_uri，发起OAuth流程。

step3：开放平台授权页服务获取该用户在蓝信中的身份信息，生成标识用户的临时授权码Code，该Code只能使用1次且5分钟有效。授权页服务生成Code时会校验redirect_uri是否和配置到蓝信应用中的可信域名相匹配。注：如果是在蓝信端内（蓝信客户端内置浏览器）打开应用，授权页服务会直接获取蓝信客户端当前用户身份，不会弹出蓝信登录页，从而实现端内免登。如果是在浏览器内打开纯web应用（蓝信端外打开应用），第一次打开应用跳转授权页后会弹出蓝信登录页，用户需要通过登录页登录蓝信，然后授权页才能获取当前用户的身份信息，生成code后再跳转应用。step4：应用需要实现一个服务端接口，也就是redirect_uri对应的接口用于处理获取用户临时授权码Code，开放平台授权页服务通过302重定向的方式将标识用户身份的Code送到应用的该redirect_uri接口。step5-9：应用服务端redirect_uri接口接收到Code后，需要携带AppToken, Code等信息换取UserToken（获取 UserToken）。step10-12： 应用拿到用户身份信息 UserToken 就可以通过接口获取人员基本信息。拿到用户身份信息后，应用服务端需要缓存相关数据，并通过302重定向的方式跳转至应用原始访问的页面，继续后面的业务逻辑。

OAuth优化流程

在标准的OAuth流程中会涉及3次的重定向跳转，会有一定的时间性能损耗，针对在蓝信客户端内打开的应用，可以通过JSSDK调用Native客户端获取Code，从而可以缩短OAuth的耗时，具体流程如下：

OAuth优化流程

如果是，则继续应用逻辑
如果否，则应用服务端通过定义特定错误码返回前端，告知前端用户未登录应用

step3-4： 应用前端拿到用户未登录的错误信息后，调用JSSDK的接口获取人员免登授权码，并送交应用服务端。特别说明：该JS接口调用时，无须进行JS签名验证。

step5-9：应用服务端接收到Code后，需要携带AppToken, Code等信息通过蓝信开放平台服务端接口换取UserToken（获取 UserToken）。step10-12： 应用拿到用户身份信息 UserToken 就可以通过接口获取人员基本信息。拿到用户身份信息后，应用服务端需要缓存相关数据，并通过302重定向的方式跳转至应用原始访问的页面，继续后面的业务逻辑。

蓝信前置授权

对于蓝信PC端应用，目前支持应用在端内（蓝信内置浏览器）打开应用，也支持外置系统浏览器打开应用。在蓝信工作台打开应用时如果使用外置浏览器打开，应用不能使用以上优化的OAuth流程（因为在系统外置浏览器里面打开应用不能使用蓝信客户端的JSSDK），但如果使用标准的基于web跳转的标准OAuth流程又会引起应用二次登录的问题，第一次打开应用时会弹出蓝信登录页。

蓝信目前支持蓝信webIm工作台，可以理解是蓝信的web客户端。用户登录蓝信的webIm客户端后在蓝信webIm工作台上打开应用时，应用可以使用基于web重定向的标准OAuth流程接入蓝信。因为登录蓝信webIm时用户已经保存了在蓝信用户中心的登录状态，所以从蓝信webIm工作台打开应用时，如果基于web重定向的标准OAuth流程接入蓝信，一般情况下也是免登的（不会弹出蓝信登录页）。但如果蓝信用户在蓝信用户中心和蓝信webIm的session有效期出现差异的情况下，比如蓝信用户中心的session已过期，但webIm的登录session还有效，这时如果在webIm上打开应用并使用基于重定向方式获取用户身份的OAuth流程，也会弹出登录页，出现二次登录的情况。

为了解决以上从蓝信客户端通过外置web浏览器打开应用的二次登录问题(端内触发，端外打开)，蓝信在以上两种特定场景下提供前置授权的登录方式。

OAuth前置授权流程

step1-3：用户在蓝信客户端工作台打开H5应用，蓝信客户端判断如果是PC外置浏览器或蓝信webIm中打开应用，蓝信客户端根据配置的应用入口信息获取用户code。通过外置浏览器打开应用时将code作为http请求参数交给应用前端。step4：应用前端判断如果请求中携带code则将code送到应用服务端的认证授权接口。step5-8：应用服务端认证授权接口接收到Code后，需要携带AppToken, Code等信息换取UserToken（获取 UserToken）。step9-11： 应用拿到用户身份信息 UserToken 就可以通过接口获取人员基本信息。拿到用户身份信息后，应用服务端需要缓存相关数据，并通过302重定向的方式跳转至应用原始访问的页面，继续后面的业务逻辑。

可信域名

对于OAuth流程，蓝信开放平台需要将人员临时免登授权码(code)，通过以上两种方式交付到应用，这个过程都有前端参与，为防止恶意软件通过拦截伪造前端请求的方式非法获取人员免登授权码，蓝信开放平台要求对获取人员免登授权码的地址(redirect_uri)进行可信域名白名单登记和校验。

可信域名登记：在蓝信开发者中心 "可信域名" 配置页将redirect_rui进行配置, 例如：https://test.com/api/v1/code 可信域名登记

可信域名校验：开放平台在处理应用获取人员免登授权码请求时会校验当前获取code的redirect_uri和登记的可信域名是否一致。所以如果遇到获取人员免登授权码失败的情况，首先请检查可信域名是否正确登记。

免登授权码获取用户身份信息流程

Oauth

JSSDK 签名认证流程

JSSDK 签名认证流程如下：

JSSDK 签名认证流程

step1：应用前端调用应用服务端接口获取应用JS签名信息。step2-4： 应用服务端需要实现以下逻辑：

js_api_token: 使用AppToken，通过开放平台接口获取JSAPI访问Token获取，例如：31a4a1aa-cffc-4aca-9ef6-0497edf7fbed。
noncestr: 应用服务端生成一个随机字符串noncestr, 一般是个UUID，例如：e30fdeda-f13c-4cca-a0a6-94b507d2b260。
timestamp: 应用服务端获取当前时间信息timestamp，要求精确到秒, 前端接JS Config接口中字该段类型为int，例如：1569275968。
url: 当前网页的URL，全路径含参数，不包含#及其后面部分，例如：http://www.test.com/index.html?open_type=webview/。
应用服务端将以上各参数按以下格式处理：js_api_token=31a4a1aa-cffc-4aca-9ef6-0497edf7fbed&noncestr=e30fdeda-f13c-4cca-a0a6-94b507d2b260&timestamp=1569275968&url=http://www.test.com/index.html?open_type=webview/。
使用sha-1函数对5中处理过的字符串计算签名： signature = 2e3efe2bf4482494b4f7af07817656c72c70d79a。
应用服务端将 signature, noncestr, timestamp, url 信息返回给应用前端。

step5-6： 应用前端拿到JS签名和其他必要参数后，调用前端 JS Config接口进行权限验证配置。

特别说明：; 1. js_api_token 2小时有效，系统只保存单一js_api_token，换取新token后老token会立即失效，所以应用服务端必须按接口返回的token有效时间对该js_api_token进行全局缓存（服务多实例情况下共用一个缓存数据），避免并发场景下JS验签失败。; 2. 签名的计算需要在应用的服务端进行，禁止由前端页面代码进行计算，原因是前端页面的代码运行空间不安全，会导致js-api-token等敏感信息泄漏。

Go 语言签名算法示例代码如下：

package testing

import (
        "crypto/sha1"
        "fmt"
        "github.com/satori/go.uuid"
        "testing"
        "time"
)

func TestGenJsSign(t *testing.T) {
        token := "31a4a1aa-cffc-4aca-9ef6-0497edf7fbed"
        url := "http://www.test.com/index.html?open_type=webview/"
        timestamp := time.Now().Unix()
        nonce := uuid.NewV4().String()
        stringToSign := fmt.Sprintf("js_api_token=%v&noncestr=%v&timestamp=%v&url=%v", token, nonce, timestamp, url)
        h := sha1.New()
        h.Write([]byte(stringToSign))
        signature := fmt.Sprintf("%x", h.Sum(nil))
        fmt.Println(stringToSign)
        fmt.Println(signature)
        return
}

JAVA 语言签名算法示例代码如下：

import java.security.NoSuchAlgorithmException;
import java.security.MessageDigest;
import java.util.UUID;

class Example {
    public static void main(String[] args) throws NoSuchAlgorithmException {
        String token = "31a4a1aa-cffc-4aca-9ef6-0497edf7fbed";
        String url = "http://www.test.com/index.html?open_type=webview/";
        Long timestamp = System.currentTimeMillis() / 1000;
        String nonce = UUID.randomUUID().toString();
        String stringToSign ="js_api_token="+token+"&noncestr="+nonce+"&timestamp="+timestamp + "&url=" + url;
        MessageDigest md = null;
        try {
            md = MessageDigest.getInstance("SHA-1");
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
            return;
        }
        md.update(stringToSign.getBytes());
        String signature = "";
        for (byte b : md.digest()){
            signature += String.format("%02x", b);
        }
        System.out.println(stringToSign);
        System.out.println(signature);
        return;
    }
}

第三方网站接入蓝信扫码登录

基本介绍

网站应用蓝信客户端扫描二维码并确认登录，是基于OAuth 2.0 协议标准构建的蓝信授权登录系统。登录的网站仅可以获取登录蓝信用户的身份信息。网站应用接入蓝信客户端扫码登录有两种方式：

标准OAuth流程：打开应用web页面后，如果没有该用户登录状态，应用通过重定向方式打开蓝信的登录页，使用蓝信客户端在蓝信登录页扫描登录二维码后，蓝信登录页会再次通过重定向方式携带用户身份信息（code）回到应用的页面，完成web应用的蓝信用户身份授权信息获取。此方式具体接流程式参考标准OAuth流程，在此不做详细描述。该方式的优点是接入方式简单通用，缺点是登录过程会有页面切换。
通过JSSDK创建iframe弹窗展示蓝信登录二维码，用户可以直接在应用的页面内完成扫码登录，无须跳转蓝信登录页，本文档主要针对这种接入方式进行说明。

准备工作

网站接入蓝信

在网站使用蓝信扫码登录前，网站需要通过蓝信开放平台接入蓝信，具体操作参考自建应用开发流程

重定向地址加入到应用可信域名

作为应用接入到蓝信之后，蓝信授权给第三方应用时需要进行严格的鉴权操作，redirect_uri 就是其中一个，此地址可以在应用的可信域名中配置。

授权登录流程说明

蓝信 OAuth 2.0 授权登录是让用户使用蓝信身份安全登录第三方应用或者网站，我们提供 lxLogin JSSDK 供已接入蓝信的第三方网站实现使用蓝信客户端扫码可直接确认授权登录，无需跳转蓝信域下登录后在返回第三方网站，提升用户的登录体验以及减少第三方网站的接入成本。

使用蓝信移动端扫码成功之后会跳转授权登录页面，点击确认登录时第三方网站会获取到蓝信临时授权码 code，然后第三方服务再根据 code 和 AppToken 等信息换取 UserToken，应用拿到用户身份信息 UserToken 后可通过开放平台获取人员基本信息获取用户信息。

实现方法

第三方网站需实现扫码登录入口

(1) 第三方网站需根据提供的 JSSDK 实现扫码登录入口，登录方法将会绑定在 window 对象（window.LxLogin)。

(2) 首先确认当前域名是否为已经配置应用的可信域名。

(3) 在调用 lxLogin JSSDK 会根据传入的 appId 和二维码授权页面 URL，UC 生成二维码通过 JSSDK 创建 iframe 弹窗展示二维码，授权成功后需手动销毁 iframe。

ps: appId格式如果为123567-7654321, 取-后面的部分7654321

(4) success 回调会返回 authCode 可用于登录。

LxLogin JSSDK 使用方法如下：

页面添加dom用于挂载iframe

<div id="qrauth-container"></div>

二维码尺寸设置

ps: 建议宽度不小于300px，尺寸过小可能导致扫不出信息

#qrauth-container iframe {}

<script src="https://user-xxx.xxx.cn/user/passport/qrauth/static/login-jssdk.js"></script>

LxLogin JSSDK 使用方法如下：

LxLogin({
    oauthUrl: 'https://xxx.xxx.cn/user/passport/qrauth', // qrauth扫码页面完整链接
    appId: 7654321, // 应用id
    orgId: 1, // 组织id
    containerId: 'qrauth-container' // iframe容器id
    success: function(res) {
      // code用于登录
      const { code, status } = res
    },
    fail: function(res) {
      const { code, error } = res
    }

});

F.A.Q

可能出现的错误类型

必填参数未设置
回调地址不在应用可信域名范围内
不在蓝信内扫描登录
蓝信获取应用信息异常，当前组织未能查找到该应用信息
蓝信授权服务异常导致授权失败
网络异常

人员身份识别码使用场景

蓝信客户端（移动端）提供蓝信人员身份识别码。当组织应用的业务形式是个读码闸机、门禁读码器或其他读码场景时，应用可以根据读码器读取到的蓝信人员身份识别码快速获取人员身份。

打开人员身份识别码

打开蓝信客户端（移动端），我的-->身份识别码，可以打开人员身份识别码。

蓝信开发者中心

根据人员身份识别码获取人员身份信息

应用使用的读码器读取人员身份识别码后，通过服务端接口可以获取人员身份信息。特别说明，读取的身份识别码信息，5分钟有效，且只能使用一次。根据身份识别码获取人员信息

💬 即时通讯

🤝 业务协同

📦 AI产品

📦 其他产品

openplatform

身份授权

认证授权流程

认证授权接入地址(注：不同蓝信部署环境对应地址不同)

基于web的标准OAuth流程

OAuth优化流程

蓝信前置授权

可信域名

免登授权码获取用户身份信息流程

JSSDK 签名认证流程

第三方网站接入蓝信扫码登录

基本介绍

准备工作

授权登录流程说明

实现方法

F.A.Q

人员身份识别码使用场景

打开人员身份识别码

根据人员身份识别码获取人员身份信息