From 4222c306fd480d2f942f4ae62e9c1c9ab5a468ae Mon Sep 17 00:00:00 2001 From: Jinah Yun-Mitchell Date: Fri, 6 Dec 2024 13:45:10 -0600 Subject: [PATCH] ENDOC-819 link fixes & misc --- .../next/docs/consume/identity-management.md | 8 ++-- .../next/tutorials/curate/private-git-repo.md | 43 +++++++++---------- .../tutorials/curate/ecr-private-images.md | 2 +- .../v7.2/docs/consume/identity-management.md | 6 +-- .../v7.3/docs/consume/identity-management.md | 8 ++-- .../v7.3/tutorials/curate/private-git-repo.md | 43 +++++++++---------- 6 files changed, 54 insertions(+), 56 deletions(-) diff --git a/vuepress/docs/next/docs/consume/identity-management.md b/vuepress/docs/next/docs/consume/identity-management.md index a7787bb633..3417bad140 100644 --- a/vuepress/docs/next/docs/consume/identity-management.md +++ b/vuepress/docs/next/docs/consume/identity-management.md @@ -34,7 +34,7 @@ Keycloak authorizes microservices using clients and roles. Authorizations are st Below are the steps to grant a user one or more roles for a specific client. This controls permissions when configuring the microservice. Note, when a microservice is installed in Entando, a corresponding client (and set of roles) is created within its plugin definition. -1. [Login to Keycloak](#logging-into-your-keycloak-instance) +1. [Log in to Keycloak](#logging-into-your-keycloak-instance) >For non-external Keycloak instances, it is [the base URL of your running Entando application](../getting-started/README.md#configure-access-to-your-cluster) followed by `/auth/`, e.g. http://YOUR-HOST-NAME/auth. In a standard Entando installation, the base URL can be verified with `kubectl get ingress/default-sso-in-namespace-ingress`. 2. Select `Users` from the left menu 3. Use the search box to find the appropriate user, e.g. "admin" @@ -60,12 +60,12 @@ See [KeycloakAuthorizationManager.java](https://github.com/entando/entando-keycl ## Social Login -Keycloak allows Entando to provide social login as an out-of-the-box capability. [Keycloak Social Identity Providers](https://www.keycloak.org/docs/18.0/server_admin/index.html#social-identity-providers) documents how to enable and configure social logins in your Entando Applications. +Keycloak allows Entando to provide social login as an out-of-the-box capability. [Keycloak Social Identity Providers](https://www.keycloak.org/docs/21.0.2/server_admin/index.html#_identity_broker) documents how to enable and configure social logins in your Entando Applications. ## One Time Passwords -Keycloak enables One Time Password (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/18.0/server_admin/index.html#one-time-password-otp-policies) to configure and enable it. +Keycloak enables One Time Password (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/21.0.2/server_admin/index.html#one-time-password-otp-policies) to configure and enable it. ## Themes, Look and Feel -Developers can customize the look and feel of the login page, as well as the identity management system that comes with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/18.0/server_development/#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). +Developers can customize the look and feel of the login page, as well as the identity management system that comes with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/21.0.2/server_development/index.html#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). diff --git a/vuepress/docs/next/tutorials/curate/private-git-repo.md b/vuepress/docs/next/tutorials/curate/private-git-repo.md index 5cf36e201d..182320dbbc 100644 --- a/vuepress/docs/next/tutorials/curate/private-git-repo.md +++ b/vuepress/docs/next/tutorials/curate/private-git-repo.md @@ -1,34 +1,38 @@ +--- +sidebarDebth: 2 +--- + # Install Bundles from a Private Git Repository ## Overview -The standard deployment of Entando assumes that bundles are checked out from public Git or Docker repositories. Public repositories do not require user authentication, but a private key is required if a customer chooses to limit repository access to specific Git or Docker accounts. This tutorial describes how to allow Entando to access a private Git repository. +The standard deployment of Entando assumes that bundles are checked out from a public Git or Docker repository. Public repositories do not require user authentication, but a private key is required if repository access is limited to specific user accounts. This tutorial describes how to grant access to a private Git repository from Entando. -For more background information please consult +For more background information please consult: 1. [Entando custom resource reference](../../docs/reference/custom-resources.md) 2. [Local Hub overview](../../docs/compose/local-hub-overview.md) ## Using SSH keys with Git -Entando supports connecting to Git repositories with SSH keys. While SSH Git URLs are accepted, HTTPS git URLs are not. For the private key to work correctly, the SSH syntax of `git@github.com:THE-REPO-OWNER-NAME/THE-REPO-NAME.git` must be used (the HTTPS syntax of `https://github.com/THE-REPO-OWNER-NAME/THE-REPO-NAME.git` is not permitted). +Entando supports connecting to Git repositories with SSH keys. While SSH Git URLs are accepted, HTTPS Git URLs are not. For the private key to work correctly, the SSH syntax of `git@github.com:THE-REPO-OWNER-NAME/THE-REPO-NAME.git` must be used (the HTTPS syntax of `https://github.com/THE-REPO-OWNER-NAME/THE-REPO-NAME.git` is not permitted). -Using the SSH method a developer can generate a public/private keypair, then register the public key with the Git server while securely storing the private key locally. An operation requiring authentication will trigger the Git command line utility to perform a search and compare between the local private key and the public key provided by the server. If the two keys are identical, the operation is allowed to complete. +Using the SSH method, a developer can generate a public/private key pair, then register the public key with the Git server while securely storing the private key locally. An operation requiring authentication will trigger the Git command line utility to perform a search and compare between the private and public keys. If the two keys match, the operation is allowed to complete. -Entando allows a Kubernetes Secret containing a Git SSH private key to be mounted in the container hosting the Entando Component Manager service. This container is deployed with the EntandoApp and can be configured from the EntandoApp Custom Resource. To prepare a Secret, first generate the keypair locally using a Docker image, then create the Secret from the directory where the keypair was generated. +Entando allows a Kubernetes Secret containing a Git SSH private key to be mounted in the container hosting the Entando Component Manager service. This container is deployed with the EntandoApp and can be configured from the EntandoApp Custom Resource. To prepare a Secret, first generate the key pair locally using a Docker image, then create the Secret from the directory where the key pair was generated. ## Tutorial Below is the recommended flow on Linux. -1. Navigate to a local folder where you intend to create the Secret +1. Navigate to a local folder where you intend to create the Secret. -2. Generate the SSH keypair from the known SSH client Docker image +2. Generate the SSH key pair from the known SSH client Docker image. - 1. Run the Docker container in interactive mode and mount the default user SSH directory to a local directory + 1. Run the Docker container in interactive mode and mount the default user SSH directory to a local directory: ``` docker run -it -v $PWD/entando_ssh:/root/.ssh kroniak/ssh-client /bin/bash ``` - 2. Generate the keypair from the shell of the resulting container + 2. Generate the key pair from the shell of the resulting container: ``` ssh-keygen @@ -36,7 +40,7 @@ Below is the recommended flow on Linux. Select all of the default options, e.g. no passphrase, etc. - 3. Attempt to add the fingerprint to the known_hosts file by connecting to your Git server and responding "yes" to the prompt + 3. Attempt to add the fingerprint to the known_hosts file by connecting to your Git server and responding "yes" to the prompt: ``` ssh git@github.com @@ -46,35 +50,30 @@ Below is the recommended flow on Linux. 4. Run `exit` -3. Create the Secret. - -You are now back in the local operating system's shell and can navigate to the directory that was mounted using Docker. - - To give yourself access to this folder and create a Secret with the content +3. Create the Secret. Back in the local operating system's shell, navigate to the directory that was mounted using Docker. Then give yourself access to this folder and create the Secret: - 1. Change the folder permissions + 1. Change the folder permissions: ``` sudo chmod ag+r entando_ssh -R ``` - 2. Create a Secret from the directory + 2. Create a Secret from the directory: ``` kubectl create secret generic my-git-secret --from-file=entando_ssh -n <> ``` - 3. Confirm that the Secret exists and has at least two keys: known_hosts, and id_rsa. Without these two keys Entando cannot log into Git. + 3. Confirm that the Secret exists and has at least two keys: `known_hosts` and `id_rsa`. Without these two keys, Entando cannot log into Git. ``` kubectl get secret my-git-secret -n <> -o yaml ``` -4. Link the resulting private key to the account of a user who has access to the applicable Git repositories. Ideally -this should be a dedicated service account user with restricted read only access. For GitHub +4. Link the resulting private key to the account of a user who has access to the applicable Git repositories. Ideally, +this should be a dedicated service account with restricted read only access. For GitHub accounts, you can follow the [official GitHub instructions.](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account) -When prompted, provide the public key that was generated in the entando_ssh directory -```entando_ssh/id_rsa.pub``` +When prompted, provide the public key that was generated in the `entando_ssh/id_rsa.pub` directory. 5. Modify the EntandoApp resource you are deploying to configure the Secret using the `spec.ecrGitSshSecretName` property. ``` diff --git a/vuepress/docs/v7.0/tutorials/curate/ecr-private-images.md b/vuepress/docs/v7.0/tutorials/curate/ecr-private-images.md index eb9a01f5fa..18ff0aea95 100644 --- a/vuepress/docs/v7.0/tutorials/curate/ecr-private-images.md +++ b/vuepress/docs/v7.0/tutorials/curate/ecr-private-images.md @@ -17,7 +17,7 @@ The first step demonstrates how to create a Secret for Docker Hub but please see **1. Create the secret** Supply the following parameters: * the name of the new Secret, e.g. `my-docker-secret`. -* the URL to your registry server. For Docker Hub this is currently +* the URL to your registry server. For Docker Hub this is currently `https://index.docker.io/v1/` * your Docker Hub username, password, and email. * the Entando namespace, e.g. `entando` for a quickstart environment. diff --git a/vuepress/docs/v7.2/docs/consume/identity-management.md b/vuepress/docs/v7.2/docs/consume/identity-management.md index 23d9753311..4f6a0cc39c 100644 --- a/vuepress/docs/v7.2/docs/consume/identity-management.md +++ b/vuepress/docs/v7.2/docs/consume/identity-management.md @@ -56,12 +56,12 @@ See [KeycloakAuthorizationManager.java](https://github.com/entando/entando-keycl ## Social Login -Keycloak allows Entando to provide social login as an out-of-the-box capability. [Keycloak Social Identity Providers](https://www.keycloak.org/docs/18.0/server_admin/index.html#social-identity-providers) documents how to enable and configure social logins in your Entando Applications. +Keycloak allows Entando to provide social login as an out-of-the-box capability. [Keycloak Social Identity Providers](https://www.keycloak.org/docs/21.0.2/server_admin/index.html#_identity_broker) documents how to enable and configure social logins in your Entando Applications. ## One Time Passwords -Keycloak enables One Time Passwords (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/18.0/server_admin/index.html#one-time-password-otp-policies) to configure and enable OTP in your application. +Keycloak enables One Time Passwords (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/21.0.2/server_admin/index.html#one-time-password-otp-policies) to configure and enable OTP in your application. ## Themes, Look and Feel -Developers can customize the look and feel of the login page, as well as the identity management system that ships with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/18.0/server_development/#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). +Developers can customize the look and feel of the login page, as well as the identity management system that ships with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/21.0.2/server_development/index.html#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). diff --git a/vuepress/docs/v7.3/docs/consume/identity-management.md b/vuepress/docs/v7.3/docs/consume/identity-management.md index a7787bb633..3417bad140 100644 --- a/vuepress/docs/v7.3/docs/consume/identity-management.md +++ b/vuepress/docs/v7.3/docs/consume/identity-management.md @@ -34,7 +34,7 @@ Keycloak authorizes microservices using clients and roles. Authorizations are st Below are the steps to grant a user one or more roles for a specific client. This controls permissions when configuring the microservice. Note, when a microservice is installed in Entando, a corresponding client (and set of roles) is created within its plugin definition. -1. [Login to Keycloak](#logging-into-your-keycloak-instance) +1. [Log in to Keycloak](#logging-into-your-keycloak-instance) >For non-external Keycloak instances, it is [the base URL of your running Entando application](../getting-started/README.md#configure-access-to-your-cluster) followed by `/auth/`, e.g. http://YOUR-HOST-NAME/auth. In a standard Entando installation, the base URL can be verified with `kubectl get ingress/default-sso-in-namespace-ingress`. 2. Select `Users` from the left menu 3. Use the search box to find the appropriate user, e.g. "admin" @@ -60,12 +60,12 @@ See [KeycloakAuthorizationManager.java](https://github.com/entando/entando-keycl ## Social Login -Keycloak allows Entando to provide social login as an out-of-the-box capability. [Keycloak Social Identity Providers](https://www.keycloak.org/docs/18.0/server_admin/index.html#social-identity-providers) documents how to enable and configure social logins in your Entando Applications. +Keycloak allows Entando to provide social login as an out-of-the-box capability. [Keycloak Social Identity Providers](https://www.keycloak.org/docs/21.0.2/server_admin/index.html#_identity_broker) documents how to enable and configure social logins in your Entando Applications. ## One Time Passwords -Keycloak enables One Time Password (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/18.0/server_admin/index.html#one-time-password-otp-policies) to configure and enable it. +Keycloak enables One Time Password (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/21.0.2/server_admin/index.html#one-time-password-otp-policies) to configure and enable it. ## Themes, Look and Feel -Developers can customize the look and feel of the login page, as well as the identity management system that comes with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/18.0/server_development/#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). +Developers can customize the look and feel of the login page, as well as the identity management system that comes with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/21.0.2/server_development/index.html#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). diff --git a/vuepress/docs/v7.3/tutorials/curate/private-git-repo.md b/vuepress/docs/v7.3/tutorials/curate/private-git-repo.md index 5cf36e201d..182320dbbc 100644 --- a/vuepress/docs/v7.3/tutorials/curate/private-git-repo.md +++ b/vuepress/docs/v7.3/tutorials/curate/private-git-repo.md @@ -1,34 +1,38 @@ +--- +sidebarDebth: 2 +--- + # Install Bundles from a Private Git Repository ## Overview -The standard deployment of Entando assumes that bundles are checked out from public Git or Docker repositories. Public repositories do not require user authentication, but a private key is required if a customer chooses to limit repository access to specific Git or Docker accounts. This tutorial describes how to allow Entando to access a private Git repository. +The standard deployment of Entando assumes that bundles are checked out from a public Git or Docker repository. Public repositories do not require user authentication, but a private key is required if repository access is limited to specific user accounts. This tutorial describes how to grant access to a private Git repository from Entando. -For more background information please consult +For more background information please consult: 1. [Entando custom resource reference](../../docs/reference/custom-resources.md) 2. [Local Hub overview](../../docs/compose/local-hub-overview.md) ## Using SSH keys with Git -Entando supports connecting to Git repositories with SSH keys. While SSH Git URLs are accepted, HTTPS git URLs are not. For the private key to work correctly, the SSH syntax of `git@github.com:THE-REPO-OWNER-NAME/THE-REPO-NAME.git` must be used (the HTTPS syntax of `https://github.com/THE-REPO-OWNER-NAME/THE-REPO-NAME.git` is not permitted). +Entando supports connecting to Git repositories with SSH keys. While SSH Git URLs are accepted, HTTPS Git URLs are not. For the private key to work correctly, the SSH syntax of `git@github.com:THE-REPO-OWNER-NAME/THE-REPO-NAME.git` must be used (the HTTPS syntax of `https://github.com/THE-REPO-OWNER-NAME/THE-REPO-NAME.git` is not permitted). -Using the SSH method a developer can generate a public/private keypair, then register the public key with the Git server while securely storing the private key locally. An operation requiring authentication will trigger the Git command line utility to perform a search and compare between the local private key and the public key provided by the server. If the two keys are identical, the operation is allowed to complete. +Using the SSH method, a developer can generate a public/private key pair, then register the public key with the Git server while securely storing the private key locally. An operation requiring authentication will trigger the Git command line utility to perform a search and compare between the private and public keys. If the two keys match, the operation is allowed to complete. -Entando allows a Kubernetes Secret containing a Git SSH private key to be mounted in the container hosting the Entando Component Manager service. This container is deployed with the EntandoApp and can be configured from the EntandoApp Custom Resource. To prepare a Secret, first generate the keypair locally using a Docker image, then create the Secret from the directory where the keypair was generated. +Entando allows a Kubernetes Secret containing a Git SSH private key to be mounted in the container hosting the Entando Component Manager service. This container is deployed with the EntandoApp and can be configured from the EntandoApp Custom Resource. To prepare a Secret, first generate the key pair locally using a Docker image, then create the Secret from the directory where the key pair was generated. ## Tutorial Below is the recommended flow on Linux. -1. Navigate to a local folder where you intend to create the Secret +1. Navigate to a local folder where you intend to create the Secret. -2. Generate the SSH keypair from the known SSH client Docker image +2. Generate the SSH key pair from the known SSH client Docker image. - 1. Run the Docker container in interactive mode and mount the default user SSH directory to a local directory + 1. Run the Docker container in interactive mode and mount the default user SSH directory to a local directory: ``` docker run -it -v $PWD/entando_ssh:/root/.ssh kroniak/ssh-client /bin/bash ``` - 2. Generate the keypair from the shell of the resulting container + 2. Generate the key pair from the shell of the resulting container: ``` ssh-keygen @@ -36,7 +40,7 @@ Below is the recommended flow on Linux. Select all of the default options, e.g. no passphrase, etc. - 3. Attempt to add the fingerprint to the known_hosts file by connecting to your Git server and responding "yes" to the prompt + 3. Attempt to add the fingerprint to the known_hosts file by connecting to your Git server and responding "yes" to the prompt: ``` ssh git@github.com @@ -46,35 +50,30 @@ Below is the recommended flow on Linux. 4. Run `exit` -3. Create the Secret. - -You are now back in the local operating system's shell and can navigate to the directory that was mounted using Docker. - - To give yourself access to this folder and create a Secret with the content +3. Create the Secret. Back in the local operating system's shell, navigate to the directory that was mounted using Docker. Then give yourself access to this folder and create the Secret: - 1. Change the folder permissions + 1. Change the folder permissions: ``` sudo chmod ag+r entando_ssh -R ``` - 2. Create a Secret from the directory + 2. Create a Secret from the directory: ``` kubectl create secret generic my-git-secret --from-file=entando_ssh -n <> ``` - 3. Confirm that the Secret exists and has at least two keys: known_hosts, and id_rsa. Without these two keys Entando cannot log into Git. + 3. Confirm that the Secret exists and has at least two keys: `known_hosts` and `id_rsa`. Without these two keys, Entando cannot log into Git. ``` kubectl get secret my-git-secret -n <> -o yaml ``` -4. Link the resulting private key to the account of a user who has access to the applicable Git repositories. Ideally -this should be a dedicated service account user with restricted read only access. For GitHub +4. Link the resulting private key to the account of a user who has access to the applicable Git repositories. Ideally, +this should be a dedicated service account with restricted read only access. For GitHub accounts, you can follow the [official GitHub instructions.](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account) -When prompted, provide the public key that was generated in the entando_ssh directory -```entando_ssh/id_rsa.pub``` +When prompted, provide the public key that was generated in the `entando_ssh/id_rsa.pub` directory. 5. Modify the EntandoApp resource you are deploying to configure the Secret using the `spec.ecrGitSshSecretName` property. ```