Merge branch 'main' into RHIDP-3974-managing-authorization-using-the-Web-UI

Gerry-Forde · web-flow · commit e91cfd219cbd · 2024-11-04T17:05:18.000Z
diff --git a/.github/workflows/build-asciidoc.yml b/.github/workflows/build-asciidoc.yml
@@ -17,7 +17,7 @@ name: GitHub Pages
 
 on:
   push:
-    branches: 
+    branches:
     - main
     - rhdh-1.**
     - 1.**.x
@@ -41,14 +41,14 @@ jobs:
       run: |
         # update
         sudo apt-get update -y || true
-        # install 
-        sudo apt-get -y -q install asciidoctor && asciidoctor --version
+        # install
+        sudo apt-get -y -q install podman && podman --version
         echo "GIT_BRANCH=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}" >> $GITHUB_ENV
 
     - name: Build guides and indexes
       run: |
         echo "Building branch ${{ env.GIT_BRANCH }}"
-        build/scripts/build.sh -b ${{ env.GIT_BRANCH }}
+        build/scripts/build-ccutil.sh -b ${{ env.GIT_BRANCH }}
 
     # repo must be public for this to work
     - name: Deploy
@@ -60,7 +60,7 @@ jobs:
         keep_files: true
         publish_dir: ./titles-generated
 
-    - name: Cleanup merged PR branches 
+    - name: Cleanup merged PR branches
       run: |
         PULL_URL="https://api.github.com/repos/redhat-developer/red-hat-developers-documentation-rhdh/pulls"
         GITHUB_TOKEN="${{ secrets.RHDH_BOT_TOKEN }}"
@@ -70,7 +70,7 @@ jobs:
         git checkout gh-pages; git pull || true
         dirs=$(find . -maxdepth 1 -name "pr-*" -type d | sed -r -e "s|^\./pr-||")
         refs=$(cat pulls.html | grep pr- | sed -r -e "s|.+.html>pr-([0-9]+)</a>.+|\1|")
-        for d in $(echo -e "$dirs\n$refs" | sort -uV); do 
+        for d in $(echo -e "$dirs\n$refs" | sort -uV); do
           PR="${d}"
           echo -n "Check merge status of PR $PR ... "
           PR_JSON=$(curl -sSL -H "Accept: application/vnd.github+json" -H "Authorization: Bearer $GITHUB_TOKEN" "$PULL_URL/$PR")
diff --git a/assemblies/assembly-authenticating-with-github.adoc b/assemblies/assembly-authenticating-with-github.adoc
@@ -1,5 +1,5 @@
-[id="assembly-auth-provider-github"]
-= Enabling the GitHub authentication provider
+[id="authenticating-with-github"]
+= Authenticating with GitHub
 
 To authenticate users with GitHub or GitHub Enterprise:
 
diff --git a/assemblies/assembly-configuring-authorization-in-rhdh.adoc b/assemblies/assembly-configuring-authorization-in-rhdh.adoc
@@ -1,7 +1,33 @@
 [id='configuring-authorization-in-rhdh']
 = Configuring authorization in {product}
 
-include::modules/authorization/con-rbac-overview.adoc[leveloffset=+1]
+In link:{authorization-book-url}[{authentication-book-title}], you learnt how to authenticate users to {product}.
+{product-short} knowns who the users are.
+
+In this book, learn how to authorize users to perform actions in {product-short}.
+Define what users can do in {product-short}.
+
+Role-Based Access Control (RBAC) is a security concept that controls access to resources in a system, and specifies a mapping between users of the system, and the actions they can perform on resources in the system.
+You define roles with specific permissions, and then assign the roles to users and groups.
+
+RBAC on {product-short} is built on top of the Permissions framework, which defines RBAC policies in code.
+Rather than defining policies in code,
+the {product-short} RBAC feature allows you
+to define policies in a declarative fashion using a simple CSV based format.
+You can define the policies by using {product-short} web interface or REST API, rather than editing the CSV directly.
+
+To apply RBAC in {product-short}:
+
+. The {product-short} administrator sets up the RBAC feature:
+.. Enable the RBAC feature
+.. Configure Policy Administrators
+
+. The {product-short} policy administrator configures your RBAC policies:
+.. Define roles with specific permissions
+.. Assign the roles to users and groups
+
+
+include::modules/authorization/proc-enabling-the-rbac-plugin.adoc[leveloffset=+1]
 
 
 include::assembly-managing-authorizations-by-using-the-rhdh-web-ui.adoc[leveloffset=+1]
@@ -13,9 +39,6 @@ include::modules/authorization/ref-rbac-permission-policies.adoc[leveloffset=+1]
 include::modules/authorization/con-rbac-config-permission-policies.adoc[leveloffset=+2]
 
 
-include::modules/authorization/con-rbac-config-permission-policies-admin.adoc[leveloffset=+3]
-
-
 include::modules/authorization/con-rbac-config-permission-policies-external-file.adoc[leveloffset=+3]
 
 include::modules/authorization/proc-mounting-the-policy-csv-file-using-the-operator.adoc[leveloffset=+4]
diff --git a/modules/authentication/proc-enabling-authentication-with-github.adoc b/modules/authentication/proc-enabling-authentication-with-github.adoc
@@ -159,6 +159,39 @@ auth:
         enterpriseInstanceUrl: ${GITHUB_HOST_DOMAIN}
 ----
 
