跳到主要内容

OIDC

1. 创建配置文件​

创建 sso.json 默认路径为 /data/hap/script/volume/sso/sso.json，内容如下：

注意：如果挂载后依然出现 404 ，可将内容复制到 json.cn 中验证 json 格式是否合法

{
  "mode": "common-oidc",
  "name": "oidc",
  "oidc": { 
    "oidcUrl": "",
    "clientId": "",
    "clientSecret": "",
    "redirectUrl": "{HAP}/orgsso/oidc-redirect",
    "responseTypes": "code",
    "scope": "openid email",
    "params": {
      "UserId": "sub",
      "Name": "name",
      "Email": "email",
      "Mobile": "phone_number"
    },
    "autoRegister": true,
    "projectId": ""
  }
}

部分参数及解释

参数类型是否必须含义
oidc.oidcUrlString是配置 oidc 服务发现地址；可设置返回格式如下： 配置参数示例
oidc.clientIdString是分发给应用的客户端 Id
oidc.clientSecretString是分发给应用的客户端密钥
oidc.redirectUrlString是回调地址；设置为 {HAP}/orgsso/oidc-redirect
oidc.responseTypesString是支持授权码模式；配置为 code
oidc.scopeString否获取用户信息范围；可填写为 openid,email,profile...任意组合;比如设置为 openid email； 默认为 openid
oidc.paramsObject是返回用户信息字段映射规则,key 为固定字段 value 根据实际用户信息配置；参数配置方法
oidc.params.UserIdString是用户唯一标识
oidc.params.NameString否姓名，用户已存在会覆盖
oidc.params.EmailString否邮箱；通过邮箱查找或者注册此字段必须设置； 邮箱或者手机号必须设置其中一个；如已经绑定第三方关系的，可通过关系查找用户，邮箱或手机可不设置
oidc.params.MobileString否手机号；通过手机号查找或者注册此字段必须设置；
oidc.params.PositionsArray否职位；自动更新用户的职位，不存在自动创建
oidc.params.DepartmentsArray否部门；自动更新用户的部门，不存在自动创建
oidc.params.SystemLanguageString否登录后的系统语言，目前支持 zh-Hans、en、ja、zh-Hant,默认为 zh-Hans
autoRegisterBoolean否当账号不存在时，是否自动创建账号；默认为 true
projectIdString是HAP 组织编号;组织管理(右上角) > 组织信息(页)>组织编号 ID;（多组织单点登录不需要配置此参数,见步骤 3) ；如 1x-2x-3x-4x-5x

交互示意图

OIDC 交互流程

获取访问令牌(access_token)的接口需要满足以下要求：

  • 支持 POST 方式调用（请求参数通过 URL 传递）

  • 需要先获得服务端 authorizePath 授权

  • 返回值为 JSON 格式，且需满足如下格式：

{
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ..."
}

获取用户信息的接口需要满足以下要求：

  • 支持 GET 方式调用（参考 userInfoUrl 参数说明）

  • 需要先获得服务端 authorizePath 授权

  • 返回值为 JSON 格式，且需满足如下格式：

{
  "sub": "248289761001",
  "name": "Jane Doe",
  "email": "janedoe@example.com",
  "phone_number": "123"
}

根据以上👆返回，则 params 的配置为：

"params": {
  "UserId": "sub",
  "Name": "name",
  "Email": "email",
  "Mobile": "phone_number"
}
oidcUrl 参考响应参数示例 
{
    "issuer": "https://oidc-demo.domain.com/oidc",
    "authorization_endpoint": "https://oidc-demo.domain.com/oidc/auth",
    "token_endpoint": "https://oidc-demo.domain.com/oidc/token",
    "claims_parameter_supported": false,
    "claims_supported": [
        "sub",
        "username"
    ],
    "code_challenge_methods_supported": [
        "plain",
        "S256"
    ],
    "end_session_endpoint": "https://oidc-demo.domain.com/oidc/session/end",
    "grant_types_supported": [
        "authorization_code",
        "password",
        "refresh_token"
    ],
    "response_types_supported": [
        "code"
    ],
    "scopes_supported": [
        "openid",
        "offline_access",
        "username",
        "phone",
        "email",
        "address",
        "profile"
    ],
    "userinfo_endpoint": "https://oidc-demo.domain.com/oidc/me",
    ......
}

2. 挂载配置文件​

修改微服务应用对应的 docker-compose.yaml，默认路径 /data/hap/script/docker-compose.yaml， 在 volumes 中增加文件挂载并重启微服务应用。

- ./volume/sso/sso.json:/usr/local/MDPrivateDeployment/sso/OptionFile/sso.json

开启关系查找​

如需要绑定第三方关联ID，则需要创建文件 extend.json 默认路径 /data/hap/script/volume/sso/extend.json 内容如下

{
  "relation": true
}

增加挂载文件

- ./volume/sso/extend.json:/usr/local/MDPrivateDeployment/sso/extend.json
提示

挂载配置完成需重启微服务应用

重启成功后可通过GET方式访问 {HAP}/orgsso/checkssoconfig 接口，查看配置文件是否挂载成功

3. 单点登录​

单组织

浏览器访问: {HAP}/orgsso/sso?returnUrl={returnUrl}

多组织

浏览器访问: {HAP}/orgsso/sso?returnUrl={returnUrl}&appKey={appKey}&sign={sign}&timestamp={timestamp}&projectId={projectId}

对于多组织 projectId 需要通过参数传递，还需要企业授权认证参数；

企业认证授权签名算法请参考：{HAP}/apidoc/zh-Hans/

备注

{HAP} 为 HAP 系统地址，比如可替换为：http://192.168.10.20:8880

{returnUrl} 为登录成功后的跳转地址，可不填写；比如需要跳转应用页面，则可替换为：http://192.168.10.20:8880/app/cf595091-e3ac-4669-a320-068e55533c33/64477b37df36209b5f36f1cf/64477b4f61655012a90ed994?from=insite

如果访问过程中出现的 SSO Error 提示，则可以通过管理员账号登录 HAP 系统，点击右上角头像： 平台管理>运维管理>日志；搜索服务名为 sso，排查具体报错原因