Android SDK

概述

AuthCenter为广大安卓手机开发者提供了多种登录认证模块的SDK包，辅助开发者快速接入登录、注册、生物认证等功能。 AuthCenter SDK基于开源库AppAuth，也基于OAuth 2.0和OpenID Connect的现代认证的解决方案。在AppAuth的基础上，AuthCenter SDK还提供了Embedded Webview的认证场景：

场景一、AppAuth开源认证，基于Custom Tabs方案（Custom Tabs 是 Android 平台上的一个功能，它允许应用程序在内部使用对custom tabs API支持浏览器的标签页 ，而无需用户离开应用程序），但国内绝大部分浏览器对custom tabs API不支持，只能使用系统浏览器进行认证（跨应用）；

场景二、Embedded Webview实现app内嵌webview认证方案，在Custom Tabs浏览器支持很少下，Embedded Webview下的认证方案，覆盖全机型，体验好、适配少、安全性高。该方案不仅支持通用的认证方法，还支持Passkeys的生物认证方法，使用Passkeys在APP内一键登录，快捷、安全、效率高，Embedded Webview内Passkeys的接入方法见【通用密钥认证】。

最新SDK包

SDK包介绍

Android SDK支持的版本

AuthnCenterSDK类

AuthnCenterSDK类, SDK的管理类，负责内部功能参数设置。

/**
 *  设置使用认证的场景
 * @param scene
 *      BROWSER(0)              系统浏览器（包含CustomTabs场景）,
 *      EmbeddedWebView (1)     内嵌浏览器 ;
 *
 *      使用BROWSER(0)，但未使用setDefaultBrowser设置目标浏览器，SDK打开BROWSER规则： //1. support custom tabs
 *          1.1 interface set browser (under supporting)
 *          1.2 系统原生浏览器 (under supporting)
 *          1.3 Chrome > Edge > FireFox > Opera > Samsung    (under supporting)
 *              match package + version
 *          2. system browser
 *              2.1 interface set browser
 *          2.2 系统原生浏览器
 *          2.3 default browser
 **/
public void setAuthorizationScene(AuthorizationScene scene)


/**
 * 设置配置服务器地址，保留选项，暂未启用
 * @param discoveryUrl    DiscoveryUri地址
 */
public void setDiscoveryUri(String discoveryUrl)

/**
 * 设置SDK使用哪个浏览器， 该参数在设置setAuthorizationScene为BROWSER(0)生效
 *
 * @param packageName      浏览器packageName
 * @param bUseCustomTab    是否使用CustomTab模式，注：选择的浏览器不支持CustomTabs模式，则会直接打开该浏览器认证
 */
public void setDefaultBrowser(String packageName , boolean bUseCustomTab) 

/**
 *  SDK响应外部shceme的协议，需要在集成工程中配置
 *  在工程的build.gradle中： manifestPlaceholders.putIfAbsent("appAuthRedirectScheme", "net.rj.appauth")
 *
 * @param launchScheme shceme协议，如上demo所示的net.rj.appauth
* */
public void setLaunchScheme(String launchScheme)


/**
 * 设置ActionBar背景色
 * @param actionBarColor 背景色
 * */
public void setActionBarColor(int actionBarColor)

/**
 * 设置StatusBar背景色
 * @param stutasColor 背景色
* */
public void setStatusBarColor(int stutasColor) 

/**
 * 初始化SDK
 * @param context 上下文
 **/
public void initInterface(Context context) 

/**
 * 设置认证信息，client id设置
 * @param clientid 认证app Client id
 * */
public void setClientId(String clientid) 

/**
 * 设置认证信息 ， 登录成功定位的url
 * @param url 认证redirect url
 * */
public void setRedirectUri(String url) 

/**
 * 设置认证信息 ，退出登录后定位url， 保留参数，暂未启用
 * @param url 退出登录redirect url
 * */
public void setEndSessionRedirectUri(String url) 

/**
 * 设置认证信息，scope设置
 * @param scope 认证Scope
 * */
public void setAuthorizationScope(String scope)

/**
 * 设置认证信息：认证地址
 * @param url 认证地址
 * */
public void setAuthorizationEndpointUri(String url)

/**
 * 设置认证信息：token request url
 * @param url 认证token获取
 **/
public void setAuthorizationTokenEndpointUri(String url) 


/**
 * 设置认证信息 ， 使用https
 * @param bHttps ：true，使用https
 **/
public void setHttpsRequired(boolean bHttps)
/**
 * 设置允许使用webview中JSAPI的域名
 * 内置白名单： authorizationEndpointUrl redirectUrl endSessionRedirectUrl endSessionRedirectUrl
 * @param jsonUrls ：urls为json数组
 * */
public void setJsAPIPermissions(String jsonUrls)

/**
 * 清空本地的登录态
 * @param context ：上下文
 * @param callback ： 清空后回调信息
 *                 成功回调： json格式{"code":200}
 *                 失败回调： 参考接口文档errCode
 */
public void endSession(Context context , AuthnCenterCallback callback)

