配置知名的 OpenID Connect 提供程序
本文档介绍如何配置知名的社交 OIDC 和 OAuth2 提供商。
简介
如果使用 OpenID Connect 授权码流程 来保护 Quarkus 端点，则需要配置 Quarkus，告知它如何连接 OpenID Connect 提供商、如何向这些提供商进行身份验证、使用哪些范围等等。
有时，您需要使用配置来解决某些提供商未完全实现 OpenID Connect 的事实，或者实际上只是 OAuth2 提供商。
此类提供商的配置可能会变得复杂、非常技术性且难以理解。
引入了 quarkus.oidc.provider 配置属性来引用知名的 OpenID Connect 和 OAuth2 提供商。此属性可用于引用诸如 github 之类的提供商，只需最少的自定义，通常是帐户特定的 client id、client secret，并且必须设置一些属性才能完成配置。
如果需要配置多个提供商，则可以在 application.properties 中、在 多租户 设置中使用此属性（例如，请参阅 Quarkus Renarde 安全文档），在自定义 TenantConfigResolvers 中，如果动态创建租户配置。
知名提供商
Apple
要为 Apple 设置 OIDC，您需要创建一个开发者帐户，并注册 99 美元/年的计划，但您无法像大多数其他 OIDC 提供商那样在 localhost 上测试您的应用程序：您需要在 HTTPS 上运行它并使其公开访问，因此出于开发目的，您可能需要使用诸如 https://ngrok.com 之类的服务。
转到 创建新标识符，然后按 +
不要碰任何东西，保持 App IDs 选中，然后按 Continue
不要碰任何东西，保持 App 选中，然后按 Continue
输入描述和 Bundle ID（使用您的应用程序包名称）
然后向下滚动以找到 Sign in with Apple 功能，选择它，然后按 Continue
记下您的 App ID Prefix，然后按 Register
返回 Identifiers 页面，按 +
选择 Service IDs，然后按 Continue
输入描述和 Bundle ID（使用您的应用程序包名称），然后按 Continue
现在按 Register
返回服务列表，单击您新创建的服务
启用 Sign in with Apple，然后按 Configure
添加您的域名和返回 URL（设置为 <host>/apple），然后按 Next
现在按 Done
现在按 Continue
现在按 Save
转到左侧菜单上的 Keys 页面，然后按 +
填写密钥名称，启用 Sign in with Apple，然后按 Configure
选择您的 Primary App ID，然后按 Save
返回密钥页面，按 Continue
现在按 Register
记下您的 Key ID，下载您的密钥并将其保存到 Quarkus 应用程序的 src/main/resources/AuthKey_<KEYID>.p8 中
您现在可以配置您的 application.properties
quarkus.oidc.provider=apple
quarkus.oidc.client-id=<Bundle ID>
quarkus.oidc.credentials.jwt.key-file=AuthKey_<Key ID>.p8
quarkus.oidc.credentials.jwt.token-key-id=<Key ID>
quarkus.oidc.credentials.jwt.issuer=<App ID Prefix>
quarkus.oidc.credentials.jwt.subject=<Bundle ID}quarkus.oidc.provider=apple 将请求 Apple 将 openid、email 和 name 范围添加到颁发的访问令牌。有关覆盖这些范围或请求更多范围的信息，请参阅 提供商范围 部分。
Discord
创建一个 Discord 应用程序
现在您可以获取您的客户端 ID 和密钥
您现在可以配置您的 application.properties
quarkus.oidc.provider=discord
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret=<Client Secret>Facebook 不会让您像大多数其他 OIDC 提供商那样在 localhost 上测试您的应用程序：您需要在 HTTPS 上运行它并使其公开访问，因此出于开发目的，您可能需要使用诸如 https://ngrok.com 之类的服务。
要为 Facebook 设置 OIDC，请首先 创建应用程序，选择 Other 作为应用程序类型，然后单击 Next。
现在选择您的应用程序类型。对于本指南，选择 Consumer 并单击 Next，直到您到达下面的屏幕。现在输入应用程序名称和联系人电子邮件，然后按 Create app
在应用程序页面上，单击 Facebook login 产品上的 Set up
在 Quickstart 页面上，单击左侧菜单上的 Facebook login > Settings
首先单击 Get Advanced Access 将 public_profile 切换为高级访问。然后输入您的 Redirect URIs（设置为 <host>/facebook），然后按 Save changes
现在转到左侧菜单上的 Settings > Basic，并记下您的 App ID 和 App secret
您现在可以配置您的 application.properties
quarkus.oidc.provider=facebook
quarkus.oidc.client-id=<App ID>
quarkus.oidc.credentials.secret=<App secret>quarkus.oidc.provider=facebook 将请求 Facebook 将 email 和 public_profile 范围添加到颁发的访问令牌。有关覆盖这些范围或请求更多范围的信息，请参阅 提供商范围 部分。
GitHub
要为 GitHub 设置 OIDC，您需要在您的 GitHub 开发者设置 中创建一个新的 OAuth 应用程序
确保填写适当的详细信息，但更重要的是授权回调 URL，设置为 https://:8080/github（如果您打算使用 Quarkus 开发模式进行测试）。
现在单击 Register application，您将看到您的应用程序页面
您需要单击 Generate a new client secret，确认您的凭据，并记下您的 Client ID 和 Client secret（特别是那个，因为您以后将无法从该页面再次看到它，但您可以随时重新创建一个，所以不要太担心）
现在将以下配置添加到您的 application.properties
quarkus.oidc.provider=github
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>|
默认情况下，Quarkus GitHub 提供商在 HTTP Authorization 标头中提交客户端 ID 和密钥。但是，GitHub 可能要求客户端 ID 和密钥都作为表单参数提交。如果在登录 GitHub 并重定向回 Quarkus MCP 服务器后收到 HTTP 401 错误，请将 |
quarkus.oidc.provider=github 将请求 GitHub 将 user:email 范围添加到颁发的访问令牌。有关覆盖此范围或请求更多范围的信息，请参阅 提供商范围 部分。
您还可以将 GitHub 颁发的访问令牌发送到 quarkus.oidc.application-type=service 或 quarkus.oidc.application-type=hybrid Quarkus 应用程序。 |
要为 Google 设置 OIDC，您需要在您的 Google Cloud Platform 控制台 中创建一个新项目
选择一个项目名称，然后单击 CREATE。
现在确保您在顶部选择器中选择了您的项目，然后在左侧栏菜单上单击 APIs and Services > OAuth consent screen
选择 External 以授权任何 Google 用户登录您的应用程序，然后按 CREATE
现在您可以填写您的应用程序名称、您的支持电子邮件、您的开发者联系信息，然后按 SAVE AND CONTINUE
不要在下一页上添加任何范围，然后按 SAVE AND CONTINUE
不要在下一页上添加任何测试用户，然后按 SAVE AND CONTINUE
单击顶部菜单 CREATE CREDENTIALS > OAuth client ID
选择 Web application 作为 Application type，并在 Authorised redirect URIs 列表中添加 https://:8080/google，然后按 CREATE
复制您的 Client ID 和 Client Secret
您现在可以配置您的 application.properties
quarkus.oidc.provider=google
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>quarkus.oidc.provider=google 将请求 Google 将 openid、email 和 profile 范围添加到颁发的访问令牌。有关覆盖这些范围或请求更多范围的信息，请参阅 提供商范围 部分。
您还可以将 Google 颁发的访问令牌发送到 quarkus.oidc.application-type=service 或 quarkus.oidc.application-type=hybrid Quarkus 应用程序。 |
创建一个 LinkedIn 应用程序
添加 Sign In with LinkedIn using OpenId Connect 产品
现在您可以获取您的客户端 ID 和密钥。不要忘记也为您的应用程序添加授权的重定向 URL
您现在可以配置您的 application.properties
quarkus.oidc.provider=linkedin
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret=<Client Secret>Mastodon
创建一个 Mastodon 帐户。您必须 选择一个服务器，例如，mastodon.social。在您的帐户中选择 Development 选项并注册一个应用程序，例如
选择注册的应用程序
并记下其客户端 ID 和客户端密钥属性，使用它们来配置您的 application.properties
quarkus.oidc.provider=mastodon
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret.value=<Client Secret>默认情况下，quarkus.oidc.provider=mastodon 将 quarkus.oidc.auth-server-url 设置为 https://mastodon.social Mastodon 服务器地址。
如果您在另一个 Mastodon 服务器中创建了您的帐户，则可以覆盖 quarkus.oidc.auth-server-url，例如
quarkus.oidc.provider=mastodon
quarkus.oidc.auth-server-url=https://infosec.exchange
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret.value=<Client Secret>Microsoft
要为 Microsoft 设置 OIDC，您需要转到您的 Microsoft Azure Portal，并搜索 Microsoft Entra ID（以前称为 Azure Active Directory），然后单击它
进入后，在左侧的 Manage 下，单击 App registrations，然后单击 New registration
填写您的应用程序名称，选择 Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) 以允许任何人登录，并添加 Web 重定向 URI 作为 https://:8080/microsoft，然后单击 Register
在该结果页面上，复制 Client Id（在 Application (client) ID 下），然后单击 Add a certificate or secret
现在，在 Client secrets (0) 下，单击 New client secret
在该对话框中单击 Add，不要更改任何内容
在结果页面上，复制您的 Secret Value
您现在可以配置您的 application.properties
quarkus.oidc.provider=microsoft
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>quarkus.oidc.provider=microsoft 将请求 Microsoft 将 openid、email 和 profile 范围添加到颁发的访问令牌。有关覆盖这些范围或请求更多范围的信息，请参阅 提供商范围 部分。
您还可以将 Microsoft 颁发的访问令牌发送到 quarkus.oidc.application-type=service 或 quarkus.oidc.application-type=hybrid Quarkus 应用程序，但如果 Microsoft 颁发的访问令牌不是 JWT 格式，您可能需要将 quarkus.oidc.verify-access-token-with-user-info 配置属性设置为 true。 |
|
某些 Microsoft 服务可能会颁发令牌，只有在当前令牌的 |
Slack
创建一个 Slack 应用程序
选择应用程序名称、工作区并记住它，您稍后将需要它
请保存下一页上显示的客户端 ID 和密钥，您稍后将需要它们
配置重定向 URL。Slack 提供商需要 HTTPS 协议，出于开发目的，您可以使用 ngrok
您现在可以配置您的 application.properties
quarkus.oidc.provider=slack
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Client Secret>
quarkus.oidc.authentication.extra-params.team=quarkus-slack (1)| 1 | 使用 team 参数来引用您在 Slack OIDC 应用程序注册期间选择的工作区。 |
打开您的浏览器并导航到您的应用程序 https://<your ngrok 实例>.ngrok-free.app/。Quarkus 将在第一个请求中将您重定向到 Slack 提供商，您可以在其中授予所需的权限
Spotify
创建一个 Spotify 应用程序
不要忘记添加 https://:8080 作为开发期间测试的重定向 URI。完成 Spotify 应用程序设置后，您应该获得生成的客户端 ID 和密钥，例如
您现在可以配置您的 application.properties
quarkus.oidc.provider=spotify
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Client Secret>quarkus.oidc.provider=spotify 将请求 Spotify 将 user-read-private 和 user-read-email 范围添加到颁发的访问令牌。有关覆盖这些范围或请求更多范围的信息，请参阅 提供商范围 部分。
Strava
创建一个 Strava 应用程序
例如，将 Category 设置为 SocialMotivation，并将 ApplicationCallbackDomain 设置为 localhost 或 Ngrok 提供的域名，有关更多信息，请参阅 HTTPS 重定向 URI。
您现在可以配置您的 application.properties
quarkus.oidc.provider=strava
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret=<Client Secret>
# default value is '/strava'
quarkus.oidc.authentication.redirect-path=/fitness/welcome (1)| 1 | Strava 不强制要求作为授权码流程参数提供的重定向（回调）URI 等于在 Strava 应用程序中注册的 URI，因为它只需要配置 ApplicationCallbackDomain。例如，如果 ApplicationCallbackDomain 设置为 www.my-strava-example.com，Strava 将接受诸如 www.my-strava-example.com/a、www.my-strava-example.com/path/a 之类的重定向 URI，OAuth2 最佳安全实践不推荐这样做，有关更多信息，请参阅 Insufficient redirect_uri validation。因此，在使用 Strava 提供商时，您必须配置重定向路径，Quarkus 将强制要求当前请求路径与配置的 quarkus.oidc.authentication.redirect-path 值匹配，然后才能完成授权码流程。有关更多信息，请参阅 精确重定向 URI 匹配。 |
Twitch
创建一个 Twitch 应用程序
您现在可以配置您的 application.properties
quarkus.oidc.provider=twitch
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.client-secret.value=<Client Secret>X (原 Twitter)
您可以使用 X（原 Twitter）进行 OIDC 登录，但目前，它限制访问用户的电子邮件，这意味着您必须自己获取并验证它。
要为 X 设置 OIDC，首先 创建一个项目，输入项目名称，然后按 Next
输入用例，然后按 Next
输入项目描述，然后按 Next
现在输入应用程序名称，然后按 Next
记下您的密钥，因为它们不会再次显示，然后按 App Settings
导航到 User authentication settings 部分，然后按 Set up
选中 OAuth 2.0 复选框
选择 Web App 作为应用程序类型，然后填写您的应用程序详细信息（Callback URI 使用 <host>/_renarde/security/twitter-success）。
X 在实践中不需要 https 使用，但不会接受没有 https 的 Website URL，因此您仍然可以使用 ngrok。 |
现在按 Save
您现在可以复制您的 Client ID 和 Client Secret，然后按 Done
您现在可以配置您的 application.properties
quarkus.oidc.provider=x
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Client Secret>quarkus.oidc.provider=x 将请求 X 将 offline.access、tweet.read 和 users.read 范围添加到颁发的访问令牌。有关覆盖这些范围或请求更多范围的信息，请参阅 提供商范围 部分。
|
X 提供商需要代码交换的 Proof Key (PKCE)， 如果您更喜欢使用 |
|
X 是 Twitter 的新名称。您可以暂时继续使用 |
提供商范围
每个提供商声明都会请求一个或多个添加到给定提供商颁发的访问令牌中的令牌范围。例如，quarkus.oidc.provider=google 将请求 Google 添加 openid、email 和 profile 范围。
您可以使用 quarkus.oidc.authentication.scopes 属性覆盖这些范围，例如，如果您使用 Google 并且不想将 email 范围添加到访问令牌
quarkus.oidc.provider=google
quarkus.oidc.authentication.scopes=oidc,profile您可能还想在默认请求的范围之外添加一个或多个范围。例如，如果您想使用 Google 颁发的访问令牌来访问 Google Calendar 服务，您可以这样做
quarkus.oidc.provider=google
quarkus.oidc.authentication.extra-params.scope=https://www.googleapis.com/auth/calendar与使用 quarkus.oidc.authentication.scopes 添加新范围相比，这更简单，因为 quarkus.oidc.authentication.scopes 会覆盖提供商声明已经设置的范围，这就是为什么在这种情况下您需要列出所有必需的范围
quarkus.oidc.provider=google
quarkus.oidc.authentication.scopes=oidc,email,profile,https://www.googleapis.com/auth/calendar支持多个提供商
如果您想支持使用多个提供商对用户进行身份验证，则必须支持提供商特定的租户配置解析。
有关更多信息，请参阅 Quarkus 使用 OpenID Connect (OIDC) 多租户 指南。
使用令牌传播访问提供商服务
有时，仅使用社交提供商对用户进行身份验证是不够的。还需要访问提供商特定的服务，Quarkus OIDC web-app 应用程序才能代表当前经过身份验证的用户从提供商服务获取或更新数据。
正如在 保护 Web 应用程序的 OIDC 代码流程机制 指南中提到的，在授权码流程完成后，将返回 ID 和访问令牌，某些提供商（如 GitHub）仅返回访问令牌。正是这个访问令牌必须传播到诸如 Google Calendar 或 Spotify Playlists 之类的服务，以便当前经过身份验证的用户能够使用这些服务。
您不必引入提供商特定的库来实现此目的，而是可以使用反应式 Token Propagation 过滤器，该过滤器可以使用简单的注释绑定到给定的 REST 客户端。有关更多信息，请参阅 Quarkus 访问令牌传播 指南。
例如，在您配置了 Google 提供商之后，您可以使用 REST 客户端将事件添加到用户的 Google Calendar，如以下示例所示
package org.acme.calendar;
import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
import io.quarkus.oidc.token.propagation.common.AccessToken;
import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.Consumes;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@RegisterRestClient(configKey="google-calendar-api")
@AccessToken (1)
@Path("/calendars/primary")
public interface GoogleCalendarClient {
@POST
@Path("events")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
Uni<String> addEvent(Event event);
public static class Event {
public String summary;
public String kind = "calendar#event";
public Time start;
public Time end
}
public static class Time {
public String dateTime;
public String timeZone = "Europe/CET";
public Time() {
}
public Time(String value) {
dateTime = value;
}
}
}| 1 | @AccessToken 注释启用访问令牌传播到目标服务。 |
最后，您需要配置 Google Calendar 地址并请求访问令牌的 Google Calendar 范围，如以下示例所示
quarkus.oidc.provider=google
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
# Add a required calendar scope
quarkus.oidc.authentication.extra-params.scope=https://www.googleapis.com/auth/calendar
# Point REST client to Google Calendar endpoint
quarkus.rest-client.google-calendar-api.url=https://www.googleapis.com/calendar/v3现在您可以让用户使用 Google 进行身份验证，并支持代表他们更新他们的 Google 日历，例如
package org.acme.calendar;
import org.eclipse.microprofile.jwt.JsonWebToken;
import org.eclipse.microprofile.rest.client.inject.RestClient;
import io.quarkus.oidc.IdToken;
import io.quarkus.security.Authenticated;
import io.smallrye.mutiny.Uni;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
@Path("/calendar")
@Authenticated
public class CalendarService {
@Inject
@IdToken
JsonWebToken jwt;
@Inject
@RestClient
GoogleCalendarClient calendarClient;
@GET
@Path("/event")
@Produces("text/plain")
public Uni<String> get() {
return calendarClient.addEvent(new Event()).onItem()
.transform(c -> ("Hello " + jwt.getName() + ", new event: " + c));
}
}如果您想在本地主机上测试此端点，您必须更新在 Google 提供商处注册的应用程序，以将 https://:8080/calendar/event 列为授权的重定向 URI 之一，例如
您可能还必须注册一个或多个测试用户
如果端点必须访问其他 Google 服务，请遵循相同的方法。
使用给定提供商进行身份验证的模式，其中端点使用 ID 令牌或 UserInfo（尤其是如果使用仅 OAuth2 的提供商，如 GitHub）来获取有关当前经过身份验证的用户的一些信息，并使用访问令牌来访问一些下游服务（提供商或应用程序特定的服务）代表此用户可以普遍应用，无论使用哪个提供商来保护应用程序。
精确重定向 URI 匹配
除了 Strava 之外，大多数 OIDC 和 OAuth2 提供商都将强制要求只有当重定向 URI 精确匹配给定提供商仪表板中配置的重定向 URI 时，才能完成授权码流程。
从实际的角度来看，您的 Quarkus 端点很可能需要将 quarkus.oidc.authentication.redirect-path 相对路径属性设置为所有经过身份验证用户的初始入口路径，例如，quarkus.oidc.authentication.redirect-path=/authenticated，这意味着新经过身份验证的用户将登陆 /authenticated 页面，无论您的应用程序有多少个安全入口点以及他们最初访问了哪个安全资源。
这是许多 OIDC web-app 应用程序的典型流程。一旦用户登陆初始安全页面，您的应用程序就可以返回一个 HTML 页面，该页面使用链接来引导用户到应用程序的其他部分，或者可以借助 JAX-RS API 立即将用户重定向到其他应用程序资源。
如有必要，您可以配置 Quarkus 以在身份验证完成后恢复原始请求 URI。例如
quarkus.oidc.provider=strava (1)
quarkus.oidc.client-id=<Client ID>
quarkus.oidc.credentials.secret=<Secret>
quarkus.oidc.authentication.restore-path-after-redirect=true (2)| 1 | strava 提供商配置是唯一支持的配置，它使用 /strava 路径强制执行 quarkus.oidc.authentication.redirect-path 属性，您可以使用另一个路径（例如 /fitness）覆盖该路径。 |
| 2 | 如果用户在身份验证之前访问 /run 端点，那么一旦他们通过身份验证并重定向到配置的重定向路径（例如 /strava），他们将登陆原始请求 /run 路径。 |
您不必立即设置 quarkus.oidc.authentication.redirect-path，因为如果没有配置 quarkus.oidc.authentication.redirect-path，Quarkus 会假设当前请求 URL 是授权码流程重定向 URL。例如，要测试 Google 身份验证是否正常工作，您可以让 Quarkus 端点在 /google 上监听，并更新 Google 仪表板，以支持 https://:8080/google 重定向 URI。一旦您的安全应用程序 URL 空间增长，就需要设置 quarkus.oidc.authentication.redirect-path 属性。
速率限制
根据您的开发者 API 订阅级别，某些提供商可能会强制执行相当严格的请求速率限制策略。
当 Quarkus 从符合 OIDC 的提供商（如 Google 提供商）获取公共验证密钥并在本地使用这些密钥验证用户会话时，这可能不是问题。但是，对于纯 OAuth2 提供商，只有访问令牌可用，并且必须通过从提供商端点请求 UserInfo 来间接验证已通过身份验证的用户所做的每个请求，这可能会成为问题。
因此，UserInfo 嵌入在内部生成的 ID 令牌中，并在会话 cookie 中加密。您可以使用 quarkus.oidc.cache-user-info-in-idtoken=false 禁用它。
或者，使用默认或自定义 UserInfo 缓存提供程序，请参阅 "OpenID Connect (OIDC) Bearer token authentication" 指南的 令牌内省和 UserInfo 缓存 部分。
