Merge pull request #75173 from cbippley/OSDOCS-10363

skopacz1 · web-flow · commit cf1516e78060 · 2024-06-21T13:48:31.000-04:00
[DOCS] AUTH-509 Reducing permissions for unauthenticated users for apiserver access
diff --git a/authentication/impersonating-system-admin.adoc b/authentication/impersonating-system-admin.adoc
@@ -11,3 +11,5 @@ include::modules/authentication-api-impersonation.adoc[leveloffset=+1]
 include::modules/impersonation-system-admin-user.adoc[leveloffset=+1]
 
 include::modules/impersonation-system-admin-group.adoc[leveloffset=+1]
+
+include::modules/unauthenticated-users-cluster-role-binding.adoc[leveloffset=+1]
diff --git a/authentication/managing-oauth-access-tokens.adoc b/authentication/managing-oauth-access-tokens.adoc
@@ -16,3 +16,6 @@ include::modules/oauth-view-details-tokens.adoc[leveloffset=+1]
 
 // Deleting user-owned OAuth access tokens
 include::modules/oauth-delete-tokens.adoc[leveloffset=+1]
+
+// Adding unauthenticated groups to ClusterRoleBindings
+include::modules/unauthenticated-users-cluster-role-binding.adoc[leveloffset=+1]
diff --git a/authentication/tokens-scoping.adoc b/authentication/tokens-scoping.adoc
@@ -7,3 +7,5 @@ include::_attributes/common-attributes.adoc[]
 toc::[]
 
 include::modules/tokens-scoping-about.adoc[leveloffset=+1]
+
+include::modules/unauthenticated-users-cluster-role-binding.adoc[leveloffset=+1]
diff --git a/authentication/using-rbac.adoc b/authentication/using-rbac.adoc
@@ -42,3 +42,5 @@ endif::openshift-rosa[]
 ifdef::openshift-dedicated[]
 include::modules/osd-grant-admin-privileges.adoc[leveloffset=+1]
 endif::openshift-dedicated[]
+
+include::modules/unauthenticated-users-cluster-role-binding-con.adoc[leveloffset=+1]
diff --git a/cicd/builds/triggering-builds-build-hooks.adoc b/cicd/builds/triggering-builds-build-hooks.adoc
@@ -12,6 +12,13 @@ include::modules/builds-triggers.adoc[leveloffset=+1]
 
 include::modules/builds-webhook-triggers.adoc[leveloffset=+2]
 
+include::modules/unauthenticated-users-system-webhook.adoc[leveloffset=+3]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../authentication/using-rbac.adoc#unauthenticated-users-cluster-role-bindings-concept_using-rbac[Cluster role bindings for unauthenticated groups]
+
 include::modules/builds-using-github-webhooks.adoc[leveloffset=+3]
 
 include::modules/builds-using-gitlab-webhooks.adoc[leveloffset=+3]
@@ -34,4 +41,4 @@ include::modules/builds-build-hooks.adoc[leveloffset=+1]
 
 include::modules/builds-configuring-post-commit-build-hooks.adoc[leveloffset=+2]
 
-include::modules/builds-using-cli-post-commit-build-hooks.adoc[leveloffset=+2]
+include::modules/builds-using-cli-post-commit-build-hooks.adoc[leveloffset=+2]
diff --git a/modules/builds-using-bitbucket-webhooks.adoc b/modules/builds-using-bitbucket-webhooks.adoc
@@ -24,6 +24,10 @@ The payload URL is returned as the Bitbucket Webhook URL by the `oc describe` co
 https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket
 ----
 
+.Prerequisites
+
+* `system:unauthenticated` has access to the `system:webhook` role in the required namespaces. Or, `system:unauthenticated` has access to the `system:webhook` cluster role.
+
 .Procedure
 
 . Configure a Bitbucket Webhook.
diff --git a/modules/builds-using-github-webhooks.adoc b/modules/builds-using-github-webhooks.adoc
@@ -35,6 +35,7 @@ https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespa
 .Prerequisites
 
 * Create a `BuildConfig` from a GitHub repository.
+* `system:unauthenticated` has access to the `system:webhook` role in the required namespaces. Or, `system:unauthenticated` has access to the `system:webhook` cluster role.
 
 .Procedure
 
diff --git a/modules/builds-using-gitlab-webhooks.adoc b/modules/builds-using-gitlab-webhooks.adoc
@@ -24,6 +24,10 @@ The payload URL is returned as the GitLab Webhook URL by the `oc describe` comma
 https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab
 ----
 
+.Prerequisites
+
+* `system:unauthenticated` has access to the `system:webhook` role in the required namespaces. Or, `system:unauthenticated` has access to the `system:webhook` cluster role.
+
 .Procedure
 
 . Configure a GitLab Webhook.
