From a6487ae56e4baf5b59874190a81762a78ef98439 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 5 Sep 2025 08:18:41 +0800 Subject: [PATCH 1/3] add docing not standard tpl --- ...non_standard_OIDC_service_field_mapping.md | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md diff --git a/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md b/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md new file mode 100644 index 00000000..3b66c27a --- /dev/null +++ b/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md @@ -0,0 +1,28 @@ +--- +products: + - Alauda Container Platform +kind: + - Solution +--- + +# \[Solution name\] + +## Issue + +Specify the problem(s) this solution addresses or applicable scenarios. Required field. + +## Environment + +Describe the platform version and the corresponding plugin version. Required field. + +## Resolution + +Describe the specific solution to address this scenario or problem.Required field. + +## Root Cause + +Root cause of this issue. Optional field. + +## Diagnostic Steps + +What are the specific diagnostic steps for this issue, and how can I confirm if there are related problems in my environment? Optional filed. \ No newline at end of file From dc52b6e40af71396df76464a35a9f1d434a75f77 Mon Sep 17 00:00:00 2001 From: Administrator Date: Fri, 5 Sep 2025 16:00:48 +0800 Subject: [PATCH 2/3] add docking non standard oidc --- ...non_standard_OIDC_service_field_mapping.md | 109 +++++++++++++++++- 1 file changed, 103 insertions(+), 6 deletions(-) diff --git a/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md b/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md index 3b66c27a..e3fdc622 100644 --- a/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md +++ b/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md @@ -5,24 +5,121 @@ kind: - Solution --- -# \[Solution name\] +# Docking Non-standard OIDC Service Field Mapping ## Issue -Specify the problem(s) this solution addresses or applicable scenarios. Required field. +When integrating third-party OIDC (OpenID Connect) services, authentication callback failures are frequently encountered, with the error message typically being: + +`Internal error occurred: failed to authenticate: missing email claim, not found \"email\" key` + +**Common error messages:** + +- missing "email" claim: Missing email field +- missing "email_verified" claim: Missing email verification field +- missing "name" claim: Missing name field ## Environment -Describe the platform version and the corresponding plugin version. Required field. +- 4.x +- 3.x ## Resolution -Describe the specific solution to address this scenario or problem.Required field. +The platform provides a field mapping feature to handle these non-standard situations. + +### For Platform Version 4.x + +1. Navigate to Administrator → Users → IDP → Click to enter OIDC integration details → Click Update on the right side of Actions → Switch to YAML view + +2. Configure field mapping in the YAML: + +```yaml +spec: + config: + # Other configurations + # If the Provider cannot provide the email_verified field, the email verification check can be skipped. + insecureSkipEmailVerified: true + + # Use other fields as the display name; the default is the name field. + userNameKey: display_name + + # If the provider's /.well-known/openid-configuration provides a userinfo_endpoint, the UserInfo endpoint query can be enabled. + getUserInfo: true + + # Field Mapping Configuration + claimMapping: + # If the provider cannot provide the email field, 'sub' can be used as a substitute. + # In addition to the sub field, other fields that can uniquely represent a user globally may also be used. + # Default email + email: sub + + # If the provider uses 'user_groups' instead of 'groups' + # Default groups + groups: user_groups + + # If the provider uses 'mobile' instead of 'phone' + phone: mobile +``` + +3. After updating the field mappings in the IDP configuration, users can attempt to log in again using OIDC. + +For detailed documentation related to version 4.x, please refer to: [https://docs.alauda.io/container_platform/4.1/security/users_and_roles/idp/functions/oidc_manage.html](https://docs.alauda.io/container_platform/4.1/security/users_and_roles/idp/functions/oidc_manage.html) + +### For Platform Version 3.x + +1. Execute the following commands in the global cluster: + +```bash +# Retrieve the connected provider(s). +kubectl get connectors -n cpaas-system + +# Edit connector information +kubectl edit connector -n cpaas-system +``` + +2. Decode the value of the config field using Base64. + +The configuration information of the Provider will be displayed in JSON format. At this point, you can update the configuration in the JSON according to the field configuration of version 4.x. Finally, encode the information in base64 and update it to the connector resource. + +After updating the Connector configuration, you can use OIDC to log in to the platform again. ## Root Cause -Root cause of this issue. Optional field. +The root cause of this type of issue is that the ID Token returned by the third-party OIDC service lacks standard mandatory fields, preventing the system from correctly parsing user information. + +ID Tokens contain standard claims that assert which client app logged the user in, when the token expires, and the identity of the user. + +**Standard ID Token example:** + +```json +{ + "iss": "http://127.0.0.1:5556/dex", + "sub": "CgcyMzQyNzQ5EgZnaXRodWI", + "aud": "example-app", + "exp": 1492882042, + "iat": 1492795642, + "at_hash": "bi96gOXZShvlWYtal9Eqiw", + "email": "jane.doe@coreos.com", + "email_verified": true, + "groups": [ + "admins", + "developers" + ], + "name": "Jane Doe" +} +``` + +**Required fields:** +- sub: Unique identifier of the user (required) +- email: User email (usually mandatory) +- email_verified: Whether the email has been verified (usually mandatory) +- name: User name ## Diagnostic Steps -What are the specific diagnostic steps for this issue, and how can I confirm if there are related problems in my environment? Optional filed. \ No newline at end of file +1. **Check the ID Token content**: You can use an online JWT decoding tool (such as [https://jwt.io](https://jwt.io)) to view the actual content of the ID Token and understand which fields the OIDC service provides. + +2. **Consult the IDP provider**: To map the required fields, consult the IDP provider's operations personnel to determine which fields were provided during authorization. + +3. **Verify authentication flow**: Test the OIDC authentication process to identify specific missing claims in the error messages. \ No newline at end of file From 17cc1ec1014f09f5c08d73b4cb9b9f9ea46002dd Mon Sep 17 00:00:00 2001 From: Administrator Date: Fri, 5 Sep 2025 16:26:12 +0800 Subject: [PATCH 3/3] estructure OIDC field mapping solution documentation --- ..._mapping.md => OIDC_field_mapping_configuration.md} | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) rename docs/en/solutions/{Docking_non_standard_OIDC_service_field_mapping.md => OIDC_field_mapping_configuration.md} (94%) diff --git a/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md b/docs/en/solutions/OIDC_field_mapping_configuration.md similarity index 94% rename from docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md rename to docs/en/solutions/OIDC_field_mapping_configuration.md index e3fdc622..e2282ee2 100644 --- a/docs/en/solutions/Docking_non_standard_OIDC_service_field_mapping.md +++ b/docs/en/solutions/OIDC_field_mapping_configuration.md @@ -5,7 +5,7 @@ kind: - Solution --- -# Docking Non-standard OIDC Service Field Mapping +# OIDC Field Mapping Configuration ## Issue @@ -13,6 +13,8 @@ When integrating third-party OIDC (OpenID Connect) services, authentication call `Internal error occurred: failed to authenticate: missing email claim, not found \"email\" key` +The platform requests the default scopes `profile` and `email` during OIDC authentication. However, some third-party OIDC providers may not return standard fields in the expected format. + **Common error messages:** - missing "email" claim: Missing email field @@ -110,12 +112,6 @@ ID Tokens contain standard claims that assert which client app logged the user i } ``` -**Required fields:** -- sub: Unique identifier of the user (required) -- email: User email (usually mandatory) -- email_verified: Whether the email has been verified (usually mandatory) -- name: User name - ## Diagnostic Steps 1. **Check the ID Token content**: You can use an online JWT decoding tool (such as [https://jwt.io](https://jwt.io)) to view the actual content of the ID Token and understand which fields the OIDC service provides.