使用 OpenID Connect 配置 SSO

兼容性

此功能与其他经过 OpenID Connect 认证的平台兼容，目前经过测试且确认支持的平台：

• Microsoft Entra
• Okta Identity Platform
• auth0

添加并配置客户端应用

根据您使用的 OpenID Connect 服务提供商，通常需要在该服务提供商中添加并配置某种应用或整合。如需更多信息，请查阅您所使用提供商的 OpenID Connect 文档。下面是使用 auth0 配置 OpenID Connect 的指南。

1. 注册 auth0 账号并创建 tenant
2. 进入你的 tenant，选择 Applications -> Applications -> Create Application，输入你的应用名，选择“Regular Web Application”，创建 OIDC 应用。
   
3. 设置你的网站 OpenID Connect 插件。选择刚创建的应用，点击 Settings 标签页，domain 并加上 https:// 前缀，复制到“授权服务器 URL”，Client ID 复制到“客户端 ID”，Client Secret 复制到 “客户端密钥”。
   
4. 在 User Management -> Users 创建用户，在 User Management -> Roles 创建角色，必须创建一个管理员角色（例如：Supervisors），并创建一个用户属于此角色。此用户将映射到 Limyee CMS 管理员，用于管理网站。
5. 要映射用户的角色，需要添加 Action，选择 Action -> Triggers -> Sign Up & Login -> post-login -> Create Action -> Create Custom Action，输入名称后，点击 Create
6. 输入设置自定义声明的代码，代码中的声明名称（group）将 OpenID Connect 插件的映射设置的组（角色）声明一致。注意不要使用系统保留的关键字。
   

   exports.onExecutePostLogin = async (event, api) => {
     if (event.authorization) {
       api.idToken.setCustomClaim('group', event.authorization.roles);
       api.accessToken.setCustomClaim('group', event.authorization.roles);
     }
   };

7. 然后点击 Deploy 并返回 Post Login Triggers，将刚创建的 trigger 拖拽到 Strart 和 Complete 之间，然后点击 Apply。
8. 添加以下代码到 OpenID Connect 插件的映射配置中，用于映射管理员到网站。
   

   {
     "roleMappings":[
           { "source":"Supervisors","destination":"Administrators" }
     ]
   }

回调 URL

当配置应用程序时，您需要指定相应的回调 URL。

配置 OpenID Connect 插件

您可以通过进入系统管理->认证->身份验证方法，然后选择“OpenID Connect 单点登录”找到 OpenID Connect 插件。建议您先配置所需的属性并保存，然后再选择“启用”选项。否则，您的网站认证流程将立即被替换，您可能需要使用应急管理登录来进一步配置该插件。

授权选项

网站选项

映射

高级配置文件与角色映射

您可使用映射选项，在用户创建并登录时，将声明信息映射到自定义配置文件字段，并将角色关联至用户（如需要）。该功能采用特定的JSON格式进行定义。在决定使用此功能时，需注意以下几点重要事项。

• 如果使用 SCIM 用户配置管理，建议不要使用此功能，因为 SCIM 本身已设计用于处理此类功能。虽然两者可以共用，但存在潜在冲突风险。
• 在定义配置文件字段时，请使用唯一键。您可以映射到现有的配置文件字段，但用户输入的值可能在登录时被覆盖。
• 请将OpenID Connect的自定义配置文件字段集中到各自的配置文件字段组中。这样在网站用户界面添加时，可将其设为只读状态，因为配置文件字段现在由OpenID Connect提供程序管理，不应被修改。

了解JSON结构

配置对象包含以下三个属性：

{
  "claimMappings": [],
  "roleMappings":[],
  "onCreateOnly":false
}

声明映射 （claimMappings）

有两种方式可以映射声明、系统字段或自定义配置文件字段。系统字段是您站点中的常量字段，而配置文件字段则可根据您的站点进行特定配置。您可以映射任何简单值字段，例如字符串，或包含简单值的数组，例如字符串列表。

claimMappings 包括以下字段：

{
    "mapsTo": {  },
    "claims": [],
    "format": ""
}

映射系统字段

当前支持的系统字段如下：

• displayName:  网站用户的显示名称。

在定义系统字段时，会在 mapsTo 字段中添加以下 JSON 格式：

"mapsTo": { "systemField": "displayName" }

“systemField” 属性是唯一所需的内容，且必须符合上述定义的预设系统字段ID。

自定义个人资料字段

当不使用系统字段时，您可以指定自定义配置文件字段。如果该配置文件字段已存在，则其值由 OpenID Connect 提供程序管理；如果不存在，则在首次尝试写入值时自动创建。

"mapsTo": {"profileField":{"key": "profilrField_key", "label": "FieldLabel","fieldType": "Plain Text","searchable": true } }

• key:  该值用作配置字段的键。它会映射到一个已有的字段，如果不存在则创建一个新的字段。
• label:  用于创建新字段时的字段标签。它决定了用户界面中该字段的显示方式。
• fieldType:  配置文件字段的类型。数组字段支持“纯文本”和“逗号分隔列表”。
• searchable: 定义该字段是否可在网站中进行搜索。

声明属性

您可以为“mapsTo”字段指定一个或多个声明。当指定了多个声明时，若未指定格式，则这些值将按在“mapsTo”字段中定义的顺序用空格连接。此外，当适当指定时，声明也可以是字符串数组。

"claims": [ {"name": "first_name" }, { "name": "emails, "type":"array","delimiter":"," }]

• name:  令牌中显示的声明名称。它始终是必需的。
• type: 如果声明值是一个字符串数组，请指定 'array'
• delimiter:  仅对数组类型有效，这是用于连接数组值的分隔符。默认值为逗号（','）。

简单的单值声明。

{ "name": "first_name" }

值为字符串数组的声明。

{ "name": "groups","type":"array", "delimiter":","}

格式化

您可以使用格式属性来选择声明值的显示方式。该属性是一个静态字符串，其中包含以 {claimName} 格式化的占位符，而 claimName 是在声明区域中定义的名称。当指定多个声明时，此格式非常有用。占位符将被其对应的声明值替换，但数组会根据声明定义中的分隔符方式进行显示。  

单值格式

"format":"My name is {first_name}"

多值格式

"format":"{last_name}, {first_name}"

限制字段更新的时间

您可以为单个映射对象指定“onCreateOnly”属性。当该值为 true 时，配置文件数据仅在创建账户时应用。默认情况下此值为 false，表示数据将在创建账户和每次登录时应用。

{
    "mapsTo": {  },
    "claims": [],
    "format": "",
    "onCreateOnly":true
}

角色映射

您可以在“roleMappings”中定义用户如何映射到特定角色，该字段是一个包含以下属性的映射对象数组

• source:  这是身份提供者所呈现的角色名称。当未指定目标且该角色不存在时，将自动创建。
• destination:  您的站点中角色的名称。当指定时，将把源角色的成员添加到目标角色中。如果目标角色不存在，则会创建该角色。（可选）
• onCreateOnly:  如果为 true，角色仅在创建账户时应用。默认情况下此值为 false，表示角色将在创建账户和每次登录时应用。

"roleMappings":[
        { "source":"siteMembershipAdmins","destination":"CustomRole" },
        { "source":"Group 2", "destination":null,"onCreateOnly":true }
  ]