## 简介 [Logto](https://logto.io/) 为我们的开发人员和商业团队提供全面的客户身份和访问管理（CIAM）解决方案。我们提供各种不同平台和应用框架的现成 SDK。结合我们的 Logto 云服务，你可以在几分钟内轻松地建立一个高度安全的用户授权流程。作为一个从开发者社区诞生的公司，Logto 拥抱并珍视我们的社区参与。除了那些官方开发的 Logto SDK，我们持续鼓励并热烈欢迎来自社区的开发人员通过创建更多元化和用户友好型的 SDK，满足各种平台和框架的独特需求。在本文中，我们将简要演示如何逐步实现一个 OIDC 标准认证 SDK。在 Logto 中创建你的应用程序 ## 上下文 OpenID Connect（OIDC）流程是一种建立在 OAuth 2.0 框架之上的认证协议，它提供了身份验证和单一签-on 盾示的能力。它允许用户与应用程序进行身份验证，并得到进一步安全访问任何私有资源的授权。请参阅 OIDC 规范以获取更多详细信息。 ### 工作流程一个标准的授权代码流程包括以下步骤: ```mermaid sequenceDiagram actor user as End User participant app as Client App participant server as Authorization Server participant resource as Private Resources user ->> app: anonymous visitor sign-in app ->> server: send authentication request server -->> user: redirect to the user sign-in page user ->> server: sign-in with credentials server -->> app: redirect back to the client app with authorization_code app ->> server: token exchange request with the authorization_code server ->> app: grant id_token, access_token and refresh_token app -->> user: authenticated app ->> resource: private api request with access_token resource --> server: sync signing key resource -->> resource: token validation resource ->> app: 200 OK ``` #### 认证流程 1. **用户发起登录请求：**一个匿名用户从一个公共入口来到你的应用程序。试图进行认证并可能进一步请求访问第三方应用或服务的受保护资源。 2. **用户认证：**客户端应用生成一个认证 URI，并发送请求到授权服务器，该服务器将用户重定向到其登录页面。用户使用各种登录方法与登录页面进行交互，并由授权服务器进行认证。 3. **处理登录回调：**在成功的认证之后，用户将会被重定向回你的应用程序，并附带获得的 `authorization_code` . 这个 `authorization_code` 包含了与认证状态和请求的授权数据相关的所有权限。 4. **令牌交换：**使用从上面的重定向地址抽取的 `authorization_code` 请求进行令牌交换。回报是: - `id_token`：包含认证用户身份信息的数字签名 JWT。 - `access_token`：一个不透明的 `access_token`，可以用来访问用户基础信息端点。 - `refresh_token`：允许用户维持对 `access_token` 的持续交换的凭据令牌。 #### 授权流程 1. **访问用户信息：**要访问更多的用户信息，应用程序可以使用从初始令牌交换流程中获得的不透明 `access_token` 向 UserInfo 端点发出额外的请求。这能够获取关于用户的更多详细信息，如他们的电子邮件地址或个人资料照片。 2. **允许访问受保护的资源：**如果需要，应用程序可以使用 `refresh_token` 结合 `resource` 和 `scope` 参数，向令牌交换端点发出额外的请求，以获得用于用户访问目标资源的专用 `access_token`。这个过程会导致一个 JWT 格式的 `access_token` 的发行，它包含了访问受保护资源所需的所有授权信息。 ## 实现我们将在我们的 @logto/client JavaScript SDK 中遵循一些设计策略，来展示实现一个简单 SDK 的过程。请记住，详细的代码结构可能会根据你正在使用的客户端框架而有所不同。你可以自由地选择任何 Logto 官方 SDK 作为你自己的 SDK 项目的示例。 ### 预览 ```ts class LogtoClient { protected readonly logtoConfig: LogtoConfig; protected readonly storage: Storage; protected oidcConfig: OidcConfig; protected accessTokenMap: Map constructor(logtoConfig: LogtoConfig) {} get async idToken(){} private async getOidcConfig(){} private async getJwksFunction() {} private async verifyIdToken() {} private async saveTokens() {} private async setSignInSession() {} private async getSignInSession() {} private async getAccessTokenByRefreshToken() {} async signIn(redirectUri: string) {} async handlerSignInCallback (callbackUri: string) {} async getUserInfo() {} async getAccessToken(resource?: string, scopes?: string[]) {} } ``` ### 构造器构造器应该接受一个 [logtoConfig](#logto-config) 作为其输入。这提供了所有你需要通过这个 SDK 建立一个认证连接的必要配置。根据您为 SDK 使用的平台或框架，您可能会将一个持久的本地存储实例传给构造器。这个存储实例将被用来存储所有的授权相关的令牌和秘密。 ```ts class LogtoClient { constructor(logtoConfig: LogtoConfig, storage: Storage) {} } ``` ### 初始化用户认证在生成一个认证请求 URL 前，完成几个准备步骤是非常必要的，以确保一个安全的过程。 #### 从授权服务器获取 OIDC 配置定义一个私有方法 `getOidcConfigs` 从授权服务器的发现端点获取 OIDC 配置。OIDC 配置响应包含了客户端可以用来与授权服务器交互的所有元数据信息，包括其端点位置和服务器的能力。 (请参阅 [OAuth OAuth 认证服务器元数据规范](https://datatracker.ietf.org/doc/html/rfc8414) 以获取更多详细信息。) ```ts const discoveryPath = "/oidc/.well-known/openid-configuration"; private async getOidcConfigs() { if (this.oidcConfig) { return this.oidcConfig; } const response = await fetch(`${this.logtoConfig.endpoint}${discoveryPath}`) this.oidcConfig = await response.json(); return this.oidcConfig; } ``` #### PKCE 生成器一个 [PKCE(Proof Key for Code Exchange)](https://datatracker.ietf.org/doc/html/rfc7636) 验证流程对于所有的公共客户端授权代码交换流都是必要的。它可以降低 authorization_code 的截取攻击的风险。因此，所有的公共客户端应用（例如，本地应用和 SPA）的授权请求都需要一个 `code_challenge` 和 `code_verifier`。实现方式可能会因你使用的语言和框架而有所不同。请参考 [code_challenge](https://datatracker.ietf.org/doc/html/rfc7636#section-4.2) 和 [code_verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) 规范获得详细的定义。如果你正在做一个机密的客户端或者服务器渲染的 web 应用程序，如 express 或者 nextjs，请直接跳到下一步。关于 PKCE 以及公共客户端和机密客户端之间的区别的更多信息，请查看我们的 [OAuth 安全复习](https://blog.logto.io/oauth-security-recap). ```ts class PKCE { readonly codeVerifier: string; readonly codeChallenge: string; constructor() { this.codeVerifier = this.generateCodeVerifier(); this.codeChallenge = this.generateCodeChallenge(this.codeVerifier); } /** * Generates code verifier * * @link [Client Creates a Code Verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) */ private generateCodeVerifier() { return generateRandomString(); } /** * Calculates the S256 PKCE code challenge for an arbitrary code verifier and encodes it in url safe base64 * * @param {String} codeVerifier Code verifier to calculate the S256 code challenge for * @link [Client Creates the Code Challenge](https://datatracker.ietf.org/doc/html/rfc7636#section-4.2) */ private async generateCodeChallenge(codeVerifier: string) { const encodedCodeVerifier = new TextEncoder().encode(codeVerifier); const codeChallenge = new Uint8Array( await crypto.subtle.digest('SHA-256', encodedCodeVerifier) ); } } ``` #### 生成 state 参数在授权流程中，[state 参数](https://blog.logto.io/oauth-security-recap/#state) 是一个随机生成的值，它被包含在客户端发送的授权请求中。它作为一个安全措施，来防止跨站请求伪造（CSRF）攻击。 ```ts const state = generateRandomString(); ``` #### 存储中间会话信息有几个参数需要被保留在存储中，用于用户在认证后被重定向回来后的验证。我们将实现一个方法来将这些中间参数设置到存储中。 ```ts protected async setSignInSession (data: { codeVerifier: string; redirectUri: string; state: string; }) { await this.storage.setItem('signInSession', data); } ``` #### 登录让我们将以上所有的内容封装起来，定义一个方法生成用户的登录 URL 并将用户重定向到授权服务器进行认证。 ```ts async signIn(redirectUri: string) { const { appId, resources, scopes } = this.logtoConfig; const { authorizationEndpoint } = await this.getOidcConfig(); // 仅适用于公共客户端应用 const pkce = new PKCE(); const state = generateRandomString(); const queryParameters = new URLSearchParams({ client_id: appId, redirect_uri: redirectUri, code_challenge: pkce.codeChallenge, code_challenge_method: 'S256', state, response_type: 'code', prompt: 'consent', scopes: [...reservedScopes, scopes], }); // 如果有任何资源指示器，则追加所有资源指示器 for (const resource of resources ?? []) { urlSearchParameters.append('resource', resource); } const signInUrl = new URL(`${authorizationEndpoint}?${urlSearchParameters.toString()}`); await this.setSignInSession({ redirectUri, state, codeVerifier: pkce.codeVerifier }); navigate(signInUrl); } ``` ### 处理用户登录回调在上一部分，我们创建了一个登录方法，这个方法生成了一个用于用户认证的 URL。这个 URL 包含了从客户端应用启动认证流程所需的所有必要参数。这个方法将用户重定向到授权服务器的登录页面的进行认证。在成功登录后，最终用户将被重定向回我们之前提供的 redirect_uri 的位置。所有必要的参数都将附带在 redirect_uri 中，以完成后续的令牌交换流程。 #### 抽取并验证回调 URL 这个验证步骤非常重要，以防止任何形式的伪造的授权回调攻击。在向授权服务器发送进一步的代码交换请求之前， **必须** 仔细验证回调 URL。首先，我们需要从应用的存储中检索之前存储的 signInSession 数据。 ```ts protected async getSignInSession () { session = await this.storage.getItem('signInSession', data); if (!session) { throw Error('Session not found'); } } ``` 然后在向授权服务器发送令牌交换请求之前，验证回调 URL 的参数。 - 使用以前保存的 `redirectUri` 来验证 `callbackUri` 是否与我们给授权服务器的一个。 - 使用以前保存的 `state` 来验证返回的 state 是否与我们给授权服务器的一个。 - 检查授权服务器是否返回了任何错误信息 - 检查返回的 `authorization_code` 的存在 ```ts verifyAndParseCodeFromCallbackUri(callbackUri: string, redirectUri: string, state: string) { const url = new URL(callbackUri) const parameters = url.searchParams; if (!callbackUri.startWith(redirectUri)) { throw new Error('redirect_uri_mismatched') } //Check the error message. // 如果认证失败，用户将会被带有附加错误参数的重定向回来 const error = parameters.get('error'); const errorDescription = parameters.get('error_description'); if (error || errorDescription) { throw new Error(`${error}:${errorDescription}`) } // 状态验证 const callbackState = parameter.get('state'); if (callbackState !== state) { throw new Error('state_mismatch'); } // 抽取授权代码 const code = parameters.get('code'); if (!code) { throw new Error('authorization_code_not_found') } return code; } ``` #### 发送代码交换请求作为用户认证流程的最后一步，我们将使用返回的 `authorization_code` 发送令牌交换请求，并获取必需的授权令牌。有关请求参数定义的更多详细信息，请参阅 [token exchange specification](https://datatracker.ietf.org/doc/html/rfc8693#section-2)。 - code: 我们从回调 URI 中收到的 `authorization_code` - clientId: 应用 ID - redirectUri: 是在为用户生成登录 URL 时使用的同一值。 - codeVerifier: PKCE 代码验证器。类似于 redirectUri，授权服务器将比较这个值和之前我们发送的，确保进入的令牌交换请求的验证。 ```ts const getTokenByAuthorizationCode = async (payload: { code: string; clientId: string; tokenEndpoint: string; redirectUri: string; codeVerifier: string; }) => { const parameters = new URLSearchParams({ client_id: payload.clientId, code: payload.code, code_verifier: payload.codeVerifier, redirect_uri: payload.redirectUri, grant_type: 'authorization_code', }); return fetch(tokenEndpoint, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' } body: parameters, }); } ``` #### 处理登录回调将我们所有的东西封装起来，我们构建一个 signInCallback 处理方法： ```ts private async saveTokens({refreshToken, idToken, accessToken}) { this.storage.setItem('refreshToken', refreshToken); this.storage.setItem('idToken', idToken); // opaque access token without resource indicator specification this.accessTokenMap.setItem('', accessToken) } async handleSignInCallback(callbackUri: string){ const signInSession = await this.getSignInSession(); if (!signInSession) { throw new Error('sign_in_session.not_found'); } const { redirectUri, state, codeVerifier } = signInSession; const code = verifyAndParseCodeFromCallbackUri(callbackUri, redirectUri, state); const { appId } = this.logtoConfig; const { tokenEndpoint } = await this.getOidcConfig(); const response = await getTokenByAuthorizationCode({ code, clientId: appId, tokenEndpoint, redirectUri, codeVerifier, }); await this.saveTokens(response); } ``` 结果，令牌交换请求将返回以下令牌： - `id_token`：OIDC idToken，一个包含关于认证用户身份信息的 JSON Web Token（JWT）。id_token 也可以被用作用户认证状态的 single source of truth(SSOT)。 - `access_token`：由授权服务器返回的默认授权代码。可以用于调用用户信息端点和检索已认证的用户信息。 - `refresh_token`：(如果在授权请求中存在 offline_access 作用域)：这个 refresh token 允许客户端应用获取一个新的 access token，无需要求用户重新认证，从而授予长期访问资源的权限。 - `expires_in`：以秒为单位的时间，即 access token 在过期前有效的持续时间。 ### ID token 验证验证并从 `id_token` 抽取声明是认证过程中的关键步骤，用于确保令牌的真实性和完整性。以下是验证 `id token` 的关键步骤： - 签名验证：`id_token` 由授权服务器使用其私钥进行数字签名。客户端应用需要使用授权服务器的公钥验证签名。这确保了令牌没有被篡改，并且的确是由合法的授权服务器签发的。 - 发行者验证：检查 `id_token` 中的 "iss"（发行者）声明是否与期望的值匹配，表示令牌是由正确的授权服务器颁发的。 - 观众验证：确保 `id_token` 中的 "aud"（观众）声明和客户端应用的客户端 ID 相匹配，确保令牌是针对客户端的 - 到期检查：验证 `id_token` 中的 "iat"（发行时间）声明是否已过当前时间，确保令牌仍然有效。由于有网络交易成本，我们需要在验证收到的令牌 iat 声称时设置一个发行时间容忍度。返回的 id_token 是一个标准的 JSON Web Token (JWT)。根据你使用的框架，你可以找到各种便利的 JWT 令牌验证插件来帮助解码和验证令牌。对于这个例子，我们将在我们的 JavaScript SDK 中使用 [jose](https://www.npmjs.com/package/jose) 来方便令牌的验证和解码。 ```sh npm install jose ``` ```ts import {createRemoteJWKSet, jwtVerify} from 'jose'; private async getJwksFunction() { const { jwksUri } = await this.getOidcConfig(); return createRemoteJWKSet(new URL(jwksUri))(); } private async verifyIdToken( idToken: string, clientId: string, issuer: string, ) { const jwks = await this.getJwksFunction(); const result = await jwtVerify(idToken, jwks, { audience: clientId, issuer }); if (Math.abs((result.payload.iat ?? 0) - Date.now() / 1000) > issuedAtTimeTolerance) { throw new Error('id_token.invalid_iat'); } return result; }; ``` ### 获取用户信息在成功的用户认证之后，可以从授权服务器颁发的 OIDC `id_token` 中获取基本的用户信息。然而，由于性能考虑，JWT 令牌的内容是有限的。为了获取更详细的用户个人资料信息，符合 OIDC 的授权服务器提供了一个开箱即用的用户信息端点。通过请求特定的用户个人资料作用域，这个端点允许你通过获取附加的用户个人资料数据。在调用令牌交换端点时，如果没有指明一个特定的 API 资源，授权服务器将默认地发出一个 opaque 类型的 `access_token`。这个 `access_token` 只能被用来访问用户信息端点，允许检索到基本的用户个人资料数据。 ```ts async getUserInfo() { const { userinfoEndpoint } = await this.getOidcConfig(); const accessToken = await this.getAccessToken(); return fetch(userinfoEndpoint, { headers: { Authorization: `Bearer ${accessToken}` } }); } ``` ### 获取受保护资源授权的 access token 在大多数情况下，客户端应用不仅需要用户认证，还需要用户授权访问某些受保护的资源或 API 端点。在这里，我们将使用在登录期间获得的 `refresh_token` 来获取特定于管理特定资源的 `access_token(s)`。这样我们就可以获得对那些受保护的 API 的访问权限。在用户登录期间，向授权服务器提供所有 API 资源指示器是非常关键的。经过成功的认证后，我们只可以检索到预先配置的指定资源的 `access_token`。为了实现这一点，在生成登录 URL 之前，需要预配置所有需要 API 资源指示器在客户端应用的配置设置中。 ```ts private async getAccessTokenByRefreshToken(resource?:string, scopes?: string[]){ const { appId } = this.logtoConfig; const { tokenEndpoint } = await this.getOidcConfig(); const { refreshToken } = await this.storage.getItem('refreshToken'); const parameters = new URLSearchParams({ 'grant_type': 'refresh_token', 'client_id': appId, 'refresh_token': }); if (resource) { parameters.append('resource', resource); } if (scopes?.length) { parameters.append('scope', scopes.join(' ')); } const response = await fetch(tokenEndpoint, { method: 'POST', grant_type: 'authorization_code', body: parameters, }); // 保存并替换最新返回的 refreshToken await this.storage.setItem('refreshToken', response.refreshToken); await this.accessTokenMap.setItem(`${resource}:${scopes.join(_)}`, response.accessToken); return response.accessToken; } async getAccessToken(resource?:string, scopes?: string[]) { if (!this.idToken) { throw new Error('User not authenticated'); } const accessTokenInStorage = this.accessTokenMap.getItem(`${resource}:${scopes.join(_)}`); if (accessTokenInStorage && accessTokenInStorage.expiresAt > Date.now() / 1000) { return accessToken.token; } return await this.getAccessTokenByRefreshToken(resource, scopes); } ``` ## 总结我们已经提供了客户端应用的用户认证和授权过程的基本方法实现。根据你的特定场景，你可以组织和优化 SDK 的逻辑。请注意，由于不同的平台和框架，可能会存在变化。对于更多的详细信息，请浏览 Logto 提供的 SDK 包。我们鼓励更多的用户参与到开发中来，并和我们进行讨论。你们的反馈和贡献对于我们提升和扩展 SDK 的能力有着极大的价值。 ## 附录 ### 保留的作用域 Logto 保留的作用域，你需要在初始 auth 请求中通过。这些作用域是 OIDC 保留的或者 Logto 保留的，用来完成一个成功的授权流程。 | 作用域名称 | 描述 | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | openid | 在成功认证后获得 `id_token` 所需的。 | | offline-access | 允许您的客户端应用在屏幕停止的情况下交换和续签 access_token 并保留 | `refresh_token`。 | | profile | 用于获取访问基本用户信息的权限 | ### Logto 配置 | 属性名称 | 类型 | 是否必填 | 描述 | 默认值 | | ------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | | appId | string | 是 | 唯一的应用标识符。由授权服务器生成以识别客户端应用。 | | | appSecret | string | | 应用程序的保密用于验证请求者的身份。机密客户端（如 Go web 或 Next.js web 应用）需要它，并且公共客户端（如原生应用或单页应用程序（SPA））可以选择它 | | endpoint | string | 是 | 授权服务器的根端点。此属性将被广泛用于生成授权请求的端点。 | | | scopes | string list | | 包含了用户可能需要被授予以访问任何给定的受保护资源的所有必要资源的作用域。 | [reservedScopes] | | resources | string list | | 用户可能请求访问的所有受保护资源指示器 | | ### 实用方法 #### generateRandomString ```ts const generateRandomString = (length = 64) => fromUint8Array(crypto.getRandomValues(new Uint8Array(length)), true); ``` 今天就试试 Logto Cloud 吧