目录

移动应用ID Token模式接入华为帐号(OpenID Connect)

场景介绍

适用于基于HarmonyOS的移动端应用,希望基于OpenID Connect协议标准接入华为帐号的场景。

ID Token模式基于OpenID Connect协议,应用可以通过获取帐号用户身份认证信息(ID Token),使用户通过帐号安全登录您的应用。首次登录时,要求用户同意授权,当身份验证信息到期时,用户每次登录时都应同意授权。

支持的设备

设备类型

OS版本

HMS Core(APK)版本

手机、平板

HarmonyOS 2.0及以上

5.0.0.300及以上

车机

HarmonyOS 2.0及以上

6.2.0.300及以上

华为智慧屏、智能手表(wearable,不支持运动手表liteWearable)

HarmonyOS 2.0及以上

6.5.0.300及以上

HarmonyOS(Java)必须在单HAP包场景下使用,暂不支持多HAP包场景。

开发前提

请确认您已完成开发准备。

帐号登录授权

  1. 初始化华为帐号SDK。

    在使用华为帐号SDK之前,要求应用先通过调用AccountAuthManager.init(AbilityPackage abilityPackage)方法,完成华为帐号SDK的初始化。

    建议在应用初始化的时候就完成华为帐号SDK的初始化,如下。

    “Java”
    // 示例:在应用初始化时就完成华为帐号SDK的初始化
    public class MyApplication extends AbilityPackage {
        @Override
        public void onInitialize() {
            super.onInitialize();
            // 调用示例initHuaweiAccountSDK方法,在HarmonyOS应用初始化方法onInitialize中进行华为帐号SDK初始化
            initHuaweiAccountSDK();
        }
        @Override
        public void onEnd() {
            super.onEnd();
        }
     
        // 示例:此方法中调用华为帐号SDK的初始化方法AccountAuthManager.init()进行初始化
        private void initHuaweiAccountSDK() {
            Task<Void> task;
            try {
                // 调用AccountAuthManager.init方法初始化
                task = AccountAuthManager.init(this);
            } catch (ApiException apiException) {
                apiException.getStatusCode();
                return;
            }
            task.addOnSuccessListener(new OnSuccessListener<Void>() {
                @Override
                public void onSuccess(Void v) {
                    //初始化成功
                }
            });
     
            task.addOnFailureListener(new OnFailureListener() {
                @Override
                public void onFailure(Exception e) {
                    // SDK初始化失败
                    if (e instanceof ApiException) {
                        ApiException apiException = (ApiException) e;
                        // SDK初始化失败,status code标识了失败的原因,请参见API参考中的错误码了解详细错误原因
                        apiException.getStatusCode();
                    }
                }
            });
        }
    }
  2. 添加登录按钮btn_hwid_sign_in。
    您根据需要在应用布局文件中添加华为帐号登录按钮。

    如您需要使用华为帐号登录图标,请参见华为帐号登录图标使用规范。

  3. 将huaweiIdSignIn绑定到登录按钮ResourceTable.Id_btn_hwid_sign_in的onClick响应事件中,实现华为帐号登录功能。当用户点击登录按钮时,会启动登录视图。
    “Java”
        Button mBtnHuaweiIdSignIn = (Button) findComponentById(ResourceTable.Id_btn_hwid_sign_in);
        mBtnHuaweiIdSignIn.setClickedListener((Component c) -> {
                huaweiIdSignIn();
            });
  4. 调用华为帐号登录接口获取ID Token。

    在huaweiIdSignIn方法中,构造登录授权请求参数AccountAuthParams和华为帐号登录授权服务AccountAuthService。

    构造AccountAuthParams参数时,调用AccountAuthParamsHelper.setIdToken()方法设置使用idToken模式。

    调用静默登录接口silentSignIn进行静默登录。

    • 如果静默登录成功,在成功监听中获取华为帐号对象AuthAccount,通过AuthAccount.getIdToken()获取到ID Token。
    • 如果静默登录失败,需要在静默登录的失败监听中调用前台登录授权signIn接口,显式拉起登录授权视图进行登录,如果前台登录授权接口成功,在成功监听中获取华为帐号对象AuthAccount,通过AuthAccount.getIdToken()获取到ID Token。
       “Java” 
          private void huaweiIdSignIn() {
              AccountAuthService accountAuthService;
              // 1、配置登录请求参数AccountAuthParams,包括请求用户id(openid、unionid)、email、profile(昵称、头像)等。
              // 2、DEFAULT_AUTH_REQUEST_PARAM默认包含了id和profile(昵称、头像)的请求。
              // 3、如需要再获取用户邮箱,需要setEmail();
              // 4、通过setIdToken()来选择使用id token模式,最终所有请求的用户信息都可以从idtoken中解析出来
              AccountAuthParams accountAuthParams = new AccountAuthParamsHelper(AccountAuthParams.DEFAULT_AUTH_REQUEST_PARAM)
                      .setIdToken()
                      .createParams();
              try {
                  accountAuthService = AccountAuthManager.getService(accountAuthParams);
              } catch (ApiException e) {
                  // 处理初始化登录授权服务失败,status code标识了失败的原因,请参见API参考中的错误码了解详细错误原因
                  e.getStatusCode();
                  return;
              }
              // 调用静默登录接口。
              // 如果华为系统帐号已经登录,并且已经授权,会登录成功;
              // 否则静默登录失败,需要在失败监听中,显式调用前台登录授权接口,完成登录授权。
              Task<AuthAccount> task = accountAuthService.silentSignIn();
              // 添加静默登录成功处理监听
              task.addOnSuccessListener(new OnSuccessListener<AuthAccount>() {
                  @Override
                  public void onSuccess(AuthAccount authAccount) {
                      // 静默登录成功,从authAccount中获取idToken,开发者需要对idToken进行验证
                      authAccount.getIdToken();
                  }
              });
              // 添加静默登录失败监听
              task.addOnFailureListener(new OnFailureListener() {
                  @Override
                  public void onFailure(Exception e) {
                      if (e instanceof ApiException) {
                          // 静默登录失败,显式调用前台登录授权signIn接口,完成登录授权。
                          Task task = accountAuthService.signIn();
                          if (task == null) {
                              return;
                          }
                          task.addOnSuccessListener(new OnSuccessListener<AuthAccount>() {
                              @Override
                              public void onSuccess(AuthAccount account) {
                                   // 从account中获取idToken,开发者需要对idToken进行验证
                                   account.getIdToken();
                              }
                          });
                          task.addOnFailureListener(new OnFailureListener() {
                              @Override
                              public void onFailure(Exception e) {
                                  if (e instanceof ApiException) {
                                      ApiException apiException = (ApiException) e;
                                      // 登录失败,status code标识了失败的原因,请参见API参考中的错误码了解详细错误原因
                                      apiException.getStatusCode();
                                  }
                              }
                          });
                      }
                  }
              });
          }

