"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; const headings = [{ "data": { "id": "introduction", "hProperties": { "id": "introduction" } }, "depth": 2, "value": "Introduction" }, { "data": { "id": "but-first-what-and-why", "hProperties": { "id": "but-first-what-and-why" } }, "depth": 2, "value": "But first, what and why?" }, { "data": { "id": "integrate-an-oidc-server", "hProperties": { "id": "integrate-an-oidc-server" } }, "depth": 2, "value": "Integrate an OIDC server" }, { "data": { "id": "find-an-oidc-provider", "hProperties": { "id": "find-an-oidc-provider" } }, "depth": 3, "value": "Find an OIDC provider" }, { "data": { "id": "subject-client-and-audience", "hProperties": { "id": "subject-client-and-audience" } }, "depth": 3, "value": "Subject, client, and audience" }, { "data": { "id": "1-a-user-clicks-the-sign-in-button-on-a-web-application", "hProperties": { "id": "1-a-user-clicks-the-sign-in-button-on-a-web-application" } }, "depth": 4, "value": "1. A user clicks the sign-in button on a web application" }, { "data": { "id": "2-a-user-uses-a-single-page-application", "hProperties": { "id": "2-a-user-uses-a-single-page-application" } }, "depth": 4, "value": "2. A user uses a single-page application" }, { "data": { "id": "3-a-machine-to-machine-communication", "hProperties": { "id": "3-a-machine-to-machine-communication" } }, "depth": 4, "value": "3. A machine-to-machine communication" }, { "data": { "id": "recap", "hProperties": { "id": "recap" } }, "depth": 4, "value": "Recap" }, { "data": { "id": "tokens", "hProperties": { "id": "tokens" } }, "depth": 3, "value": "Tokens" }, { "data": { "id": "multiple-audiences", "hProperties": { "id": "multiple-audiences" } }, "depth": 3, "value": "Multiple audiences" }, { "data": { "id": "specify-resource-in-the-code-exchange-request", "hProperties": { "id": "specify-resource-in-the-code-exchange-request" } }, "depth": 4, "value": "Specify resource in the code exchange request" }, { "data": { "id": "use-a-refresh-token-to-get-a-new-access-token", "hProperties": { "id": "use-a-refresh-token-to-get-a-new-access-token" } }, "depth": 4, "value": "Use a refresh token to get a new access token" }, { "data": { "id": "client-credentials-grant", "hProperties": { "id": "client-credentials-grant" } }, "depth": 4, "value": "Client credentials grant" }, { "data": { "id": "protect-your-api-service", "hProperties": { "id": "protect-your-api-service" } }, "depth": 3, "value": "Protect your API service" }, { "data": { "id": "assert-claims", "hProperties": { "id": "assert-claims" } }, "depth": 4, "value": "Assert claims" }, { "data": { "id": "authorization", "hProperties": { "id": "authorization" } }, "depth": 2, "value": "Authorization" }, { "data": { "id": "closing-notes", "hProperties": { "id": "closing-notes" } }, "depth": 2, "value": "Closing notes" }]; const readingTime = { "minutes": 8, "words": 2328, "text": "8 min read" }; const frontmatter = undefined; function _createMdxContent(props) { const _components = { a: "a", blockquote: "blockquote", code: "code", em: "em", h2: "h2", h3: "h3", h4: "h4", li: "li", p: "p", pre: "pre", span: "span", strong: "strong", ul: "ul", ..._provideComponents(), ...props.components }, {Info, LogtoCloudButton, Note} = _components; if (!Info) _missingMdxReference("Info", true); if (!LogtoCloudButton) _missingMdxReference("LogtoCloudButton", true); if (!Note) _missingMdxReference("Note", true); return _jsxs(_Fragment, { children: [_jsxs(_components.h2, { id: "introduction", children: ["Introduction", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#introduction", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "You may encounter a situation where you need a centralized authentication and authorization system, a.k.a. identity access management (IAM) or identity provider (IdP). Sometimes people will append a word to designate the business, such as Customer IAM and Workforce IAM." }), "\n", _jsx(_components.p, { children: "Let's set aside these fancy names for a moment. The need for IAM could arise because your application is growing, or you plan to delegate the hard work to a vendor from the start. Nevertheless, you are reaching a point where an identity system will need to be introduced to your project." }), "\n", _jsx(_components.p, { children: "Considering the popularity of OAuth 2.0, OpenID Connect (OIDC) is a natural choice for many developers. Since OIDC is an authentication layer built on top of OAuth 2.0, you may feel familiar when you start to work with OIDC. Let's get started!" }), "\n", _jsxs(_components.h2, { id: "but-first-what-and-why", children: ["But first, what and why?", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#but-first-what-and-why", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.blockquote, { children: ["\n", _jsx(_components.p, { children: "Feel free to skip this section if you are already familiar with the concept of identity provider and the importance of it." }), "\n"] }), "\n", _jsxs(_components.p, { children: ["An OIDC server, or identity provider, is a centralized system that manages user authentication and authorization. As we discussed in ", _jsx(_components.a, { href: "https://blog.logto.io/centralized-identity-system", children: "Why you need a centralized identity system for a multi-app business" }), ", a centralized identity system has many benefits."] }), "\n", _jsx(_components.p, { children: "Let's say your project starts with a simple web application, and it has authentication built-in:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "graph LR\n A[User] --> B[Web application]\n" }) }), "\n", _jsx(_components.p, { children: "As your project grows, you need to introduce a mobile version:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "graph LR\n A[User] --> B[Web application]\n A --> C[Mobile application]\n" }) }), "\n", _jsx(_components.p, { children: "It'll be bad experience for users if they need to create an account for each application. Since you started with a web application, you let the mobile application communicate with the web application for authentication:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "graph LR\n A[User] --> B[Web application]\n A --> C[Mobile application]\n C --> B\n" }) }), "\n", _jsx(_components.p, { children: "Now, a new API service is being introduced. Since it's a service for paid users, you need to make sure the user is authenticated and authorized to access the service. To achieve this, you can proxy the service through the web application:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "graph LR\n A[User] --> B[Web application]\n A --> C[Mobile application]\n C --> B\n B --> D[API service]\n" }) }), "\n", _jsx(_components.p, { children: "Or, use some token technique to authenticate the user, and validate the token by talking to the web application in the service. Therefore the mobile application can use the service directly:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "graph LR\n A[User] --> B[Web application]\n A --> C[Mobile application]\n C --> B\n B <--> D[API service]\n C --> D\n" }) }), "\n", _jsx(_components.p, { children: "Things are getting messy. So you decide to split the authentication and authorization logic into a separate service:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "graph LR\n A[User] --> B[Web application]\n A --> C[Mobile application]\n B --> D[API service]\n C --> D\n B --> E[Identity service] \n C --> E\n D --> E \n\n subgraph Applications\n B\n C\n end\n\n subgraph Services\n D\n end\n\n subgraph Identity\n E\n end\n" }) }), "\n", _jsx(_components.p, { children: "The refactoring process can be painful. You may notice that the complexity of it will increase exponentially as you add more applications and services to the project. Even worse, you may need to maintain multiple authentication methods such as passwordless sign-in, social login, SAML, etc." }), "\n", _jsx(_components.p, { children: "This is why we'd better introduce an identity provider at the beginning when you have a plan to scale your project." }), "\n", _jsx(Note, { children: _jsx(_components.p, { children: "Of course, there are some cases where the project is simple enough and you know it will keep simple for a while. You can leave this article and come back when you need it." }) }), "\n", _jsxs(_components.h2, { id: "integrate-an-oidc-server", children: ["Integrate an OIDC server", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#integrate-an-oidc-server", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.h3, { id: "find-an-oidc-provider", children: ["Find an OIDC provider", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#find-an-oidc-provider", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "There are many OIDC providers available in the market. You can choose one based on your requirements and preferences. As long as the provider is OIDC compliant, it will play the same role in your project." }), "\n", _jsx(Info, { children: _jsxs(_components.p, { children: [_jsx(_components.a, { href: "https://logto.io", children: "Logto" }), " is an open-source OIDC provider with out-of-the-box identity and access management features."] }) }), "\n", _jsxs(_components.h3, { id: "subject-client-and-audience", children: ["Subject, client, and audience", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#subject-client-and-audience", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["To simplify the concept, we can think of the ", _jsx(_components.em, { children: "subject" }), " is the entity that is requesting access to an ", _jsx(_components.em, { children: "audience" }), " via a ", _jsx(_components.em, { children: "client" }), "."] }), "\n", _jsx(Note, { title: "I can't see audience (aud) in the token", children: _jsx(_components.p, { children: "When audience is missing, usually it means the audience is the OIDC server itself." }) }), "\n", _jsx(_components.p, { children: "Let's see some typical scenarios:" }), "\n", _jsxs(_components.h4, { id: "1-a-user-clicks-the-sign-in-button-on-a-web-application", children: ["1. A user clicks the sign-in button on a web application", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#1-a-user-clicks-the-sign-in-button-on-a-web-application", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "In a traditional and server-side rendering web application, the frontend and backend are coupled. Let's say the web application serves both frontend and backend:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Subject" }), ": The user"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Audience" }), ": The OIDC server"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Client" }), ": The web application"] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["It may looks counter-intuitive that the audience is the OIDC server. In fact, it is the key to realize the SSO (Single Sign-On) experience for end-users. Let's see a simplified sequence diagram for ", _jsx(_components.a, { href: "https://blog.logto.io/implicit-flow-is-dead#how-authorization-code-flow-works", children: "authorization code flow" }), ":"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n participant User as User
(subject)\n participant App1 as WebApp 1
(client)\n participant App2 as WebApp 2
(client)\n participant OIDC as OIDC server
(audience)\n\n User ->> App1: Click sign-in\n App1 ->> OIDC: Redirect
(authorization request)\n OIDC ->> User: Show sign-in page\n User ->> OIDC: Sign-in\n OIDC ->> App1: Redirect with `code`\n App1 ->> OIDC: Exchange tokens using `code`\n Note over User: Drink a cup of coffee\n User ->> App2: Click sign-in\n App2 ->> OIDC: Redirect\n OIDC ->> OIDC: Valid session found\n OIDC ->> App2: Redirect with `code`\n App2 ->> OIDC: Exchange tokens using `code`\n" }) }), "\n", _jsxs(_components.p, { children: [_jsx(_components.code, { children: "code" }), " is a one-time code that can be exchanged for various tokens, such as access token, ID token, and refresh token. It's OK if you don't understand all these tokens at this moment. As we move forward, you'll get a better understanding of them."] }), "\n", _jsx(_components.p, { children: "In the above case, the user doesn't need to sign in again when they switch to another application because the user (subject) has already authenticated with the OIDC server (audience)." }), "\n", _jsxs(_components.h4, { id: "2-a-user-uses-a-single-page-application", children: ["2. A user uses a single-page application", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#2-a-user-uses-a-single-page-application", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "In a single-page application (or a mobile application), the frontend and backend are separated. Let's say the backend is an API service:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Subject" }), ": The user"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Audience" }), ": The API service"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Client" }), ": The single-page application (SPA)"] }), "\n"] }), "\n", _jsx(_components.p, { children: "A simplified sequence diagram with authorization code flow:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n participant User as User
(subject)\n participant SPA as Single-page application
(client)\n participant API as API service
(audience)\n participant OIDC as OIDC server
(audience)\n\n User ->> SPA: Click sign-in\n SPA ->> OIDC: Redirect
(authorization request)\n OIDC ->> User: Show sign-in page\n User ->> OIDC: Sign-in\n OIDC ->> SPA: Redirect with `code`\n SPA ->> OIDC: Exchange tokens using `code`\n User ->> SPA: Try to view a protected page\n SPA ->> API: Request data with access token\n API ->> OIDC: Validate access token\n OIDC ->> API: OK\n API ->> SPA: Response data\n" }) }), "\n", _jsxs(_components.p, { children: ["Since the API service is non-interactive, the SPA needs to use the access token with the API service as the audience (the ", _jsx(_components.code, { children: "aud" }), " in the token)."] }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Why the OIDC server is still an audience?" }) }), "\n", _jsx(_components.p, { children: "Technically, you can remove the OIDC server from the audience list. Since in most cases, you'll need the user information from the OIDC server (which requires the OIDC server to be the audience), it's better to always include the OIDC server in the audience list when it involves user interaction." }), "\n", _jsx(_components.p, { children: _jsx(_components.strong, { children: "Wait, you are saying that we can have multiple audiences in an authorization request?" }) }), "\n", _jsxs(_components.p, { children: ["Exactly! Remember that OIDC is built on top of OAuth 2.0, it is possible to leverage ", _jsx(_components.a, { href: "https://datatracker.ietf.org/doc/html/rfc8707", children: "RFC 8707: Resource Indicators for OAuth 2.0" }), " in the authorization request to specify multiple audiences. It requires the support from both the grant and the OIDC server. ", _jsx(_components.a, { href: "https://logto.io", children: "Logto" }), " supports this feature natively."] }), "\n", _jsxs(_components.h4, { id: "3-a-machine-to-machine-communication", children: ["3. A machine-to-machine communication", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#3-a-machine-to-machine-communication", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Let's say you have a service A that needs to call service B:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Subject" }), ": Service A"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Audience" }), ": Service B"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Client" }), ": Service A"] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["A simplified sequence diagram with ", _jsx(_components.a, { href: "https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4", children: "client credentials grant" }), ":"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n participant ServiceA as Service A
(subject and client)\n participant ServiceB as Service B
(audience)\n participant OIDC as OIDC server\n\n ServiceA ->> OIDC: Request access token
with client credentials (token request)\n OIDC ->> ServiceA: Access token\n ServiceA ->> ServiceB: Request data with access token\n ServiceB ->> OIDC: Validate access token\n OIDC ->> ServiceB: OK\n ServiceB ->> ServiceA: Response data\n" }) }), "\n", _jsx(_components.p, { children: "When service B needs to call service A, the roles are simply swapped." }), "\n", _jsxs(_components.h4, { id: "recap", children: ["Recap", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#recap", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Subject" }), ": It can be a user, a service, or any entity that needs to access the audience."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Client" }), ": It can be a web application, a mobile application, or any entity that initiates the request or acts on behalf of the subject."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Audience" }), ": It can be a service, an API, or any entity that provides access to the subject."] }), "\n"] }), "\n", _jsxs(_components.h3, { id: "tokens", children: ["Tokens", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#tokens", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "There are three types of tokens you may encounter when working with OIDC:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Access token" }), ": It is used to access the audience. It can be a JWT (JSON Web Token) or an opaque token (usually a random string)."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "ID token" }), ": An OIDC-specific token that contains user information. It is always a JWT. The client can decode the token to get user information."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Refresh token" }), ": It is used to get a new set of tokens when the access token or ID token expires."] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["For a detailed explanation of these tokens, you can refer to ", _jsx(_components.a, { href: "https://blog.logto.io/understanding-tokens-in-oidc", children: "Understanding refresh tokens, access tokens, and ID tokens in OIDC protocol" }), "."] }), "\n", _jsxs(_components.p, { children: ["In above scenario 1 and 2, the term ", _jsx(_components.em, { children: "authorization request" }), " refers to a request to get a set of tokens via a specific ", _jsx(_components.em, { children: "grant" }), "."] }), "\n", _jsx(Note, { children: _jsxs(_components.p, { children: ["While the OAuth 2.0 RFC uses the term ", _jsx(_components.em, { children: "grant" }), ", in practice, people often use the term ", _jsx(_components.em, { children: "flow" }), " to describe a more generic, end-to-end process."] }) }), "\n", _jsxs(_components.p, { children: ["When everything goes well, a set of tokens will be returned in the \"Exchange tokens using ", _jsx(_components.code, { children: "code" }), "\" step. The available tokens in the set depend on multiple factors, especially the ", _jsx(_components.code, { children: "scope" }), " parameter in the authorization request. For the sake of simplicity, we'll assume all tokens are returned in the set. Once the access token expires, the client can use the refresh token to get a new set of tokens without user interaction."] }), "\n", _jsx(_components.p, { children: "For scenario 3, it is simpler because the client credentials grant only returns an access token." }), "\n", _jsxs(_components.h3, { id: "multiple-audiences", children: ["Multiple audiences", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#multiple-audiences", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "You may notice that only one access token is returned at a time. How could we handle the case where the client needs to access multiple audiences?" }), "\n", _jsx(_components.p, { children: "There are two common solutions:" }), "\n", _jsxs(_components.h4, { id: "specify-resource-in-the-code-exchange-request", children: ["Specify ", _jsx(_components.code, { children: "resource" }), " in the code exchange request", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#specify-resource-in-the-code-exchange-request", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["When the client exchanges the code for tokens, it can specify a ", _jsx(_components.code, { children: "resource" }), " parameter in the request. The OIDC server will return an access token for the specified audience if applicable."] }), "\n", _jsx(_components.p, { children: "Here's a non-normative example:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-http", children: "POST /token HTTP/1.1\nHost: oidc-server.example.com\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=authorization_code\n&code=AUTHORIZATION_CODE\n&client_id=CLIENT_ID\n&client_secret=CLIENT_SECRET\n&resource=API_SERVICE\n" }) }), "\n", _jsxs(_components.p, { children: ["Then the OIDC server will return an access token for the ", _jsx(_components.code, { children: "API_SERVICE" }), " audience, if applicable."] }), "\n", _jsxs(_components.h4, { id: "use-a-refresh-token-to-get-a-new-access-token", children: ["Use a refresh token to get a new access token", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#use-a-refresh-token-to-get-a-new-access-token", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["With RFC 8707, the client can even specify multiple audiences by using the ", _jsx(_components.code, { children: "resource" }), " parameter multiple times. Now, if refresh tokens is available in the client, the client may specify the audience in the ", _jsx(_components.code, { children: "resource" }), " parameter when refreshing the token."] }), "\n", _jsx(_components.p, { children: "Here's a non-normative example:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-http", children: "POST /token HTTP/1.1\nHost: oidc-server.example.com\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=refresh_token\n&refresh_token=REFRESH_TOKEN\n&client_id=CLIENT_ID\n&client_secret=CLIENT_SECRET\n&resource=API_SERVICE\n" }) }), "\n", _jsx(_components.p, { children: "It has the same effect as the previous solution. Meanwhile, other granted audiences are still available in future token requests." }), "\n", _jsxs(_components.h4, { id: "client-credentials-grant", children: ["Client credentials grant", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#client-credentials-grant", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["You can also use the ", _jsx(_components.code, { children: "resource" }), " parameter in the client credentials grant to specify the audience. There's no issue with multiple audiences in this grant because you can always request a new access token for a different audience by simply sending another token request."] }), "\n", _jsxs(_components.h3, { id: "protect-your-api-service", children: ["Protect your API service", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#protect-your-api-service", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "The \"API service\" in scenario 2 and the \"Service B\" in scenario 3 have one thing in common: they need to validate the access token to determine if the request is authorized. Depending on the format of the access token, the validation process may vary." }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Opaque token" }), ": The API service needs to call the OIDC server to validate the token. An ", _jsx(_components.a, { href: "https://blog.logto.io/oauth2-token-introspection", children: "introspection endpoint" }), " is usually provided by the OIDC server for this purpose."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "JWT" }), ": The API service can validate the token locally by checking the signature and the claims in the token. The OIDC server usually provides a ", _jsx(_components.a, { href: "https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata", children: "JSON Web Key Set (JWKS) endpoint" }), " (", _jsx(_components.code, { children: "jwks_uri" }), ") for the API service to get the public key to verify the signature."] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["If you are new to JWT, you can refer to ", _jsx(_components.a, { href: "https://blog.logto.io/what-is-jwt", children: "What is JSON Web Token (JWT)?" }), ". In fact, usually there's no need to validate the signature and assert the claims manually because there are many libraries that can do it for you, such as ", _jsx(_components.a, { href: "https://github.com/panva/jose", children: "jose" }), " for Node.js and web browsers."] }), "\n", _jsxs(_components.h4, { id: "assert-claims", children: ["Assert claims", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#assert-claims", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "In addition to validating the JWT signature, the API service should always check the claims in the token:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "iss" }), ": The issuer of the token. It should match the OIDC server's issuer URL."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "aud" }), ": The audience of the token. It should match the API service's audience value (usually a valid URI)."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "exp" }), ": The expiration time of the token. The API service should reject the token if it's expired."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "scope" }), ": The scopes (permissions) of the token. The API service should check if the required scope is present in the token."] }), "\n"] }), "\n", _jsxs(_components.p, { children: ["Other claims, such as ", _jsx(_components.code, { children: "sub" }), " (subject) and ", _jsx(_components.code, { children: "iat" }), " (issued at), are also important in some cases. If you have additional security measures, check the claims accordingly."] }), "\n", _jsxs(_components.h2, { id: "authorization", children: ["Authorization", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#authorization", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["An unanswered question remains out there: How do we determine if a ", _jsx(_components.em, { children: "scope" }), " (i.e. permission) can be granted to a subject?"] }), "\n", _jsx(_components.p, { children: "The single question leads to a whole new world of authorization, which is out of the scope of this article. In short, there are some common approaches like RBAC (Role-Based Access Control) and ABAC (Attribute-Based Access Control). Here are some resources to get you started:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://blog.logto.io/rbac-and-abac", children: "RBAC and ABAC: The access control models you should know" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://blog.logto.io/mastering-rbac", children: "Mastering RBAC in Logto: A Comprehensive Real-World Example" }) }), "\n"] }), "\n", _jsxs(_components.h2, { id: "closing-notes", children: ["Closing notes", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#closing-notes", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Introducing an OIDC server into your project is a big step. It can significantly improve the security and scalability of your project. Meanwhile, it may take some time to understand the concepts and the interactions between components." }), "\n", _jsx(_components.p, { children: "Choosing a good OIDC provider that fits your requirements and preferences can notably reduce the complexity of the integration process, as the provider usually offers the whole package, including the OIDC server, authorization mechanisms, SDKs, and the enterprise features you may need in the future." }), "\n", _jsxs(_components.p, { children: ["I hope this guide helps you understand the basics of integrating an OIDC server. If you are looking for one to start with, I would selfishly recommend ", _jsx(_components.a, { href: "https://logto.io", children: "Logto" }), ", our identity infrastructure for developers."] }), "\n", _jsx(LogtoCloudButton, {})] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { headings, readingTime, frontmatter, default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }