#配置 Identity Providers

Keycloak 可以将身份验证代理到外部 Identity Providers（IdP），允许用户使用来自 OIDC、SAML 或社交身份提供程序的现有账户登录。

有关身份联合的基础概念，请参阅 Identity Federation。

#添加 OpenID Connect Identity Provider

使用此操作步骤将任何符合 OIDC 的身份提供程序集成进来（例如 Microsoft Entra ID、Okta 或另一个 Keycloak 实例）。

ACCESS_TOKEN=$(curl -s -X POST \
  "https://<keycloak-host>/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=<admin-user>" \
  -d "password=<admin-password>" \
  -d "grant_type=password" | jq -r '.access_token')

curl -s -X POST \
  "https://<keycloak-host>/admin/realms/<realm>/identity-provider/instances" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "corporate-idp",
    "displayName": "Corporate SSO",
    "providerId": "oidc",
    "enabled": true,
    "config": {
      "authorizationUrl": "https://idp.example.com/authorize",
      "tokenUrl": "https://idp.example.com/token",
      "clientId": "<client-id>",
      "clientSecret": "<client-secret>",
      "defaultScope": "openid email profile"
    }
  }'

#添加 SAML Identity Provider

创建 SAML IdP 后，下载 Keycloak SP metadata，以便在外部 IdP 中注册：

https://<keycloak-host>/realms/<realm>/broker/<alias>/endpoint/descriptor

#添加 Social Identity Provider

Keycloak 为常见的社交身份提供程序提供了内置模板。每个提供程序的配置类似；差异仅在于特定于提供程序的 client registration。

#支持的 Social Providers

#示例：将 GitHub 添加为 Identity Provider

1. 在 GitHub 上注册一个新的 OAuth App：

   • Homepage URL: https://<keycloak-host>/realms/<realm>
   • Authorization callback URL: https://<keycloak-host>/realms/<realm>/broker/github/endpoint
   • 记录 Client ID 和 Client Secret。

2. 在 Keycloak Admin Console 中：

   • 转到 Identity providers > Add provider > GitHub。
   • 输入 GitHub OAuth App 中的 Client ID 和 Client Secret。
   • 点击 Save。

3. GitHub 登录按钮会显示在 Realm 登录页面上。

#IdP Mappers

IdP Mappers 控制来自外部 IdP 的用户属性和角色如何映射到 Keycloak 用户。

#添加 IdP Mapper

1. 在 IdP 详细视图中，点击 Mappers 选项卡。
2. 点击 Add mapper。
3. 选择一种 mapper 类型：

4. 配置源（IdP claim 或 attribute）和目标（Keycloak attribute 或 role）。
5. 点击 Save。

#首次登录流程

当用户首次通过外部 IdP 进行身份验证时，Keycloak 会执行 First Login Flow 来决定如何处理这个新身份。

#默认首次登录流程行为

1. Review Profile — 系统会提示用户审查并补全其个人资料。
2. Create User — 如果没有匹配的现有用户，则会创建一个新用户。
3. Link Existing Account — 如果已存在同一 email 的用户，则会提示用户链接账户。

#自定义首次登录流程

1. 转到 Authentication > Flows 选项卡。
2. 复制 First broker login flow。
3. 按需修改步骤：
   • 删除 Review Profile 以跳过个人资料审查步骤。
   • 添加条件，以便无需用户确认即可自动链接账户。
4. 在 IdP 配置中，将 First login flow 设置为你的自定义 flow。

#默认 Identity Provider

你可以配置一个 default IdP，使 Keycloak 登录页面自动重定向到外部 IdP，而不显示本地登录表单。

1. 转到 Authentication > Flows > Browser flow。
2. 添加一个 Identity Provider Redirector 步骤。
3. 在步骤配置中配置 Default Identity Provider。
4. 将该步骤的 requirement 设置为 Alternative。

另外，应用程序可以在 authorization request 中传递 kc_idp_hint query parameter 来建议使用某个 IdP：

https://<keycloak-host>/realms/<realm>/protocol/openid-connect/auth?
  client_id=my-app&
  redirect_uri=https://my-app.example.com/callback&
  response_type=code&
  kc_idp_hint=github

#Broker Logout

默认情况下，当用户从 Keycloak 注销时，与外部 IdP 的 session 不会终止。要启用级联注销：

1. 在 IdP 配置中，启用 Backchannel logout 或 Front-channel logout（取决于 IdP 支持情况）。
2. 确保外部 IdP 已配置为接受来自 Keycloak 的注销请求。