[release-1.9] Rhidp 9758: Enable GitLab authentication

assemblies/assembly-enable-authentication-with-gitlab-basic.adoc

@@ -0,0 +1,8 @@
+:_mod-docs-content-type: ASSEMBLY
+
+[id="enable-authentication-with-gitlab-basic"]
+= Enable authentication with GitLab
+
+By configuring GitLab as an identity provider, you can enable users to authenticate with {product} and import your GitLab users and groups into the software catalog.
+
+include::modules/authentication/proc-enable-user-authentication-with-gitlab-basic.adoc[leveloffset=+1]

assemblies/assembly-enable-authentication.adoc

@@ -22,12 +22,12 @@ include::assembly-enable-authentication-with-github.adoc[leveloffset=+1]
 
 include::assembly-enable-authentication-with-azure.adoc[leveloffset=+1]
 
+include::assembly-enable-authentication-with-gitlab-basic.adoc[leveloffset=+1]
 
 include::assembly-enable-service-to-service-authentication.adoc[leveloffset=+1]
 
 
 include::modules/authentication/proc-enable-auto-logout-for-inactive-users.adoc[leveloffset=+1]
 
 
-include::assembly-troubleshoot-authentication-issues.adoc[leveloffset=+1]
-
+include::assembly-troubleshoot-authentication-issues.adoc[leveloffset=+1]

modules/authentication/proc-enable-user-authentication-with-gitlab-basic.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="enable-user-authentication-with-gilab-basic"]
+= Enable user authentication with GitLab
+
+[role="_abstract"]
+You can enable authentication with GitLab to allow users to sign in to {product-short} using their GitLab credentials. This integration also allows you to provision user and group data from GitLab to the {product-short} software catalog, enabling features that rely on synchronized user and group data. 
+
+.Prerequisites
+include::snip-enable-user-authentication-with-gitlab-common-prerequisites.adoc[]
+
+.Procedure
+include::snip-enable-user-authentication-with-gitlab-common-first-steps.adoc[]
+
+.Verification
+include::snip-enable-user-authentication-with-gitlab-common-verification.adoc[]

modules/authentication/proc-enabling-user-authentication-with-github-with-mandatory-steps.adoc

@@ -1,7 +1,7 @@
 :_mod-docs-content-type: PROCEDURE
 
 [id="enabling-user-authentication-with-github-with-mandatory-steps"]
-= Enabling user authentication with GitHub
+= Enable user authentication with GitHub
 
 [role="_abstract"]
 Authenticate users with GitHub by provisioning the users and groups from GitHub to the {product-short} software catalog, and configuring the GitHub authentication provider in {product}.

modules/authentication/snip-enable-user-authentication-with-gitlab-common-first-steps.adoc