[h2]验证ID Token有效性

方式一:本地验证

适合场景:无应用服务器场景。

  1. 从https://oauth-login.cloud.huawei.com/.well-known/openid-configuration的返回值中的jwks_uri字段获取公钥URI,访问公钥URI获取公钥。公钥每天更新一次,应用服务器可以缓存公钥的值。
  2. 验证签名。ID Token是JWT格式的,验证ID Token的签名可以采用通用的JWT库,例如jwt.io。

    JWT仅支持Android 9.0及以上版本使用。

  3. 验证ID Token中iss字段的值是否等于“https://accounts.huawei.com”。
  4. 验证ID Token中aud字段的值等于应用的client_id。
  5. 验证ID Token中的过期时间(exp字段)是否已过期。

    如果以上验证均通过,则表示用户ID Token验证通过,应用可使用登录结果中的用户信息。

方式二:服务端验证

适合场景:有应用服务器场景。

  1. 接收客户端发送过来的ID Token。

    该部分代码需要您根据应用设计自己开发。

  2. ID Token校验并获取用户信息。

    校验与解析ID Token,详细步骤请参见ID Token验证签名。

    1. 为方便您快速调用接口,华为提供了一个基于Java语言的accountservertool.jar,该jar包提供了ID Token服务端校验与解析静态方法IdTokenUtil.getUserInfosByIdToken(String idToken,String appId),供您参考,详细信息请参见accountservertool.jar工具包使用说明。
    2. 如ID Token校验失败,则应用需要重新获取ID Token。
    3. 如果只用于测试,应用可调用验证ID Token有效性的接口向华为帐号服务器发送ID Token验证请求,华为帐号服务器向应用直接返回验证结果。由于调用验证ID Token有效性的接口会带来耗时,并且受网络状况的影响,所以服务器验证方式只能用于调试目的,在商用环境需要采用应用服务器验证的方式。

