diff --git a/.vale/styles/CheDocs/Spelling.yml b/.vale/styles/CheDocs/Spelling.yml index 1c617794e3..1b6bc8d672 100644 --- a/.vale/styles/CheDocs/Spelling.yml +++ b/.vale/styles/CheDocs/Spelling.yml @@ -129,6 +129,7 @@ filters: - Datadog - Dev - DevWorkspace + - Dex - DNS - Docker - Dockerfile diff --git a/antora.yml b/antora.yml index a470b7031f..af0b3aad2e 100644 --- a/antora.yml +++ b/antora.yml @@ -61,6 +61,9 @@ asciidoc: link-installing-an-instance: xref:installation-guide:installing-che.adoc[] link-server-identity-provider-dockerfile-location: https://github.com/eclipse-che/che-server/tree/main/dockerfiles/keycloak link-viewing-the-state-of-the-cluster-deployment-using-openshift-4-cli-tools: xref:overview:installing-che-on-openshift-4-using-operatorhub.adoc[] + link-oauth2-proxy: link:https://github.com/oauth2-proxy/oauth2-proxy[OAuth2 Proxy] + link-kube-rbac-proxy: link:https://github.com/brancz/kube-rbac-proxy[kube-rbac-proxy] + link-oidc-issuer: link:https://dexidp.io/[Dex] namespace: namespace # In context: API namespace nodejs-stack: nodejs ocp: OpenShift Container Platform diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 69db037f4f..5dfa6206c7 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -68,5 +68,7 @@ ** xref:authenticating-users.adoc[] ** xref:authorizing-users.adoc[] ** xref:configuring-authorization.adoc[] -** xref:configuring-openshift-oauth.adoc[] +*** xref:configuring-openshift-oauth.adoc[] +*** xref:configuring-minikube-github-authentication.adoc[] + ** xref:removing-user-data.adoc[] diff --git a/modules/administration-guide/pages/configuring-minikube-github-authentication.adoc b/modules/administration-guide/pages/configuring-minikube-github-authentication.adoc new file mode 100644 index 0000000000..587baa9c2c --- /dev/null +++ b/modules/administration-guide/pages/configuring-minikube-github-authentication.adoc @@ -0,0 +1,7 @@ +[id="configuring-openshift-oauth"] +// = Configuring OpenShift OAuth +:navtitle: Configuring Minikube GitHub Authentication +:keywords: administration-guide, configuring-openshift-oauth +:page-aliases: .:configuring-minikube-github-authentication + +include::partial$proc_configuring-minikube-github-authentication.adoc[] diff --git a/modules/administration-guide/pages/configuring-openshift-oauth.adoc b/modules/administration-guide/pages/configuring-openshift-oauth.adoc index f234084068..11a1f5cfee 100644 --- a/modules/administration-guide/pages/configuring-openshift-oauth.adoc +++ b/modules/administration-guide/pages/configuring-openshift-oauth.adoc @@ -1,7 +1,7 @@ [id="configuring-openshift-oauth"] // = Configuring OpenShift OAuth :navtitle: Configuring OpenShift OAuth -:keywords: end-user-guide, configuring-openshift-oauth +:keywords: administration-guide, configuring-openshift-oauth :page-aliases: .:configuring-openshift-oauth include::partial$proc_configuring-openshift-oauth.adoc[] diff --git a/modules/administration-guide/pages/managing-identities-and-authorizations.adoc b/modules/administration-guide/pages/managing-identities-and-authorizations.adoc index 8534724939..2adc2dc4f7 100644 --- a/modules/administration-guide/pages/managing-identities-and-authorizations.adoc +++ b/modules/administration-guide/pages/managing-identities-and-authorizations.adoc @@ -1,7 +1,7 @@ [id="managing-identities-and-authorizations"] // = Managing identities and authorizations :navtitle: Managing identities and authorizations -:keywords: end-user-guide, managing-identities-and-authorizations +:keywords: administration-guide, managing-identities-and-authorizations :page-aliases: .:managing-identities-and-authorizations include::partial$assembly_managing-identities-and-authorizations.adoc[] diff --git a/modules/administration-guide/partials/assembly_authorizing-users.adoc b/modules/administration-guide/partials/assembly_authorizing-users.adoc index a8b4e04e0f..5e0af58bac 100644 --- a/modules/administration-guide/partials/assembly_authorizing-users.adoc +++ b/modules/administration-guide/partials/assembly_authorizing-users.adoc @@ -33,5 +33,4 @@ include::partial$proc_listing-che-permissions.adoc[leveloffset=+1] include::partial$proc_assigning-che-permissions.adoc[leveloffset=+1] - :context: {parent-context-of-authorizing-users} diff --git a/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc b/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc index 019f0f8c68..3528756b34 100644 --- a/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc +++ b/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc @@ -13,5 +13,6 @@ This section describes different aspects of managing identities and authorizatio * xref:configuring-authorization.adoc[] * xref:removing-user-data.adoc[] * xref:configuring-openshift-oauth.adoc[] +* xref:configuring-minikube-github-authentication.adoc[] :context: {parent-context-of-managing-identities-and-authorizations} diff --git a/modules/administration-guide/partials/con_che-operator.adoc b/modules/administration-guide/partials/con_che-operator.adoc index 37cfd94aba..a6e89e9b2c 100644 --- a/modules/administration-guide/partials/con_che-operator.adoc +++ b/modules/administration-guide/partials/con_che-operator.adoc @@ -15,7 +15,15 @@ Defines the `CheCluster` {orch-name} object. Creates and controls the necessary {orch-name} objects to run a {prod-short} instance, such as pods, services, and persistent volumes. `CheCluster` custom resource (CR):: -On a cluster with the {prod-short} operator, it is possible to create a `CheCluster` custom resource (CR). The {prod-short} operator ensure full lifecycle management of the {prod-short} server components on this {prod-short} instance. +On a cluster with the {prod-short} operator, it is possible to create a `CheCluster` custom resource (CR). The {prod-short} operator ensures the full lifecycle management of the {prod-short} server components on this {prod-short} instance: ++ +* xref:devworkspace-operator.adoc[] +* xref:gateway.adoc[] +* xref:dashboard.adoc[] +* xref:devfile-registries.adoc[] +* xref:che-server.adoc[] +* xref:postgresql.adoc[] +* xref:plug-in-registry.adoc[] .Additional resources diff --git a/modules/administration-guide/partials/con_gateway.adoc b/modules/administration-guide/partials/con_gateway.adoc index 622bcaa53c..30e2e71e29 100644 --- a/modules/administration-guide/partials/con_gateway.adoc +++ b/modules/administration-guide/partials/con_gateway.adoc @@ -1,7 +1,14 @@ [id="gateway_{context}"] = Gateway -The {prod-short} gateway is a Traefik instance applying {orch-name} Role based access control (RBAC) policies to control access to any {prod-short} resource. +The {prod-short} gateway has following roles: + +* Routing requests. It uses link:https://github.com/traefik/traefik[Traefik]. + +* Authenticating users with OpenID Connect (OIDC). It uses {link-oauth2-proxy}. + +* Applying {orch-name} Role based access control (RBAC) policies to control access to any {prod-short} resource. It uses {link-kube-rbac-proxy}. + The {prod-short} operator manages it as the `che-gateway` Deployment. It controls access to: diff --git a/modules/administration-guide/partials/proc_configuring-minikube-github-authentication.adoc b/modules/administration-guide/partials/proc_configuring-minikube-github-authentication.adoc new file mode 100644 index 0000000000..e9942432ab --- /dev/null +++ b/modules/administration-guide/partials/proc_configuring-minikube-github-authentication.adoc @@ -0,0 +1,69 @@ +[id="configuring-minikube-github-authentication_{context}"] += Configuring Minikube with GitHub Authentication + + +On Minikube, {prod-cli} provides a default OpenID Connect (OIDC) issuer, which can serve as a bridge to third party {identity-provider}, such as GitHub. +{link-oidc-issuer} is the default OIDC issuer, preconfigured with static users. +Configure {link-oidc-issuer} to use GitHub authentication. + +.Prerequisites + +* {prod-short} is installed on Minikube. See xref:installation-guide:installing-che-on-minikube.adoc[]. + + +.Procedure +. Get Minikube IP and remember it as `__`: ++ +---- +$ minikube ip +---- + +. link:https://github.com/settings/applications/new[Create an OAuth App] for your Minikube instance in GitHub. See link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub documentation]. ++ +[source,subs="+attributes,macros,quotes"] +---- +Application name: {prod-short} <1> +Homepage URL: https://.nip.io <2> +Authorization callback URL: https://dex..nip.io/callback <3> +---- ++ +<1> Name is only displayed on GitHub. It is not used internally so it can be any name. +<2> Main URL to {prod-short} instance. +<3> Callback URL to Dex. {prod-cli} deploys Dex on `dex.` subdomain. + + +. In the GitHub OAuth application page, click btn:[Generate a new client secret] and remember the value of the generated client secret as `__`. + +. Edit the {link-oidc-issuer} config map: ++ +---- +$ kubectl edit configmap dex -n dex +---- ++ +[source,yaml,subs="+attributes,macros,quotes"] +---- +connectors: +- type: github + id: github + name: GitHub + config: + clientID: __ <1> + clientSecret: __ <2> + redirectURI: https://dex.__.nip.io/callback <3> +---- ++ +<1> OAuth client id copied from GitHub OAuth application +<2> OAuth client secret, generated at GitHub in previous step +<3> Callback URL to Dex. This must match configuration in GitHub OAuth application from step 1. + +Note: To remove Dex static users, delete all `enablePasswordDB` and `staticPasswords` sections. + +. Restart the {link-oidc-issuer} pod: ++ +---- +$ kubectl delete pod dex -n dex +---- + +.Verification steps + +* Open {prod-short} URL. The dashboard displays GitHub login prompt. diff --git a/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc b/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc index 8468f91652..6b73c09fe8 100644 --- a/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc +++ b/modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc @@ -2,7 +2,7 @@ [id="enabling-dev-workspace-operator_{context}"] = Enabling {devworkspace} operator -This procedure describes how to enable the {devworkspace} operator to support the Devfile 2.0.0 file format and mentions how to do so on existing instances or those about to be installed. +This procedure describes how to enable the {devworkspace} operator to support the Devfile v2 file format and mentions how to do so on existing instances or those about to be installed. .Prerequisites @@ -32,18 +32,25 @@ spec: + [subs="+quotes,+attributes"] ---- -$ {prod-cli} server:deploy --che-operator-cr-patch-yaml=patch.yaml ... +$ {prod-cli} server:deploy --workspace-engine=dev-workspace ... ---- -+ -`patch.yaml` must contain the following: -+ + +ifeval::["{project-context}" == "che"] +[WARNING] +==== +{prod-cli} will automatically setup Dex as the OIDC provider on Minikube. For other {kubernetes} clusters setup link:https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server[{kubernetes} OIDC] provider following cluster provider documentation and set the following values in {prod-checluster} Custom Resource (CR): + [source,yaml,subs="+quotes"] ---- spec: - devWorkspace: - enable: true + auth: + identityProviderURL: '____' <1> ---- +<1> URL to the OIDC provider. +==== +endif::[] + * For already existing {prod-short} installation: + . Update `{prod-checluster}` CR using the `{orch-cli}` tool: