oidc-client中文文档

oidc-client

原文地址：Home · IdentityModel/oidc-client-js Wiki · GitHubOpenID Connect (OIDC) and OAuth2 protocol support for browser-based JavaScript applications - Home · IdentityModel/oidc-client-js Wikihttps://github.com/IdentityModel/oidc-client-js/wiki

oidc-client是在浏览器中运行的JavaScript库（或者Cordova的应用程序，Cordova 是用于使用HTML，CSS和JS构建移动应用的平台，我们可以认为Cordova是一个容器，用于将我们的网络应用程序与本机移动功能连接。）。oidc-client提供了OIDC和OAuth2协议的支持，并为用户会话(sessions)和访问令牌(access tokens)管理提供管理功能。

如果你不熟悉 OpenID Connect，你应该先去学习OpenID Connect协议。该库是设计符合规范的协议库。

您可能会用到两个主要类，具体取决于您使用的情况：

UserManager类提供了更高级别的API，用于用户登录、注销、管理从OIDC 提供者返回的用户声明（claims），以及管理从OIDC/OAuth2 提供者返回的访问令牌(access token)。 UserManager是该库的主要功能。

OidcClient类在授权服务器中（authorization server），为授权端点（authorization endpoint）和结束会话端点（end session endpoint）提供原生 OIDC/OAuth2 协议的支持。它提供了一个基础协议的实现，并且为UserManager类使用它。

UserManager

本文档主要对UserManager类进行说明。

Configuration配置

UserManager 构造函数需要一个设置对象（settings object）作为参数，设置对象属性包含：

Required Settings必须配置

1. authority (string): OIDC/OAuth2 提供者的 URL。
2. client_id (string):客户端应用程序在 OIDC/OAuth2 提供程序中注册的标识符。
3. redirect_uri（string）：客户端应用程序的重定向 URI，用于接收来自 OIDC/OAuth2 提供者的响应。
4. response_type（string，默认值：'id_token'）：OIDC/OAuth2 提供者所需的响应类型。
5. scope（string，默认值：'openid'）：OIDC/OAuth2 提供者规定的请求范围。

当OIDC/OAuth2提供者元数据端点（metadata endpoint）不支持CORS时，需提供者设置

authority URL设置的作用是发起HTTP 请求，获取关于OIDC/OAuth2 提供程序的更多信息，并且在设置上填写元数据属性（metadata property）。如果服务器的元数据端点不允许CORS，可以手动进行配置，在提供者的元数据端点上，可以发现这些值：

1. 元数据属性包含：

1. Issuer 发行人
2. authorization_endpoint 授权端点
3. userinfo_endpoint 用户信息端点
4. end_session_endpoint 结束会话端点
5. jwks_uri JWKS全称为 JSON Web Key Set，是指多个JWK组合在一起的一种格式JWK在OIDC中的主要作用是为JWT(id_token)提供加密密钥，用于加密/解密或签名/验签，是JSON格式的数据。参考：https://andaily.com/blog/?tag=jwks

1. signingKeys签名密钥（这是jwks_uri端点的keys属性）
2. metadataSeed元数据种子可用于发起请求结果的种子或添加附加值。

Optional Authorization Request Settings 可选配置

1. prompt
2. display
3. max_age
4. ui_locales
5. login_hint
6. acr_values

Other Optional Settings 其他可选配置

1. clockSkew (number, default: 300): 验证 id_token 的 iat、nbf 和 exp 值时允许当前系统的时间偏差（以秒为单位）
2. loadUserInfo (boolean, default: true):是否从用户信息端点加载额外的身份数据以填充到用户配置
3. filterProtocolClaims (boolean, default: true): 告诉oidc-client过滤掉OIDC协议内部用的声明信息，如: nonce, at_hash, iat, nbf, exp, aud, iss 和 idp
4. post_logout_redirect_uri (string): OIDC/OAuth2 注销后重定向 URI
5. popup_redirect_uri (string): 是使用signinPopup方法是的重定向URL。如果你不想用弹出框来登陆，希望用户能到主登录界面登陆，那么你需要使用redirect_uri属性和signinRedirect 方法。
6. popupWindowFeatures (string, default:' location=no, toolbar=no, width=500, height=500, left=100, top=100'): 弹出登录窗口的 window.open 的 features 参数。
7. popupWindowTarget (string, default: '_blank'): 用于弹出登录窗口的 window.open 的目标参数。
8. silent_redirect_uri (string): 是指得到新令牌后需要重定向到的URL。
9. automaticSilentRenew (boolean, default: false): 启用自动静默刷新token，用来在令牌过期前自动更新令牌
10. silentRequestTimeout (number, default: 10000): 静默刷新超时时间
11. accessTokenExpiringNotificationTime (number, default: 60): 用来调整访问令牌过期通知时间.默认是过期前60 秒。
12. stateStore: (default: local storage): 用于持久化交互状态的存储对象
13. userStore: (default: session storage): 用于为当前经过身份验证的用户持久保存用户的存储对象，例如userStore: new WebStorageStateStore({ store: window.localStorage })
14. monitorSession [1.1.0]: (default: true): 当用户在 OP 执行注销时将引发事件
15. checkSessionInterval: (default: 2000): 检查用户会话的时间间隔，以毫秒为单位
16. revokeAccessTokenOnSignout [1.2.1] (default: false): 如果用户有访问令牌，将在注销时吊销
17. includeIdTokenInSilentRenew [1.4.0] (default: true): 用于控制 id_token 是否作为 id_token_hint 包含在静默刷新调用中的标志。
18. staleStateAge (default: 300): 一个数字（以秒为单位），指示用于授权被认为已放弃并可以清除的请求的存储状态
19. extraQueryParams: (object): 包含要包含在授权请求中的附加查询字符串参数的对象。例如，当使用 Azure AD 获取访问令牌时，需要额外的资源参数。
20. mergeClaims [1.11.0] (default: false): 指示从用户信息端点作为声明（例如地址）返回的对象是否作为单个对象合并到来自 id 令牌的声明中。 否则，它们将作为声明类型的不同对象添加到数组中。
21. client_authentication [1.11.0] (default: client_secret_post): 指示何时发送客户端机密，是作为post参数发送，还是使用HTTP基本协议在授权报头中发送client_secret_basic
22. clockService [1.11.0]: 可以配置为获取时钟时间的服务。用于处理时钟不正确的客户端机器。

Methods方法

1. getUser:返回当前通过身份验证的用户对象。
2. removeUser:从存储中移除当前已经认证得用户。
3. signinRedirect: 重定向登录。
4. signinRedirectCallback: 重定向登录回调。
5. signinSilent: 静默登录
6. signinSilentCallback: 静默登录回调
7. signinPopup: 弹窗登录
8. signinPopupCallback: 弹窗登录回调
9. signoutRedirect: 重定向登出
10. signoutRedirectCallback: 重定向登出回调
11. signoutPopup [1.4.0]: 弹窗登出
12. signoutPopupCallback [1.4.0]: 弹窗登出回调
13. querySessionStatus [1.1.0]: 查询当前登录状态
14. startSilentRenew [1.4.0]: 启用静默刷新
15. stopSilentRenew [1.4.0]:停止静默刷新
16. clearStaleState: 在存储中移除未完成的认证请求

Properties特性

1. settings：UserManager的配置信息
2. events： UserManager注册的事件
3. metadataService：访问OIDC的元数据配置对象。

Events事件

1. UserManager将引发有关用户会话的各种事件：
2. userLoaded：在建立（或重新建立）用户会话时引发。
3. userUnloaded：当用户会话终止时引发。
4. accessTokenExpiring：在访问令牌过期之前引发。
5. accessTokenExpired：在访问令牌过期后引发。
6. silentRenewError：自动静默更新失败时引发。
7. userSignedIn [1.9.0]：用户登录时引发。
8. userSignedOut [1.1.0]：当用户在 OP 的登录状态发生变化时引发。
9. userSessionChanged：当用户会话改变时引发（当 monitorSession已设置）

要注册事件，UserManager 上有一个带有 addXxx 和 removeXxx API 的 events 属性，用于添加/删除事件的回调。

一个例子：

var mgr = new UserManager();

mgr.events.addAccessTokenExpiring(function(){

    console.log("token 将过期...");

});

User用户

通过 UserManager的 getUser方法返回User。 它包含以下属性：

1. id_token：从 OIDC 提供者返回的 id_token。
2. profile：由组合所代表的权利要求 id_token和用户信息端点。
3. session_state：从 OIDC 提供者返回的会话状态值。
4. access_token：从 OIDC 提供者返回的访问令牌。
5. scope：从 OIDC 提供程序返回的范围。
6. expires_at：OIDC 提供者返回的过期时间。
7. expires_in：计算出的访问令牌剩余的秒数。
8. expired：表示访问令牌是否过期的计算值。
9. scopes：表示解析值的数组 scope。

Logging日志记录

oidc-client-js 库支持日志记录。 您可以给任何支持接受 params 数组的 info、warn 和 error 方法配置记录器。 默认情况下，没有配置记录器。

浏览器的控制台启用日志记录：

Oidc.Log.logger = console;

Oidc.Log.level日志级别：

1. Oidc.Log.NONE
2. Oidc.Log.ERROR
3. Oidc.Log.WARN
4. Oidc.Log.INFO（默认值）

Samples示例

• Angular2
• Aurelia
• ReactJS & Redux
• Blog post on Angular
• Vue.js
• Quasar Framework
• Angular2
• Vue/Vuex
• React Context & React Redux
• Angular and Keycloak
• React Helper Library