oidc-client

文档链接: https://github.com/IdentityModel/oidc-client-js/wiki

oidc-client

oidc-client 是一个 js 库, 运行在浏览器中. 目的是提供 OIDC 和 OAuth2.0 协议的支持, 来管理用户 session 和 token 的访问.

如果不了解 OpenID, 需要先学习一下该协议, 该库是准们为该协议开发的.

主要核心类有两个: UserManager 和 OidcClient

  • UserManager 是该库的核心类, 它提供了上层 API. 用于维护用户的登录, 登出, 以及从服务端获取用户 claims, 以及 token 等.
  • OidcClient 为授权端点提供了原始 OIDC/OAuth2.0 协议的支持. 相较于 UserManager 来说, 它提供了底层 API.

本文档重点放在 UserManager 上.

UserManager

配置

UserManager 构造函数需要一个配置对象参数. 参数属性有:

必须设置的属性
  • authority (字符串): OIDC/OAuth2.0 provider 的 URL 地址.
  • client_id (字符串): 在 OIDC/OAuth2.0 provider 中注册的客户端唯一标识符.
  • redirect_uri (字符串): 当客户端从 OIDC/OAuth2.0 provider 获得响应后重定向的地址.
  • response_type (字符串, 默认为 id_token): 期望从 OIDC/OAuth2.0 provider 返回的响应类型.
  • scope (字符串, 默认为 openid): The scope being requested from the OIDC/OAuth2 provider. 应该是: 可以从 OIDC/OAuth2.0 provider 请求的 scope 范围.
如果 OIDC/OAuth2.0 provider meta 端点不支持 CORS 则需要设置

属性 authority 中的 URL 用于发起 HTTP 请求, 并用于发现更多的 OIDC/OAuth2.0 信息, 并用于填充元数据属性.

简单来说就是动态获取一些元数据信息数据.

但是元数据端点 (meta endpoint) 如果不支持 CORS, 那么就需要手动设置.

这些信息可以在下面端点中获取:

  • 元数据属性包括
    • issuer
    • authorization_endpoint
    • userinfo_endpoint
    • end_session_endpoint
    • jwks_uri
  • 签名秘钥 (signingkeys) (它是 jwks_uri 端点返回的 key 属性)
  • 元数据种子 (metadataSeed) 可以用于设置发现请求结果的值与附加信息.
可选的授权请求类型

细节还是要把协议过一遍 (2024年6月11日)

  • prompt
  • display
  • max_age
  • ui_locales
  • login_hint
  • acr_values
其他可选设置

暂略 (2024年6月11日)

方法

  • getUser: 返回一个 Promise 来加载当前授权的用户 (User) 对象.
  • removeUser: 返回 Promise, 在所有存储中删除当前授权的用户.
  • signinRedirect: 返回 Promise 来触发重定向到授权端点.
  • signinRedirectCallback: 返回 Promise 来处理来自授权端点的响应. Promise 的返回值为授权的 User.
  • signinSilent: 返回一个 Promise 来向授权端点发送一个无声请求 (通过一个 iframe). Promise 的返回值是授权后的 User.
  • signinSilentCallback: 返回 Promise, 来通知获得授权端点响应的父窗口.
  • signinPopup: 返回 Promise, 通过 popup 窗口的方式跳转到授权页, Promise 返回的是授权后的 User.
  • signinPopupCallback: 返回 Promise 来通知触发打开的窗体.
  • signoutRedirect: 返回 Promise, 其他略.
  • signoutRedirectCallback: 返回 Promise, 其他略
  • signoutPopup: 返回 Promise, 其他略
  • signoutPopupCallback: 返回 Promise, 其他略
  • querySessionStatus [1.1.0]: 返回 Promise 来查询当前用户的登录状态. 返回对象含有 session_state, 以及 subject identifier.
  • startSilentRenew [1.4.0] 启用 silent renew.
  • stopSilentRenew [1.4.0] 禁用 silent renew.
  • clearStaleState: Removes stale state entries in storage for incomplete authorize requests.

属性

  • settings: 返回 UserManager 的设置信息.
  • events: 返回一个对象, 描述注册的事件.
  • metadataService: 返回一个对象, 用于访问 OIDC provider 的元数据配置.

事件

UserManager 会绑定各种与用户会话 (user's session) 相关的事件:

  • userLoaded. 当 user session 建立, 或更新时触发该事件.
  • userUnloaded. 当 user session 结束的时候触发.
  • accessTokenExpiring. 当令牌过期之前触发.
  • accessTokenExpired. 当令牌过期之后触发.
  • silentRenewError. 自动静默更新时触发.
  • userSignedIn. 用户登录时触发.
  • userSignedOut. 登出时触发.
  • userSessionChanged. session 修改时触发, 监视 session 变化时设置.

注册事件的语法是使用 UserManager 实例的 events 属性的 addXXX 方法, 移除事件使用 removeXXX 方法. 例如:

var mgr = new UserManager()
mgr.events.addAccessTokenExpiring(() => {
  console.log('token expiring ...')
})

User

User 类型的数据是 UserManager 实例的 getUser() 方法返回的对象. 其成员包括:

  • id_token: 由 OIDC provider 返回的 id_token.
  • profile: 用户的元数据信息. The claims represented by a combination of the id_token and the user info endpoint. 由 id_token 与用户信息端点合并表示的元数据信息.
  • session_state: OIDC provider 返回的 session state 信息.
  • access_token: ...
  • scope: ...
  • expires_at: ...
  • expires_in: 还可访问令牌的秒数.
  • expired: 是否过期.
  • scopes: 数组类型...

Logging

内置了日志模块, 默认是没有配置的. 配置语法:

Oidc.Log.logger = console

日志也分级别, 设置 Oidc.Log.level 来启用. 可设置的级别有:

  • Oidc.Log.NONE
  • Oidc.Log.ERROR
  • Oidc.Log.WARN
  • Oidc.Log.INFO (默认)

案例

略

练习

略

Last Updated:
Contributors: jk