概念

用户使用帐号登录软件，通过订阅的方式访问受保护的功能。

传统的授权方式是设备授权，针对的是设备；帐号授权针对的是人（谁拥有这个帐号，谁就可以访问）。

价值

个性化：开发商可以围绕帐号做一些个性化的服务，用来增加用户粘性，比如个人云盘。
更易用：帐号授权摆脱了设备限制，可以随时随地进行安全的授权，并且支持的范围更广，支持客户端软件和Web应用的授权；在登录模式方面也多种多样，可以很容易的支持微信扫码登录，无密码登录...
订阅式：每一个帐号通过订阅的方式来使用软件，开发商可以针对帐号统计其日活，月活，喜好等，可以支持更多的销售模式。

使用指南

创建帐号授权业务

本文介绍如何创建帐号授权的业务。

创建业务

使用管理员帐号登录比特授权云平台，点击左侧列表的业务，并点击添加业务。

创建业务

输入一个业务名称，然后点击 “选择业务类型”

选择业务类型

选择帐号授权的业务，接着点击“提交”。至此“帐号授权”的业务就创建完成了。

怎么创建用户

本文主要介绍管理单个用户的操作，如创建用户、关联账户以及绑定邮箱等，如需了解如何查看所有用户的信息，请见用户管理中心的相关概念。

创建用户

登录比特云平台后，点击左侧导航栏的用户，点击用户按钮创建：

创建用户对话框

可以创建邮箱类型的帐号，也可以创建普通帐号，用户在使用帐号授权时，会用该帐号进行认证。

用户信息

创建完成后，会自动跳转至刚创建的用户信息界面，开发商可以对该信息进行修改

创建用户填写详细信息，邮件为空值

给用户授权业务

开发商的一个App对应了bit云平台的一个“业务”，开发商给用户授权的过程，就是给用户勾选“业务”的流程。

在用户信息界面，选择“业务”列表

给用户授权业务

快速开发集成

方案介绍

帐号授权的集成比特云提供了两种方案，一种是客户端直接认证，另外一种是OIDC认证。

客户端直接认证：开发商可以使用比特云提供的库，直接传入帐号，密码进行认证和授权
OIDC认证：开发商通过OIDC流程完成认证，使用认证后得到的token调用库的接口，完成授权

两种授权方案，应对不同的使用场景。相比较，我们更推荐使用OIDC认证方案，它支持社会化登录（微信扫码等），不同应用之间支持单点登录。

授权库直接认证

    BIT_HANDLE handle = NULL;
    BIT_CHAR *pBusinessGuid = "xxx";        // 业务编号，在业务属性界面可以看到
    BIT_CHAR *pBusinessSecret = "xxx";      // 业务密钥，在业务属性界面可以看到
    BIT_CHAR *pAccount = "xxx";             // 用户帐号
    BIT_CHAR *pPassword = "xxx";            // 用户密码

    BIT_STATUS status = Bit_LoginByPassword(
       url,
       pBusinessGuid,
       pBusinessSecret,
       pAccount,
       pPassword,
       application_data,
       &handle);

    if (status == BIT_SUCCESS) 
    {
       printf("Login success");
    }

使用OIDC协议认证

认证协议为http，为了简化集成步骤，我们还提供了一些SDK进行调用集成。

跳转到托管登录页

跳转到托管登录页

    https://{host}.bitanswer.cn/oidc/auth?
            state={state}&
            scope=openid&
            client_id={client_id}&
            response_type=code&
            ui_locales=zh_CN+en&
            prompt=login&
            redirect_uri={redirect_uri}

    state: 状态码（开发商设置一个随机值，回调地址里会将这个值带回来，可以防止xss攻击）
    client_id: 业务的guid（开发商在bit平台创建的业务）
    redirect_uri: 认证通过后，重定向的地址

获取access_token

托管登录页认证成功后，会携带code回调客户端程序，客户端通过code就可以获取到access_token。

    curl --request POST \
         --url  https://{host}/oidc/token \
         --data ‘client_id=xxx&client_secret=xxxx&grant_type=authorization_code&code=xxx’

    client_secret: 业务密钥
    code：重定向传过来的code