+[TIP]
+====
+To enable GitHub integration with a different authentication provider, complete the following configurations:
+
+* Add the GitHub provider to the existing `auth` section.
+* Keep the `signInPage` section from your authentication provider configuration.
+
+.`app-config-rhdh.yaml` fragment with mandatory fields to enable GitHub integration and use a different authentication provider
+[source,yaml,subs="+quotes"]
+----
+auth:
+  environment: production
+  providers:
+    github:
+      production:
+        clientId: ${AUTH_GITHUB_CLIENT_ID}
+        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
+    __<your_other_authentication_providers_configuration>__
+integrations:
+  github:
+    - host: ${GITHUB_HOST_DOMAIN}
+      apps:
+        - appId: ${AUTH_GITHUB_APP_ID}
+          clientId: ${AUTH_GITHUB_CLIENT_ID}
+          clientSecret: ${GITHUB_CLIENT_SECRET}
+          webhookUrl: ${GITHUB_WEBHOOK_URL}
+          webhookSecret: ${GITHUB_WEBHOOK_SECRET}
+          privateKey: |
+            ${GITHUB_PRIVATE_KEY_FILE}
+signInPage: __<your_main_authentication_provider>__
+----
+====
+
 --
 
 .Verification
diff --git a/modules/authorization/con-rbac-config-permission-policies-admin.adoc b/modules/authorization/con-rbac-config-permission-policies-admin.adoc
diff --git a/modules/authorization/con-rbac-overview.adoc b/modules/authorization/con-rbac-overview.adoc
diff --git a/modules/authorization/proc-enabling-the-rbac-plugin.adoc b/modules/authorization/proc-enabling-the-rbac-plugin.adoc
@@ -0,0 +1,53 @@
+[id='enabling-and-giving-access-to-rbac']
+= Enabling and giving access to the Role-Based Access Control (RBAC) feature
+
+The Role-Based Access Control (RBAC) feature is disabled by default.
+Enable the RBAC plugin and declare policy administrators to start using RBAC features.
+
+The permission policies for users and groups in the {product-short} are managed by permission policy administrators. Only permission policy administrators can access the Role-Based Access Control REST API.
+
+.Prerequisites
+* You have link:{linkadminguide}#assembly-add-custom-app-file-openshift_admin-rhdh[added a custom {product-short} application configuration], and have sufficient permissions to modify it.
+* You have link:{authentication-book-title}[enabled an authentication provider].
+
+.Procedure
+. The RBAC plugin is installed but disabled by default.
+To enable the  `./dynamic-plugins/dist/janus-idp-backstage-plugin-rbac` plugin, edit your `dynamic-plugins.yaml` with the following content.
++
+.`dynamic-plugins.yaml` fragment
+[source,yaml]
+----
+plugins:
+  - package: ./dynamic-plugins/dist/janus-idp-backstage-plugin-rbac
+    disabled: false
+----
++
+See link:{installing-and-viewing-dynamic-plugins-url}[{installing-and-viewing-dynamic-plugins-title}].
+
+. Declare policy administrators to enable a select number of authenticated users to configure RBAC policies through the REST API or Web UI, instead of modifying the CSV file directly.
+The permissions can be specified in a separate CSV file referenced in the `app-config-rhdh` ConfigMap, or permissions can be created using the REST API or Web UI.
++
+To declare users such as _<your_policy_administrator_name>_ as policy administrators, edit your custom {product-short} ConfigMap, such as `app-config-rhdh`, and add following code to the `app-config-rhdh.yaml` content:
++
+.`app-config.yaml` fragment
+[source,yaml,subs=+quotes]
+----
+permission:
+  enabled: true
+  rbac:
+    admin:
+      users:
+        - name: user:default/__<your_policy_administrator_name>__
+----
+
+.Verification
+. Sign out from the existing {product} session and log in again using the declared policy administrator account.
+. With RBAC enabled, most features are disabled by default.
+.. Navigate to the *Catalog* page in {product-very-short}.
+The *Create* button is not visible.
+You cannot create new components.
+.. Navigate to the API page.
+The *Register* button is not visible.
+
+.Next steps
+* Explicitly enable permissions to resources in {product-short}.
diff --git a/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc b/modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.adoc
@@ -3,7 +3,7 @@
 You can enable the Bulk Import feature for users and give them the necessary permissions to access it.
 
 .Prerequisites
-* You have link:{authentication-book-url}#enabling-authentication-with-github[configured GitHub authentication and integration].
+* You have link:{authentication-book-url}#enabling-authentication-with-github[configured GitHub integration].
 
 .Procedure
 
diff --git a/modules/importing-repositories/procedure-importing-multiple-repositories-from-github.adoc b/modules/importing-repositories/procedure-importing-multiple-repositories-from-github.adoc
@@ -4,7 +4,6 @@
 In {product}, you can select your GitHub repositories and automate their onboarding to the {product-short} catalog.
 
 .Prerequisites
-* You have link:{authentication-book-url}#enabling-authentication-with-github[configured GitHub authentication and integration].
 * You have xref:enabling-and-giving-access-to-the-bulk-import-feature[enabled the Bulk Import feature and gave access to it].
 
 .Procedure
