Getting started（入门指南）¶

The OpenID Connect 1.0 (OIDC) ↗ protocol is a simple identity layer on top of the OAuth 2.0 protocol. It allows clients like Foundry to verify the identity of the end-user and obtain basic user profile information.

:::callout{theme="warning"} Some OIDC providers are publicly available and allow any individual to create an account. Misconfiguration of public providers may grant unwanted users access to your enrollment. Proceed with caution. :::

Network egress¶

Egress calls are required for OIDC authentication and metadata collection. You can select an egress policy or configure a network egress policy.

OIDC concepts¶

The following section will outline the OIDC authentication concepts that are common in Foundry.

Redirect URL¶

The redirect URL needs to be registered with the OIDC provider. It allows the provider to communicate the result of the authorization request back to Foundry. The provider includes the redirect URL in the authorization request that is sent to the end-user, and the end-user is redirected to this URL during authorization. Foundry can then handle the response from the provider.

Logout URL¶

Foundry provides front-channel and back-channel URLs. Which logout URL is registered with the OIDC provider is dependent on desired logout behavior.

OIDC integration metadata¶

The OIDC integration metadata is the information about your identity provider that is passed to Foundry. Foundry can automatically fetch the required metadata fields if provided with the metadata discovery URI.

Alternatively, you can provide the required metadata manually. This information includes:

Issuer: This is the URL of the OIDC provider, which identifies the provider and its location. Foundry uses this URL to locate the OIDC discovery document, which among other things can specify the provider's OIDC endpoints, claims, supported scopes, and public keys.
Authorization endpoint: The provider's authorization endpoint, which is used to redirect the end-user to obtain an authorization code.
Token endpoint: This provider's token endpoint, which is used to exchange an authorization code for an access token and ID token.
JWKS URI: This is the URL of the provider's JSON Web Key Set (JWKS) document, which contains the public keys used to verify the signatures of the ID token.
User info endpoint (if applicable): The provider's user info endpoint, which is used to retrieve the end-user's profile information. This endpoint is not supported by all providers and is required by some providers that do support it.
End session endpoint (optional): The provider's end session endpoint, which is used to log the end-user out of the provider's session. This endpoint is optional and may not be supported by all providers.

Client credentials¶

The client credentials refer to the client ID and client secret that are issued by the OIDC provider to Foundry. These credentials are used by Foundry to authenticate to the provider and obtain access to the end-user's resources.

Obtaining these credentials differs across providers, so check your provider’s documentation.

Authentication method¶

Select how Foundry can authenticate requests to the token endpoint. The options are:

HTTP basic authentication scheme.
POST: Include credentials as form values in the request.

Scopes¶

OIDC scopes determine what information is included in the ID token and user info responses. Each scope returns a set of user attributes (i.e. claims).

The openid, email, and profile scopes must be included.

Email domains¶

These are the email domains associated with the configured authentication provider. These domains restrict who can log in with this provider and determine if a user is presented this provider as an option during login.

Supported hosts¶

Supported hosts are used to ensure the integration is only presented to users that log in using these hosts.

You can choose from the hosts configured for your enrollment.

Attribute mapping¶

Map the attributes defined in your identity provider to their representation in Foundry.

User attributes¶

User attributes, also called "claims", include fields such as name, email, and other available additional information. These attributes are sent in a map of attribute key to value or values, for example email → user@example.com.

For Foundry to have the correct values for user attributes, you must map identity provider attributes, also called "claims", to matching Foundry attributes. Foundry requires the following mappings:

ID: Set to sub by default. This value should always be present on OIDC assertions and has a static unique value.
Username: Set to preferred_username by default. You can change the value to a different human-readable attribute.
Email: Set to email by default. This should be mapped to the email attribute.
First name: Set to given_name by default. This should be mapped to the first name attribute.
Last name: Set to family_name by default. This should be mapped to the last name attribute.