diff --git a/modules/unauthenticated-users-cluster-role-binding-con.adoc b/modules/unauthenticated-users-cluster-role-binding-con.adoc
@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//
+// * authentication/using-rbac.adoc
+// * post_installation_configuration/preparing-for-users.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="unauthenticated-users-cluster-role-bindings-concept_{context}"]
+= Cluster role bindings for unauthenticated groups
+
+[NOTE]
+====
+Before {product-title} 4.16, unauthenticated groups were allowed access to some cluster roles. Clusters updated from versions before {product-title} 4.16 retain this access for unauthenticated groups.
+====
+
+For security reasons {product-title} {product-version} does not allow unauthenticated groups to have default access to cluster roles.
+
+There are use cases where it might be necessary to add `system:unauthenticated` to a cluster role.
+
+Cluster administrators can add unauthenticated users to the following cluster roles:
+
+* `system:scope-impersonation`
+* `system:webhook`
+* `system:oauth-token-deleter`
+* `self-access-reviewer`
+
+[IMPORTANT]
+====
+Always verify compliance with your organization's security standards when modifying unauthenticated access.
+====
diff --git a/modules/unauthenticated-users-cluster-role-binding.adoc b/modules/unauthenticated-users-cluster-role-binding.adoc
@@ -0,0 +1,57 @@
+// Module included in the following assemblies:
+//
+// * authentication/impersonating-system-admin.adoc
+// * authentication/tokens-scoping.adoc
+// * authentication/managing-oauth-access-tokens.adoc
+// * post_installation_configuration/preparing-for-users.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="unauthenticated-users-cluster-role-bindings_{context}"]
+= Adding unauthenticated groups to cluster roles
+
+As a cluster administrator, you can add unauthenticated users to the following cluster roles in {product-title} by creating a cluster role binding. Unauthenticated users do not have access to non-public cluster roles. This should only be done in specific use cases when necessary.
+
+You can add unauthenticated users to the following cluster roles:
+
+* `system:scope-impersonation`
+* `system:webhook`
+* `system:oauth-token-deleter`
+* `self-access-reviewer`
+
+[IMPORTANT]
+====
+Always verify compliance with your organization's security standards when modifying unauthenticated access.
+====
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed the OpenShift CLI (`oc`).
+
+.Procedure
+
+. Create a YAML file named `add-<cluster_role>-unauth.yaml` and add the following content:
++
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ annotations:
+   rbac.authorization.kubernetes.io/autoupdate: "true"
+ name: <cluster_role>access-unauthenticated
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: <cluster_role>
+subjects:
+ - apiGroup: rbac.authorization.k8s.io
+   kind: Group
+   name: system:unauthenticated
+----
+. Apply the configuration by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f add-<cluster_role>.yaml
+----
diff --git a/modules/unauthenticated-users-system-webhook.adoc b/modules/unauthenticated-users-system-webhook.adoc
@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// * cicd/builds/triggering-builds-build-hooks.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="unauthenticated-users-system-webhook_{context}"]
+= Adding unauthenticated users to the system:webhook role binding
+
+As a cluster administrator, you can add unauthenticated users to the `system:webhook` role binding in {product-title} for specific namespaces. The `system:webhook` role binding allows users to trigger builds from external systems that do not use an {product-title} authentication mechanism. Unauthenticated users do not have access to non-public role bindings by default. This is a change from {product-title} versions before 4.16.
+
+Adding unauthenticated users to the `system:webhook` role binding is required to successfully trigger builds from GitHub, GitLab, and Bitbucket.
+
+If it is necessary to allow unauthenticated users access to a cluster, you can do so by adding unauthenticated users to the `system:webhook` role binding in each required namespace. This method is more secure than adding unauthenticated users to the `system:webhook` cluster role binding. However, if you have a large number of namespaces, it is possible to add unauthenticated users to the `system:webhook` cluster role binding which would apply the change to all namespaces.
+
+[IMPORTANT]
+====
+Always verify compliance with your organization's security standards when modifying unauthenticated access.
+====
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed the OpenShift CLI (`oc`).
+
+.Procedure
+
+. Create a YAML file named `add-webhooks-unauth.yaml` and add the following content:
++
+[source,yaml]
+----
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  annotations:
+    rbac.authorization.kubernetes.io/autoupdate: "true"
+  name: webhook-access-unauthenticated
+  namespace: <namespace> <1>
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: "system:webhook"
+subjects:
+  - apiGroup: rbac.authorization.k8s.io
+    kind: Group
+    name: "system:unauthenticated"
+----
+<1> The namespace of your `BuildConfig`.
+
+. Apply the configuration by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f add-webhooks-unauth.yaml
+----
diff --git a/post_installation_configuration/preparing-for-users.adoc b/post_installation_configuration/preparing-for-users.adoc
@@ -114,6 +114,10 @@ include::modules/rbac-cluster-role-binding-commands.adoc[leveloffset=+2]
 include::modules/rbac-creating-cluster-admin.adoc[leveloffset=+2]
 endif::[]
 
+include::modules/unauthenticated-users-cluster-role-binding-con.adoc[leveloffset=+2]
+
+include::modules/unauthenticated-users-cluster-role-binding.adoc[leveloffset=+2]
+
 include::modules/authentication-kubeadmin.adoc[leveloffset=+1]
 
 include::modules/authentication-remove-kubeadmin.adoc[leveloffset=+2]
