Merge branch 'main' into RHIDP-3972-chapter-1-enabling-the-rbac-plugin

Author: Gerry-Forde

.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")

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:
 

assemblies/assembly-configuring-authorization-in-rhdh.adoc

@@ -1,7 +1,30 @@
 [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]

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

modules/authorization/con-rbac-overview.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
 

modules/importing-repositories/procedure-enabling-the-bulk-import-from-github-feature.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