支持开发者门户单点登录
API7 开发者门户支持单点登录(SSO),允许用户通过组织的身份提供方(IdP)验证身份,提供流畅、安全的登录体验,提升易用性和安全性。
通常不建议为外部开发者使用 SSO,因为这要求他们在组织的 IdP 中拥有账号。开发者门户的 SSO 配置独立于 API7 控制台的 SSO 配置,后者用于登录控制台并管理网关配置、API 提供方等 API7 企业版设置。
创建登录选项
API7 开发者门户支持使用多种协议实现单点登录(SSO)。通过集成现有用户系统,内部开发者无需创建新账号即可访问 API7 开发者门户。
- LDAP
- OIDC
- SAML
IdP 配置
定义目录结构,规划 Base DN 和组织单位(OU)。例如以下配置。
# Base DN 为 dc=example,dc=com
# 根条目
dn: dc=example,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
o: Example Company
dc: example
# LDAP 管理员账号(用作绑定 DN)
dn: cn=read-only-admin,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: read-only-admin
sn: Admin
uid: read-only-admin
userPassword:: e1NTSEF9JGFsdGhvdmVyJGFsdGhvdmVy
mail: admin@example.com
# 用户账号
dn: uid=alice,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
uid: alice
cn: Alice Johnson
sn: Johnson
mail: alice.johnson@example.com
telephoneNumber: 555-123-4567
dn: uid=bob,dc=example,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
uid: bob
cn: Bob Smith
sn: Smith
mail: bob.smith@example.com
telephoneNumber: 555-234-5678
# 组条目
dn: ou=admins,dc=example,dc=com
objectClass: top
objectClass: groupOfUniqueNames
ou: admins
cn: Admins
uniqueMember: uid=alice,dc=example,dc=com
uniqueMember: uid=bob,dc=example,dc=com
API7 开发者门户配置
- 在顶部导航栏选择组织,然后选择设置。
- 点击新增登录选项。
- 填写配置。
- 名称应为唯一且便于用户识别的登录名称。例如,将名称配置为
Employee Account时,控制台登录页会显示使用 Employee Account 登录选项。 - 提供方选择
LDAP。 - 主机填写 LDAP 主机域名,例如
ldap.example.com。 - 端口填写 LDAP 服务器端口,例如
389(不使用 SSL)或636(使用 SSL)。 - Base DN是定义 LDAP 目录树搜索起点的根可分辨名称,例如
dc=example,dc=com。 - 绑定 DN是执行 LDAP 用户搜索所用的可分辨名称,例如
cn=read-only-admin,dc=example,dc=com。该账号必须有权读取或搜索待认证用户。 - 绑定密码是 LDAP 客户端连接 LDAP 服务器时,以绑定 DN(用户账号)验证身份所用的凭据。
- 标识符是用于标识 LDAP 用户的属性,例如
uid。 - 属性映射用于将 API7 用户字段映射到 LDAP 属性。例如以下映射。
- username:
uid - email:
mail - name:
cn
- username:
- 点击新增。
IdP 配置
本节介绍 Keycloak 26.3.3 中的配置。如果使用其他版本的 Keycloak 或其他身份提供方(IdP),请参考对应 IdP 文档调整配置。
- 创建 Realm,例如
quickstart-realm。 - 创建客户端,例如
apisix-quickstart-client,并完成以下配置。- 启用客户端身份认证,将访问类型设为机密。
- 启用标准流程(授权码授权)。
- 配置重定向 URL,例如
*。 - 创建客户端后,前往凭据选项卡获取客户端密钥,并记录此值以供后续使用。
- 创建用户,并完成以下配置。
- 创建用户密码。
- 根据需要配置用户邮箱、名字和姓氏。
- 在 Realm 设置中找到发现文档链接,在发现文档中记录以下值以供后续使用。
issuerURL,例如http://192.168.10.101:8080/realms/quickstart-realm。end_session_endpointURL,例如http://192.168.10.101:8080/realms/quickstart-realm/protocol/openid-connect/logout。
API7 开发者门户配置
- 在顶部导航栏选择组织,然后选择设置。
- 点击新增登录选项。
- 填写配置。
- 名称应为唯一且便于用户识别的登录名称。例如,将名称配置为
Employee Account时,控制台登录页会显示使用 Employee Account 登录选项。 - 提供方选择
OIDC。 - 签发者填写 OpenID Connect 提供方的签发者 URL,例如
http://192.168.10.101:8080/realms/quickstart-realm。 - 客户端 ID填写 OIDC 提供方分配给应用的唯一标识符,例如
apisix-quickstart-client。 - 客户端密钥填写 OIDC 提供方分配的身份认证密钥。
- 请求作用域填写向 OIDC 提供方请求的作用域,用于定义访问级别及 Token 中包含的声明。所有 OIDC 请求都必须包含
openid作用域。可以根据需要添加其他作用域,使用空格分隔,例如openid profile email。 - 根 URL填写用户访问 API7 开发者门户的根地址,例如
https://api7-portal.your-company.com。此 URL 必须与用户在浏览器中输入的地址完全一致,包括协议(HTTP 或 HTTPS),以及非标准端口(80 或 443 以外)的端口号。- 回调 URL 将自动生成为
<Root_URL>/api/oidc/<LOGIN_OPTION_ID>/callback。
- 回调 URL 将自动生成为
- SSL 验证用于指定是否验证 OIDC 提供方的 SSL/TLS 证书。
- 登出 URL用于结束用户会话,并将用户重定向到登录页。应使用
end_session_endpointURL,并将post_logout_redirect_uri查询参数设为 API7 开发者门户 URL,例如http://192.168.10.101:8080/realms/quickstart-realm/protocol/openid-connect/logout?post_logout_redirect_uri=https://api7-portal.your-company.com. - 属性映射用于将 API7 用户字段映射到 OIDC 声明。例如以下映射。
- username:
preferred_username - email:
email - name:
name
- username:
- 点击新增。
IdP 配置
本节介绍 Microsoft Entra ID(Azure AD)中的配置。如果使用其他身份提供方(IdP),请参考对应 IdP 文档调整配置。
- 在 Azure 门户中,前往 Microsoft Entra ID。
- 创建企业应用程序,选择创建自己的应用程序。
- 填写应用程序名称,例如
API7。 - 选择集成在库中找不到的任何其他应用程序(非库) 选项。
- 填写应用程序名称,例如
- 在应用程序中选择用户和组选项卡,添加所有需要的用户和组。只有已添加的用户和组才能通过 SSO 登录 API7。
- 在应用程序中前往单一登录选项卡,启用 SAML,然后查找应用程序的以下信息。
- 应用联合元数据 URL用于提供 SAML 配置详情,例如
https://login.microsoftonline.com/<TENANT_ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP_ID>。 - 声明名称是 SAML Token 中用户属性的唯一标识符,用于将身份提供方的数据映射到服务提供方的对应字段。查找 username 和 email 的声明名称,例如
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name和http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress。
- 应用联合元数据 URL用于提供 SAML 配置详情,例如
- 完成下方的 API7 开发者门户配置,后续配置需要使用 API7 中的信息。
- 在应用程序中前往单一登录选项卡,编辑基本 SAML 配置。
- 标识符(实体 ID) 用于唯一标识 SAML 联合中的特定实体。此标识符必须唯一,且在 API7 与 IdP 中保持一致。建议使用 API7 开发者门户 URL,例如
https://api7-portal.your-company.com,也可以使用其他唯一字符串。 - 回复 URL(断言使用者服务 URL) 是服务提供方的端点,用于在用户成功登录后接收身份提供方发送的 SAML 身份认证响应,例如
https://api7-portal.your-company.com/api/saml/<LOGIN_OPTION_ID>/acs。
- 标识符(实体 ID) 用于唯一标识 SAML 联合中的特定实体。此标识符必须唯一,且在 API7 与 IdP 中保持一致。建议使用 API7 开发者门户 URL,例如
配置现已完成,开发者应可以通过新登录选项登录 API7 开发者门户。
API7 开发者门户配置
- 在顶部导航栏选择组织,然后选择设置。
- 点击新增登录选项。
- 填写配置。
- 名称应为唯一且便于用户识别的登录名称。例如,将名称配置为
Employee Account时,控制台登录页会显示使用 Employee Account 登录选项。 - 提供方选择
SAML。 - 身份提供方元数据 URL填写身份提供方的元数据 URL,例如
https://login.microsoftonline.com/<TENANT_ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<APP_ID>。 - 服务提供方根 URL填写服务提供方的根 URL,通常为 API7 开发者门户地址,例如
https://api7-portal.your-company.com。 - 实体 ID用于唯一标识 SAML 联合中的特定实体。此标识符必须唯一,且在 API7 与 IdP 中保持一致。建议使用 API7 开发者门户 URL,例如
https://api7-portal.your-company.com,也可以使用其他唯一字符串。 - 属性映射用于将 API7 用户字段映射到 SAML 声明。例如以下映射。
- username:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name - email:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress - name:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
- username:
- 登出时终止 IdP 会话可按需启用。
- 点击新增。
- 在新增的 SAML 登录选项中找到服务提供方 ACS URL,例如
https://api7-portal.your-company.com/api/saml/<LOGIN_OPTION_ID>/acs。 - 返回上方 IdP 配置的第 6 步。
开发者门户登录页现在应显示新的登录选项,用户可以通过 IdP 验证身份。
从 IdP 同步开发者数据
SCIM(跨域身份管理系统)是一种将身份提供方(IdP)的用户和组信息同步到 API7 开发者门户的协议。它免去了跨多个系统手动管理用户和组的工作,节省时间并降低出错风险。
启用 SCIM 预配后,当 IdP 注册或删除用户时,API7 开发者门户会自动同步用户数据。
- 在顶部导航栏选择组织,然后选择设置。
- 启用 SCIM 预配。
- 复制
API7 SCIM 端点 URL和SCIM Token。 - 如果 IdP 支持 SCIM,请在其中配置 SCIM。
删除开发者登录选项
注意
删除登录选项会移除开发者门户中与该选项关联的所有用户。
- 在顶部导航栏选择组织,然后选择用户。
- 检查是否仍有用户使用此登录选项。如有,请在变更前通知他们。
- 在顶部导航栏选择组织,然后选择设置。
- 点击目标登录选项的删除。
相关阅读
- 关键概念