You can create additional mappings to set more user attributes in Foundry by selecting Add attribute mapping. Input the attribute name in Foundry in the left field, and the path to claim in the JSON Web Token (JWT) in the right field.

For advanced usage, JSONPath syntax is supported to specify paths to claims in the JWT returned by your provider. By default, claim values will be extracted as a single string. Append [*] to the end of the path to extract the values individually. Example: groups could extract "[group1, group2]", whereas groups[*] would extract ["group1", "group2"].

Each mapping has a toggle in Foundry where you can choose the behavior when an attribute has multiple values in the OIDC response. The options are:

First: Populate the attribute with the first value received.
All: Populate the attribute with all the values received.

You can import user groups by selecting the Import user groups from the identity provider option and providing the appropriate path to claim in the JWT corresponding to the user group(s).

Advanced settings¶

Prompts (optional)¶

The prompt parameter is used to request that the user be prompted to perform a specific action during authentication. The possible values for the prompt parameter are:

none: no further user input is required for authentication.
login: users will be prompted to enter their credentials in order to be authenticated.
consent: users will be prompted to grant consent for authentication to be completed.
select_account: users will be prompted to select the account they want to use for authentication. This is typically used when users have multiple accounts with the same provider.

You can select multiple prompts. The default behavior if no prompts are selected depends on the provider.

Asynchronous user managers¶

Asynchronous user managers (AUMs) are configurable extra steps in the login flow. Expand Asynchronous user managers to view the available AUMs.

Creating a Login checkpoint redirects users at the time of login to a configurable prompt that asks for a justification before allowing the login to proceed. To enable a Login checkpoint, first toggle on the Checkpoints Login AUM, and then follow the steps to create a checkpoint.

中文翻译¶

入门指南¶

OpenID Connect 1.0 (OIDC) ↗ 协议是构建在 OAuth 2.0 协议之上的简单身份层。它允许 Foundry 等客户端验证终端用户的身份，并获取基本的用户资料信息。

:::callout{theme="warning"} 部分 OIDC 提供商是公开可用的，允许任何人创建账户。公开提供商的错误配置可能导致未经授权的用户访问您的注册环境。请谨慎操作。 :::

网络出站¶

OIDC 身份验证和元数据收集需要出站调用。您可以选择出站策略，或配置网络出站策略。

OIDC 概念¶

以下部分将概述 Foundry 中常见的 OIDC 身份验证概念。

重定向 URL¶

重定向 URL 需要在 OIDC 提供商处注册。它允许提供商将授权请求的结果传回 Foundry。提供商在发送给终端用户的授权请求中包含该重定向 URL，用户在授权过程中会被重定向至此 URL。随后 Foundry 可以处理来自提供商的响应。

注销 URL¶

Foundry 提供前端通道和后端通道 URL。向 OIDC 提供商注册哪个注销 URL 取决于所需的注销行为。

OIDC 集成元数据¶

OIDC 集成元数据是指传递给 Foundry 的关于身份提供商的信息。如果提供元数据发现 URI，Foundry 可以自动获取所需的元数据字段。

或者，您也可以手动提供所需的元数据。这些信息包括：

颁发者(Issuer)： OIDC 提供商的 URL，用于标识提供商及其位置。Foundry 使用此 URL 定位 OIDC 发现文档，该文档可指定提供商的 OIDC 端点、声明、支持的作用域和公钥等信息。
授权端点(Authorization endpoint)： 提供商的授权端点，用于重定向终端用户以获取授权码。
令牌端点(Token endpoint)： 提供商的令牌端点，用于将授权码交换为访问令牌和 ID 令牌。
JWKS URI： 提供商 JSON Web 密钥集(JWKS)文档的 URL，其中包含用于验证 ID 令牌签名的公钥。
用户信息端点(User info endpoint)（如适用）：提供商的用户信息端点，用于检索终端用户的资料信息。并非所有提供商都支持此端点，但部分支持的提供商要求使用。
结束会话端点(End session endpoint)（可选）：提供商的结束会话端点，用于将终端用户从提供商的会话中注销。此端点为可选功能，并非所有提供商都支持。