帐号退出

帐号退出是指应用向用户提供可以退出当前华为帐号退出的入口,应用通过signOut接口通知HMS Core SDK清除本地当前已经登录的华为帐号信息。

  1. 您可以将如下signOut绑定到登出按钮的onClick响应事件中,实现华为帐号退出功能。
    “Java”
            Button mBtnHuaweiIdSignOut = (Button) findComponentById(ResourceTable.Id_btn_signout);
            mBtnHuaweiIdSignOut .setClickedListener((Component c) -> {
                signOut();
            });
  2. 调用AccountAuthService类对象的signOut方法,实现华为帐号退出。
    “Java”
        private void signOut() {
            AccountAuthService accountAuthService = null;
            AccountAuthParams accountAuthParams = new AccountAuthParamsHelper(AccountAuthParams.DEFAULT_AUTH_REQUEST_PARAM).setEmail().createParams();
            try {
                accountAuthService = AccountAuthManager.getService(accountAuthParams);
            } catch (ApiException e) {
                // 处理初始化登录授权服务失败,status code标识了失败的原因,请参见API参考中的错误码了解详细错误原因
                e.getStatusCode();
                return;
            }
            Task<Void> task = accountAuthService.signOut();
            task.addOnSuccessListener(new OnSuccessListener<Void>() {
                @Override
                public void onSuccess(Void v) {
                    // 华为帐号登出成功,接入应用处理登出后逻辑
                }
            });
     
            task.addOnFailureListener(new OnFailureListener() {
                @Override
                public void onFailure(Exception e) {
     
                    // 华为帐号退出失败
                    if (e instanceof ApiException) {
                        ApiException apiException = (ApiException) e;
                        // 华为帐号退出失败,status code标识了失败的原因,请参见API参考中的错误码了解详细错误原因
                        apiException.getStatusCode();
                    }
                }
            });
        }

取消授权

为了提升应用隐私安全,应用可以提供入口,供用户取消对应用的授权。

取消授权接口通过调用AccountAuthService类对象的cancelAuthorization方法,实现取消授权。

  1. 您可以将如下cancelAuthorization方法绑定到取消授权按钮的onClick响应事件中,实现华为帐号取消授权功能。
    “Java” 
            mBtnCancelAuthorization = (Button) findComponentById(ResourceTable.Id_btn_cancelauthorization);
            mBtnCancelAuthorization.setClickedListener((Component c) -> {
                cancelAuthorization();
            });
  2. 调用AccountAuthService类对象的cancelAuthorization方法,实现华为帐号取消授权功能。
    “Java” 
        private void cancelAuthorization() {
            AccountAuthService accountAuthService;
            AccountAuthParams accountAuthParams = new AccountAuthParamsHelper(AccountAuthParams.DEFAULT_AUTH_REQUEST_PARAM).setEmail().createParams();
            try {
                accountAuthService = AccountAuthManager.getService(accountAuthParams);
            } catch (ApiException e) {
                // 处理初始化登录授权服务失败,status code标识了失败的原因,请参见API参考中的错误码了解详细错误原因
                e.getStatusCode();
                return;
            }
            // 调用取消授权接口
            Task<Void> task = accountAuthService.cancelAuthorization();
            task.addOnSuccessListener(new OnSuccessListener<Void>() {
                @Override
                public void onSuccess(Void v) {
                    // 取消授权成功
                }
            });
     
            task.addOnFailureListener(new OnFailureListener() {
                @Override
                public void onFailure(Exception e) {
                    // 取消授权失败
                    if (e instanceof ApiException) {
                        ApiException apiException = (ApiException) e;
                        // 华为帐号取消授权失败,status code标识了失败的原因,请参见API参考中的错误码了解详细错误原因
                        apiException.getStatusCode();
                    }
                }
            });
        }