/**
 * 在参数设置成功下，启动SDK进行认证
 * @param context ：上下文
 * @param callback ： 认证成功后回调
 *      成功回调：json格式{"code":0,"access_token":"","id_token":"",expires_in:""}
 *      失败回调：参考接口文档errCode
 **/
public void getAuthenticationIntent(Context context, AuthnCenterCallback callback)


/**
 * 获取系统浏览器信息
 * @param context ：上下文
 * @return  json string: [{"packagename":"" , "isCustomTab":,"icon":"" , "version":""}]
 **/
public String getBrowserSelectors(Context context )

必须接口中参数来源说明（关于url域名的绝对地址拼装，参考【概述】-【域名地址配置说明】）：

AuthnCenterCallback回调接口

/**
*  成功后回调
@param authInfo ， 请参考输入接口说明
*/
public void onSuccess(String authInfo);

/**
* 失败后回调
* errCode参考errCode
*/
public void onFailure(long errorCode, CharSequence errString);

SDK接口错误码

项目工程配置

SDK内部会接受scheme的响应，在认证过程中，非内嵌webview认证场景会通过scheme通知app，所以在sdk内部manifest.xml使用appAuthRedirectScheme参数占位scheme字符串，APP项目工程的build.gradle脚本需配置:

manifestPlaceholders.putIfAbsent("appAuthRedirectScheme", "net.rj.appauth")

”net.rj.appauth“为例子，接入方可以修改为自己的命名。在调用SDK接口中，需要通过接口：setLaunchScheme设置到SDK中。

Embedded Webview内通用密钥认证集成

国内支持通行密钥的机型不是很多，其中对通行密钥有适配的为华为和OPPO机型，使用系统浏览器可以通过Passkeys注册和认证。在APP内，场景一的使用，可以天然的使用Passkeys的功能；但在embedded webview上，passkeys是不支持的，需要我们单独的接入平台的认证器SDK。 本篇介绍的是使用Embedded Webview接入通行密钥的方案。当前webview支持华为和OPPO的机型，需要分别对两个平台进行接入配置。

注： 场景二使用Passkeys必须配置该章节内容。

Embedded Webview内通信密钥支持平台

华为webview通行密钥接入

1. 配置AppGallery Connect

   • a. 注册成为华为开发者
   • b. 创建应用
   • c. 配置AppGallery Connect签名指纹
   • d. 打开服务开关
   • 以上详细操作手册：https://developer.huawei.com/consumer/cn/doc/Security-Guides/config-agc-0000001050262772

2. 集成HMS Core配置文件，如果在AppGallery Connect中开通了相关服务则需要将“agconnect-services.json”文件添加到您的App中。

   • a. 登录AppGallery Connect网站，点击“我的项目”。
   • b. 在项目列表中找到您的项目，在项目中点击需要集成HMS Core SDK的应用。
   • c. 在“项目设置 > 常规”页面的“应用”区域，点击“agconnect-services.json”下载配置文件。
   • d. 将“agconnect-services.json”文件拷贝到应用级根目录下。

   

OPPO webview通行密钥接入

• 创建一个 JSON 文件。例如，如需声明网站 https://s10sso.ruishan.cc 和软件包名 com.ruishan.authcenter 的 Android 应用可以共享通行密钥，请使用以下内容创建一个名为 fido2-trusted-facets.json 的文件：

  [
  {
    "relation" : [
      "delegate_permission/common.get_login_creds"
    ],
    "target" : {
      "namespace" : "android_app",
      "package_name" : "com.ruishan.authcenter",
      "sha256_cert_fingerprints" : [
        SHA_HEX_VALUE
      ]
    }
  }
  ]
  

  relation 字段是包含一个或多个字符串的数组，用于描述所声明的关系。如需声明应用和网站可共享登录凭据，请指定字符串 delegate_permission/common.get_login_creds。 target 字段是一个对象，用于指定声明所适用的资源。 以下字段用于标识 Android 应用：

• 将这个 JSON 文件托管在登录网域中 例如，如果你的登录网域是 s10sso.ruishan.cc，请将 JSON 文件托管在以下位置。Digital Asset Links 文的 MIME 类型需为 JSON。确保服务器在响应中发送 Content-Type: application/json 标头。

  https://s10sso.ruishan.cc/.well-known/fido2-trusted-facets.json
  

统一认证服务端配置：识别APP认证

sso组件：application-sys.properties中加入APP的签名：

cas.authn.mfa.web-authn.core.allowed-originsandroid:apk-key-hash:aSCmCAdGEhSJ3kMYwTaM+bT50xosoqoQoIwSIjKfm+g

其中aSCmCAdGEhSJ3kMYwTaM+bT50xosoqoQoIwSIjKfm+g为例子，需要填入接入APP的key-hash。

计算 Key Hash： 使用以下命令来计算 Key Hash：
echo -n "<your_sha1_value>" | openssl sha1 -binary | openssl base64
将 <your_sha1_value> 替换为你APP签名的SHA1值。