From 0d6c9225dbb750860058adc50650a1115dd7d7a6 Mon Sep 17 00:00:00 2001 From: Joseph Snyder Date: Tue, 18 Apr 2023 09:27:57 -0400 Subject: [PATCH] Document pass_user_identities_to_ci_jwt usage Make the API documentation a bit more specific Add examples to the token payload display Add a small paragraph to the user profile preferences documentation. --- doc/api/users.md | 4 ++-- doc/ci/secrets/id_token_authentication.md | 5 +++++ doc/user/profile/preferences.md | 7 +++++++ lib/api/users.rb | 2 +- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/doc/api/users.md b/doc/api/users.md index a22930902092b4..4d6bdb260201a9 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Users API **(FREE)** -This documentation has information on API calls, parameters and responses for the Users API. +This documentation has information on API calls, parameters and responses for the Users API. For information on user activities that update the user event timestamps, see [get user activities](#get-user-activities). @@ -875,7 +875,7 @@ Parameters: | :------------------------------- | :------- | :--------------------------------------------------------------------------- | | `view_diffs_file_by_file` | Yes | Flag indicating the user sees only one file diff per page. | | `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. | -| `pass_user_identities_to_ci_jwt` | Yes | Flag indicating the user passes their external identities as CI information. This attribute does not contain enough information to identify or authorize the user in an external system. The attribute is internal to GitLab, and must not be passed to third-party services. | +| `pass_user_identities_to_ci_jwt` | Yes | Flag indicating the user passes their external identities as CI information. This attribute does not contain enough information to identify or authorize the user in an external system. The attribute is internal to GitLab, and must not be passed to third-party services. For more information and examples, see [Token Payload](../ci/secrets/id_token_authentication.md#token-payload). | ## User follow diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md index 1ff2a6efbcf97d..12e0402be25373 100644 --- a/doc/ci/secrets/id_token_authentication.md +++ b/doc/ci/secrets/id_token_authentication.md @@ -60,6 +60,7 @@ The token also includes custom claims provided by GitLab: | `user_id` | Always | ID of the user executing the job. | | `user_login` | Always | Username of the user executing the job. | | `user_email` | Always | Email of the user executing the job. | +| `user_identities` | User Preference setting | List of the user's external identities ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387537) in GitLab 16.0). | | `pipeline_id` | Always | ID of the pipeline. | | `pipeline_source` | Always | [Pipeline source](../jobs/job_control.md#common-if-clauses-for-rules). | | `job_id` | Always | ID of the job. | @@ -83,6 +84,10 @@ The token also includes custom claims provided by GitLab: "user_id": "1", "user_login": "sample-user", "user_email": "sample-user@example.com", + "user_identities": [ + {"provider": "github", "extern_uid": "2435223452345"}, + {"provider": "bitbucket", "extern_uid": "john.smith"}, + ], "pipeline_id": "574", "pipeline_source": "push", "job_id": "302", diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index da4d2da70fe031..e72113dc321054 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -182,6 +182,13 @@ NOTE: This feature is experimental, and choosing absolute times might break certain layouts. Open an issue if you notice that using absolute times breaks a layout. +## User identities in CI job JSON web tokens + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/387537) in GitLab 16.0. False by default. + +You can select to include the list of your external identities in the JSON Web Token information that is generated for a CI job. +For more information and examples, see [Token Payload](../../ci/secrets/id_token_authentication.md#token-payload). + ## Integrations Configure your preferences with third-party services which provide enhancements to your GitLab experience. diff --git a/lib/api/users.rb b/lib/api/users.rb index 505fcb2b38e8ec..13378181f243e7 100644 --- a/lib/api/users.rb +++ b/lib/api/users.rb @@ -1244,7 +1244,7 @@ def set_user_status(include_missing_params:) params do optional :view_diffs_file_by_file, type: Boolean, desc: 'Flag indicating the user sees only one file diff per page' optional :show_whitespace_in_diffs, type: Boolean, desc: 'Flag indicating the user sees whitespace changes in diffs' - optional :pass_user_identities_to_ci_jwt, type: Boolean, desc: 'Flag indicating the user passes their external identities as CI information' + optional :pass_user_identities_to_ci_jwt, type: Boolean, desc: 'Flag indicating the user passes their external identities to a CI job as part of a JSON web token.' at_least_one_of :view_diffs_file_by_file, :show_whitespace_in_diffs, :pass_user_identities_to_ci_jwt end put "preferences", feature_category: :user_profile, urgency: :high do -- GitLab