@@ -0,0 +1,132 @@
+:_mod-docs-content-type: SNIPPET
+
+. Register GitLab OAuth 2 application to allow {product-very-short} to authenticate with GitLab. You must use the required callback URL and permissions.
+.. link:https://docs.gitlab.com/integration/oauth_provider/[Register a GitLab OAuth 2 application] using the following configuration:
++
+--
+GitLab OAuth 2 application name::
+Enter a unique name, such as `authenticating-with-rhdh-_<GUID>_`.
+
+Redirect URI::
+Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`.
+
+Authorization callback URL::
+Enter your authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/gitlab/handler/frame]`.
+
+Authorized application scope::
+Enable `email`, `profile`, `openid`, and `read_user`.
+--
+.. Save the application and record these values for the next step:
+
+* **OAuth 2 Client ID**, available in the *Application ID* field
+* **OAuth 2 Client secret**, accessible by selecting *Copy* in the *Secret* field
+
+. Add your GitLab credentials to {configuring-book-link}#provisioning-your-custom-configuration[your {product-very-short} secrets] using the following key/value pairs.
+Use these environment variables in your {product-very-short} configuration files.
+
+`GITLAB_HOST`::
+Enter your GitLab host: `<gitlab_host>`.
+
+`GITLAB_CLIENT_ID`::
+Enter the saved *OAuth 2 Client ID*.
+
+`GITLAB_CLIENT_SECRET`::
+Enter the saved *OAuth 2 Client Secret*.
+
+`GITLAB_URL`::
+Enter the GitLab host domain: _`<gitlab_host_domain>`_.
+
+`GITLAB_PARENT_ORG`::
+Enter your GitLab organization name, such as `_<your_gitlab_organization_name>_`.
+
+. Enable provisioning for GitLab users and groups to the {product-short} software catalog by adding the provider section to your {product-very-short} `{my-app-config-file}` file:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+catalog:
+  providers:
+    gitlab:
+      default:
+        host: $\{GITLAB_HOST}
+        orgEnabled: true
+        group: $\{GITLAB_PARENT_ORG}
+        relations:
+          - INHERITED
+          - DESCENDANTS
+          - SHARED_FROM_GROUPS
+        groupPattern: `[\s\S]*`
+        restrictUsersToGroup: true
+        includeUsersWithoutSeat: true
+        schedule:
+          initialDelay:
+            seconds: 0
+          frequency:
+            minutes: 50
+          timeout:
+            minutes: 50
+----
+
+`host`::
+Enter your GitLab instance address: pass:c,a,q[`${GITLAB_HOST}`].
+
+`orgEnabled`::
+Set to `true` to enable the ingestion of GitLab organizational data, such as users and groups. For the Gitlab site, you must also provide a value for the `group` parameter.
+
+`group`::
+Enter your configured link:https://docs.gitlab.com/user/group/[GitLab parent group]: `${GITLAB_PARENT_ORG}`.
+
+`relations`:: 
+Optional. Specify the types of group memberships to include during ingestion. You can use the following values:
+* `INHERITED`: Optional. Includes members of any ancestor groups as members of the current group.
+* `DESCENDANTS`: Optional. Includes members of any descendant groups as members of the current group.
+* `SHARED_FROM_GROUPS`: Optional. Includes members of any invited groups as members of the current group.
+
+`groupPattern`::
+Optional. Filters found groups based on provided pattern. Defaults to `[\s\S]*`, which means to not filter anything.
+
+`restrictUsersToGroup`::
+Set to `true` to ingest only users who are direct members of the configured group.
+
+`includeUsersWithoutSeat`::
+Set to `true` to include users who do not occupy a paid seat. This setting applies only to GitLab SaaS.
+
+`schedule.initialDelay`::
+Enter your schedule initial delay, in the ISO duration or "human duration" format.
+
+`schedule.frequency`::
+Enter your schedule frequency, in the cron, ISO duration, or "human duration" format.
+
+`schedule.timeout`::
+Enter your schedule timeout, in the ISO duration or "human duration" format.
+
+. Enable the GitLab authentication provider by adding the GitLab authentication provider section to your {product-very-short} `{my-app-config-file}` file:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+includeTransitiveGroupOwnership: true
+signInPage: gitlab
+auth:
+  environment: production
+  session:
+    secret: _<name_of_secret>_
+  providers:
+    gitlab:
+      production:
+        audience: https://${GITLAB_HOST}
+        clientId: $\{GITLAB_CLIENT_ID}
+        clientSecret: $\{GITLAB_CLIENT_SECRET}
+        callbackUrl: {my-product-url}/api/auth/gitlab/handler/frame
+----
++
+
+`audience`::
+Enter your GitLab instance address: `pass:c,a,q[https://${GITLAB_HOST}]`
+
+`clientId`::
+Enter the configured client ID: `${GITLAB_CLIENT_ID}`.
+
+`clientSecret`::
+Enter the configured secret variable name: `${GITLAB_CLIENT_SECRET}`.
+
+`callbackUrl`::
+Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/gitlab/handler/frame]`

modules/authentication/snip-enable-user-authentication-with-gitlab-common-prerequisites.adoc

@@ -0,0 +1,10 @@
+:_mod-docs-content-type: SNIPPET
+
+* You have enough permissions in GitLab to create and manage a link:https://docs.gitlab.com/api/oauth2/[GitLab OAuth 2 application].
++
+[TIP]
+====
+Alternatively, ask your GitLab administrator to prepare the required GitLab OAuth 2 application.
+====
+* You must create a GitLab personal access token with the `read_api` scope.
+* You have {configuring-book-link}[added a custom {product-short} application configuration], and have enough permissions to change it.

modules/authentication/snip-enable-user-authentication-with-gitlab-common-verification.adoc

@@ -0,0 +1,4 @@
+:_mod-docs-content-type: SNIPPET
+
+. Open {product-very-short} and wait for first ingestion.
+. Log in with your GitLab account.

modules/importing-repositories/proc-importing-multiple-repositories-from-gitlab.adoc

@@ -17,14 +17,31 @@ See: link:https://access.redhat.com/support/offerings/techpreview/[Technology Pr
 .Prerequisites
 * You have {configuring-dynamic-plugins-book-link}#bulk-importing-github-repositories[enabled the Bulk Import feature and given access to it].
 * You have set up a link:https://docs.gitlab.com/user/profile/personal_access_tokens/[GitLab personal access token (PAT)].
+* You configured the GitLab integration by adding the following section to your {product-very-short} `{my-app-config-file}` file:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+integrations:
+  gitlab:
+    - host: ${GITLAB_HOST}
+      token: ${GITLAB_TOKEN}
+----
+* You enabled the GitLab catalog provider plugin in your `dynamic-plugins.yaml` file to import GitLab users and groups:
++
+[source,yaml]
+----
+plugins:
+  - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-gitlab-org-dynamic'
+    disabled: false
+----
 
 .Procedure
-. Click *Bulk Import* in {product-short} left sidebar.
+. In the {product-short} left sidebar, click *Bulk Import*.
 . If your {product-very-short} instance has multiple source control tools configured, select GitLab as your *Source control tool* option.
 . Select the projects to import, and validate.
 +
 {product-short} creates a merge request in each selected project to add the required `catalog-info.yaml` file.
-. For each project to import, click on the *PR* link to review and merge the changes in Gitlab.
+. For each project to import, click the *PR* link to review and merge the changes in Gitlab.
 
 .Verification
 . Click *Bulk Import* in {product-short} left sidebar.