鉴权

上一个步骤拿到access_token，就可以拿来直接调用授权库了。

    BIT_STATUS status = BIT_SUCCESS;
    BIT_HANDLE handle = NULL;
    BIT_CHAR *pAccessToken = “xxxxx”;

    status = Bit_LoginByToken(url, pAccessToken, application_data,  &handle);
    if (status == BIT_SUCCESS) 
    {
       printf(“Login success”);
    }

使用帐号密码直接获取access_token

    curl --request POST \
       --url  https://{host}/oidc/token \
       --data ‘client_id={client_id}&client_secret={client_secret}&grant_type=password&username={用户名}&password={密码}&scope=openid’

最佳实践

对于一款软件来讲，认证模块和主程序分开更有利于软件的开发，测试和维护。

结构示意图

Launchpad 程序：负责帐号的认证过程，认证通过后会产生access_token
主程序：Launchpad认证通过后，启动主程序并将access_token传入，主程序使用access_token进行授权

通用集成说明

本文提供了一个通用的集成方法，您可以通过本文介绍的构建请求的方式，在您的应用中添加相应的逻辑来集成我们的身份认证系统。

开发集成

构建认证端点请求

首先，您需要使用浏览器打开认证端点地址，地址要携带一些参数，包括：client_id，redirect_uri，scope，response_type等，这些参数您可以参考 OpenID Connect 协议。构建的地址应该会是下面这种形式：

      https://{{your-host}}.bitanswer.cn/oidc/auth?client_id={{your-client-id}}
          &redirect_uri={{your-redirect-uri}}
          &scope=openid%20profile%20email
          &state=1992215928
          &response_type=code
          &nonce=254234365
          &prompt=none
          &ui_locales=zh_CN%20en

在Java Web 应用中，您可以使用Spring Web提供的工具类，或者自行编写工具类，参照下方的代码构建URI：

UriComponentsBuilder.newInstance().scheme("https").host(host + ".bitanswer.cn").path("/oidc/auth")
          .queryParam("client_id", clientId)
          .queryParam("redirect_uri", redirectUri)
          .queryParam("scope", "openid profile email")
          .queryParam("state", new Random().nextInt())
          .queryParam("response_type", "code")
          .queryParam("nonce", new Random().nextInt())
          .queryParam("prompt", "none")
          .queryParam("ui_locales", "zh_CN en")
          .build()
          .toUri();

认证请求会打开托管登录页，在用户完成登录后，系统会携带code参数回调redirect_uri，您需要记录返回的code，用于获取tokens。回调的完整地址应该如下所示：

      https://{{your-redirect-uri}}?code=0f8ee45.e010016.688e016
          &state=3957

构建获取Token端点请求

获取token请求需要使用POST方法，请求地址为：https://{{your-host}}.bitanswer.cn/oidc/token

请求体包含如下参数：

code: {{code}}
client_id: {{your-client-id}}
client_secret: {{your-client-secret}}
grant_type: authorization_code

认证成功后请求会返回access_token，id_token等内容，请妥善保存。

获取用户信息

获取用户信息需要用到之前保存的access_token，使用POST方法，请求地址为：https://{{your- host}}.bitanswer.cn/oidc/userinfo

请求体包含如下参数：

access_token: {{access_token}}

构建登出请求

登出请求需要用到之前记录的id_token，执行登出请求会同时下线此设备上该用户登录的所有应用。

您需要使用浏览器打开登出端点地址，登出端点为：https://{{your- host}}.bitanswer.cn/oidc/end_session_endpoint

您的请求应该如下方所示：

        https://{{your-host}}.bitanswer.cn/oidc/end_session_endpoint?id_token_hint={{id_token}}
          &client_id={{your-client-id}}
          &post_logout_redirect_uri={{logout-redirect-uri}}
          &state=H06lz

执行登出请求后建议删除之前保存的tokens。