客户端凭据¶

客户端凭据是指 OIDC 提供商颁发给 Foundry 的客户端 ID 和客户端密钥。Foundry 使用这些凭据向提供商进行身份验证，并获取对终端用户资源的访问权限。

不同提供商获取这些凭据的方式有所不同，请查阅您的提供商文档。

身份验证方法¶

选择 Foundry 向令牌端点进行身份验证请求的方式。选项包括：

HTTP 基本身份验证方案。
POST：在请求中以表单值形式包含凭据。

作用域¶

OIDC 作用域决定 ID 令牌和用户信息响应中包含的信息。每个作用域返回一组用户属性（即声明）。

必须包含 openid、email 和 profile 作用域。

电子邮件域名¶

这些是与已配置的身份验证提供商关联的电子邮件域名。这些域名限制谁可以使用此提供商登录，并决定用户在登录时是否将此提供商作为选项呈现。

支持的主机¶

支持的主机用于确保集成仅呈现给使用这些主机登录的用户。

您可以从为注册环境配置的主机中进行选择。

属性映射¶

将身份提供商中定义的属性映射到 Foundry 中的对应表示。

用户属性¶

用户属性（也称为"声明"）包括姓名、电子邮件等字段以及其他可用的附加信息。这些属性以属性键到值的映射形式发送，例如 email → user@example.com。

为使 Foundry 获得正确的用户属性值，您必须将身份提供商属性（也称为"声明"）映射到匹配的 Foundry 属性。Foundry 需要以下映射：

ID： 默认设置为 sub。此值应始终存在于 OIDC 断言中，并具有静态唯一值。
用户名： 默认设置为 preferred_username。您可以将值更改为其他人类可读的属性。
电子邮件： 默认设置为 email。应映射到电子邮件属性。
名字： 默认设置为 given_name。应映射到名字属性。
姓氏： 默认设置为 family_name。应映射到姓氏属性。

您可以通过选择添加属性映射来创建其他映射，以在 Foundry 中设置更多用户属性。在左侧字段输入 Foundry 中的属性名称，在右侧字段输入 JSON Web 令牌(JWT)中的声明路径。

对于高级用法，支持使用 JSONPath 语法指定提供商返回的 JWT 中的声明路径。默认情况下，声明值将作为单个字符串提取。在路径末尾附加 [*] 可单独提取每个值。例如：groups 可提取 "[group1, group2]"，而 groups[*] 将提取 ["group1", "group2"]。

每个映射在 Foundry 中都有一个开关，您可以选择当属性在 OIDC 响应中包含多个值时的行为。选项包括：

第一个： 使用接收到的第一个值填充属性。
全部： 使用接收到的所有值填充属性。

您可以通过选择从身份提供商导入用户组选项，并提供 JWT 中与用户组对应的适当声明路径来导入用户组。

高级设置¶

提示（可选）¶

提示参数用于请求在身份验证过程中提示用户执行特定操作。提示参数的可能值包括：

none：身份验证无需进一步用户输入。
login：将提示用户输入凭据以完成身份验证。
consent：将提示用户授予同意以完成身份验证。
select_account：将提示用户选择要用于身份验证的账户。通常在用户与同一提供商拥有多个账户时使用。

您可以选择多个提示。如果未选择任何提示，默认行为取决于提供商。

异步用户管理器¶

异步用户管理器(AUM)是登录流程中可配置的额外步骤。展开异步用户管理器以查看可用的 AUM。

检查点登录¶

创建登录检查点会在用户登录时将其重定向到可配置的提示页面，要求提供理由后才能继续登录。要启用登录检查点，首先打开检查点登录 AUM 开关，然后按照步骤创建检查点。