Refactoring notes

2026-09-25 04:28:15 +00:00 · 2022-07-06 13:06:03 -04:00
parent 4c8edca04b
commit 7a2966aea6
14 changed files with 250 additions and 117 deletions
@@ -21,15 +21,17 @@ Usually a (non-admin) **Domain User** account should be used for this purpose, a

 Note however, that in some locked-down Active Directory configurations this default behaviour may not apply. In such case you will need to ensure that the service account user has at least **Read** and **List Content** permissions granted either on the Base OU (enclosing users and groups) or globally for the domain.

-> **Using TLS?**
->
-> - If the certificate used by the AD server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
->
-> - Upon an upgrade to v2.6.0, authenticating via Rancher against an active directory using TLS can fail if the certificates on the AD server do not support SAN attributes. This is a check enabled by default in Go v1.15. 
->
->    - The error received is "Error creating SSL connection: LDAP Result Code 200 "Network Error": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0". 
->
->    - To resolve the error, update or replace the certificates on the AD server with new ones that support the SAN attribute. Alternatively, this error can be ignored by setting `GODEBUG=x509ignoreCN=0` as an environment variable to Rancher server container.
+:::note Using TLS?
+
+- If the certificate used by the AD server is self-signed or not from a recognized certificate authority, make sure have at hand the CA certificate (concatenated with any intermediate certificates) in PEM format. You will have to paste in this certificate during the configuration so that Rancher is able to validate the certificate chain.
+
+- Upon an upgrade to v2.6.0, authenticating via Rancher against an active directory using TLS can fail if the certificates on the AD server do not support SAN attributes. This is a check enabled by default in Go v1.15. 
+
+   - The error received is "Error creating SSL connection: LDAP Result Code 200 "Network Error": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0". 
+
+   - To resolve the error, update or replace the certificates on the AD server with new ones that support the SAN attribute. Alternatively, this error can be ignored by setting `GODEBUG=x509ignoreCN=0` as an environment variable to Rancher server container.
+
+:::

 ## Configuration Steps
 ### Open Active Directory Configuration
@@ -5,19 +5,29 @@ weight: 1115

 If you have an instance of Active Directory (AD) hosted in Azure, you can configure Rancher to allow your users to log in using their AD accounts. Configuration of Azure AD external authentication requires you to make configurations in both Azure and Rancher.

->**Note:** Azure AD integration only supports Service Provider initiated logins.
+:::note Prerequisite:

->**Prerequisite:** Have an instance of Azure AD configured.
+Have an instance of Azure AD configured.

->**Note:** Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/).
+:::
+
+:::note Notes 
+
+- Azure AD integration only supports Service Provider initiated logins.
+
+- Most of this procedure takes place from the [Microsoft Azure Portal](https://portal.azure.com/).
+
+:::

 ## Azure Active Directory Configuration Outline

 Configuring Rancher to allow your users to authenticate with their Azure AD accounts involves multiple procedures. Review the outline below before getting started.

-<a id="tip"></a>
+:::tip

->**Tip:** Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.
+Before you start, we recommend creating an empty text file. You can use this file to copy values from Azure that you'll paste into Rancher later.
+
+:::

 <!-- TOC -->

@@ -50,11 +60,19 @@ Before enabling Azure AD within Rancher, you must register Rancher with Azure.

    1. In the **Redirect URI** section, make sure **Web** is selected from the dropdown and enter the URL of your Rancher Server in the text box next to the dropdown. This Rancher server URL should be appended with the verification path: `<MY_RANCHER_URL>/verify-auth-azure`.

-       >**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
+       :::tip
+       
+       You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
+
+       :::

    1. Click **Register**.

->**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
+:::note
+
+It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
+
+:::

 ### 2. Create a new client secret

@@ -110,7 +128,11 @@ Next, set API permissions for Rancher within Azure.

 1. From **API permissions**, click **Grant admin consent**. Then click **Yes**.

-    >**Note:** You must be signed in as an Azure administrator to successfully save your permission settings.
+    :::note
+    
+    You must be signed in as an Azure administrator to successfully save your permission settings.
+
+    :::


 ### 4. Add a Reply URL
@@ -124,13 +146,21 @@ To use Azure AD with Rancher you must whitelist Rancher with Azure. You can comp

 1. From the **Reply URLs** blade, enter the URL of your Rancher Server, appended with the verification path: `<MY_RANCHER_URL>/verify-auth-azure`.

-       >**Tip:** You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
+       :::tip
+       
+       You can find your personalized Azure reply URL in Rancher on the Azure AD Authentication page (Global View > Security Authentication > Azure AD).
+
+       :::

 1. Click **Save**.

 **Result:** Your reply URL is saved.

->**Note:** It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
+:::note
+
+It can take up to five minutes for this change to take affect, so don't be alarmed if you can't authenticate immediately after Azure AD configuration.
+
+:::

 ### 5. Copy Azure Application Data

@@ -170,7 +200,11 @@ As your final step in Azure, copy the data that you'll use to configure Rancher
        - **OAuth 2.0 token endpoint (v1)** (Token Endpoint)
        - **OAuth 2.0 authorization endpoint (v1)** (Auth Endpoint)
        
->**Note:** Copy the v1 version of the endpoints
+:::note
+
+Copy the v1 version of the endpoints
+
+:::

 ### 6. Configure Azure AD in Rancher

@@ -184,9 +218,13 @@ Enter the values that you copied to your [text file](#tip).
 1. Click **AzureAD**.
 1. Complete the **Configure Azure AD Account** form using the information you copied while completing [Copy Azure Application Data](#5-copy-azure-application-data).

-    >**Important:** When entering your Graph Endpoint, remove the tenant ID from the URL, like below.
-    >
-    ><code>http<span>s://g</span>raph.windows.net/<del>abb5adde-bee8-4821-8b03-e63efdc7701c</del></code>
+    :::note Important 
+    
+    When entering your Graph Endpoint, remove the tenant ID from the URL, like below.
+    
+    <code>http<span>s://g</span>raph.windows.net/<del>abb5adde-bee8-4821-8b03-e63efdc7701c</del></code>
+
+    :::

    The following table maps the values you copied in the Azure portal to the fields in Rancher.

@@ -5,11 +5,13 @@ weight: 1114

 If your organization uses FreeIPA for user authentication, you can configure Rancher to allow your users to login using their FreeIPA credentials.

->**Prerequisites:**
->
->- You must have a [FreeIPA Server](https://www.freeipa.org/) configured.
->- Create a service account in FreeIPA with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key.
->- Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+:::note Prerequisites:
+
+- You must have a [FreeIPA Server](https://www.freeipa.org/) configured.
+- Create a service account in FreeIPA with `read-only` access. Rancher uses this account to verify group membership when a user makes a request using an API key.
+- Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+
+:::

 1.  Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_).
 1.	In the top left corner, click **☰ > Users & Authentication**.
@@ -19,28 +21,36 @@ If your organization uses FreeIPA for user authentication, you can configure Ran

 	You may need to log in to your domain controller to find the information requested in the form.

-	>**Using TLS?**
- 	>If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate.
-	<br/>
-	<br/>
-	>**User Search Base vs. Group Search Base**
-	>
-	>Search base allows Rancher to search for users and groups that are in your FreeIPA.  These fields are only for search bases and not for search filters.
-	>
-	>* If your users and groups are in the same search base, complete only the User Search Base.
-	>* If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.
+	:::note Using TLS?
+
+	If the certificate is self-signed or not from a recognized certificate authority, make sure you provide the complete chain. That chain is needed to verify the server's certificate.
+
+	:::
+
+	:::note User Search Base vs. Group Search Base
+	
+	Search base allows Rancher to search for users and groups that are in your FreeIPA.  These fields are only for search bases and not for search filters.
+	
+	* If your users and groups are in the same search base, complete only the User Search Base.
+	* If your groups are in a different search base, you can optionally complete the Group Search Base. This field is dedicated to searching groups, but is not required.
+
+	:::

 1.	If your FreeIPA deviates from the standard AD schema, complete the **Customize Schema** form to match it. Otherwise, skip this step.

-	>**Search Attribute** The Search Attribute field defaults with three specific values: `uid|sn|givenName`. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.
-	>
-	>The default field value `uid|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields.
-	>
-	> * `uid`: User ID
-	> * `sn`: Last Name
-	> * `givenName`: First Name
-	>
-	> With this search attribute, Rancher creates search filters for users and groups, but you *cannot* add your own search filters in this field.
+	:::note Search Attribute
+	
+	The Search Attribute field defaults with three specific values: `uid|sn|givenName`. After FreeIPA is configured, when a user enters text to add users or groups, Rancher automatically queries the FreeIPA server and attempts to match fields by user id, last name, or first name. Rancher specifically searches for users/groups that begin with the text entered in the search field.
+	
+	The default field value `uid|sn|givenName`, but you can configure this field to a subset of these fields. The pipe (`|`) between the fields separates these fields.
+	
+	* `uid`: User ID
+	* `sn`: Last Name
+	* `givenName`: First Name
+	
+	With this search attribute, Rancher creates search filters for users and groups, but you *cannot* add your own search filters in this field.
+
+	:::

 1.	Enter your FreeIPA username and password in **Authenticate with FreeIPA** to confirm that Rancher is configured to use FreeIPA authentication.
 1. Click **Enable**.
@@ -5,7 +5,11 @@ weight: 1116

 In environments using GitHub, you can configure Rancher to allow sign on using GitHub credentials.

->**Prerequisites:** Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+:::note Prerequisites:
+
+Read [External Authentication Configuration and Principal Users]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/#external-authentication-configuration-and-principal-users).
+
+:::

 1.  Sign into Rancher using a local user assigned the `administrator` role (i.e., the _local principal_).
 1.	In the top left corner, click **☰ > Users & Authentication**.
@@ -13,17 +17,21 @@ In environments using GitHub, you can configure Rancher to allow sign on using G
 1. Click **GitHub**.
 1.	Follow the directions displayed to set up a GitHub Application. Rancher redirects you to GitHub to complete registration.

-	>**What's an Authorization Callback URL?**
-	>
-	>The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen).
+	:::note What's an Authorization Callback URL?
+	
+	The Authorization Callback URL is the URL where users go to begin using your application (i.e. the splash screen).

-	>When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application.
+	When you use external authentication, authentication does not actually take place in your application. Instead, authentication takes place externally (in this case, GitHub). After this external authentication completes successfully, the Authorization Callback URL is the location where the user re-enters your application.
+
+	:::

 1. From GitHub, copy the **Client ID** and **Client Secret**. Paste them into Rancher.

-	>**Where do I find the Client ID and Client Secret?**
-	>
-	>From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently.
+	:::note Where do I find the Client ID and Client Secret?
+	
+	From GitHub, select Settings > Developer Settings > OAuth Apps. The Client ID and Client Secret are displayed prominently.
+
+	:::

 1.	Click **Authenticate with GitHub**.

@@ -64,7 +64,11 @@ If you have an existing configuration using the SAML protocol and want to switch

    Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.

-    >**Note:** You may need to disable your popup blocker to see the IdP login page.
+    :::note
+    
+    You may need to disable your popup blocker to see the IdP login page.
+
+    :::

 **Result:** Rancher is configured to work with Keycloak using the OIDC protocol. Your users can now sign into Rancher using their Keycloak logins.

@@ -114,7 +118,11 @@ Before configuring Rancher to use Keycloak (OIDC), Keycloak (SAML) must be first

 Configure Rancher to use Keycloak (OIDC) by following the steps in [this section](#configuring-keycloak-in-rancher).

-> **Note:** After configuration is completed, Rancher user permissions will need to be reapplied as they are not automatically migrated.
+:::note
+
+After configuration is completed, Rancher user permissions will need to be reapplied as they are not automatically migrated.
+
+:::

 ## Annex: Troubleshooting

@@ -116,7 +116,11 @@ The following is an example process for Firefox, but will vary slightly for othe

    Rancher redirects you to the IdP login page. Enter credentials that authenticate with Keycloak IdP to validate your Rancher Keycloak configuration.

-    >**Note:** You may have to disable your popup blocker to see the IdP login page.
+    :::note
+    
+    You may have to disable your popup blocker to see the IdP login page.
+
+    :::

 **Result:** Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.

@@ -135,9 +139,13 @@ The following is an example process for Firefox, but will vary slightly for othe
 | Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP.                                                                            |
 | IDP-metadata              | The `metadata.xml` file that you exported from your IdP server.                                                                                          |

->**Tip:** You can generate a key/certificate pair using an openssl command. For example:
->
->        openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert
+:::tip
+
+You can generate a key/certificate pair using an openssl command. For example:
+
+openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert
+
+:::

 ## Annex: Troubleshooting

@@ -5,11 +5,13 @@ weight: 1205

 After you complete [Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/rancher/v2.6/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup/), enter your AD FS information into Rancher to allow AD FS users to authenticate with Rancher.

->**Important Notes For Configuring Your ADFS Server:**
-> 
->- The SAML 2.0 WebSSO Protocol Service URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs`
->- The Relying Party Trust identifier URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata`
->- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`
+:::note Important Notes For Configuring Your ADFS Server:
+ 
+- The SAML 2.0 WebSSO Protocol Service URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/acs`
+- The Relying Party Trust identifier URL is: `https://<RANCHER_SERVER>/v1-saml/adfs/saml/metadata`
+- You must export the `federationmetadata.xml` file from your AD FS server. This can be found at: `https://<AD_SERVER>/federationmetadata/2007-06/federationmetadata.xml`
+
+:::

 1.	In the top left corner, click **☰ > Users & Authentication**.
 1. In the left navigation menu, click **Auth Provider**.
@@ -19,8 +21,12 @@ After you complete [Configuring Microsoft AD FS for Rancher]({{<baseurl>}}/ranch

    Rancher redirects you to the AD FS login page. Enter credentials that authenticate with Microsoft AD FS to validate your Rancher AD FS configuration.

-    >**Note:** You may have to disable your popup blocker to see the AD FS login page.
+    :::note 
+    
+    You may have to disable your popup blocker to see the AD FS login page.

+    :::
+    
 **Result:** Rancher is configured to work with MS FS. Your users can now sign into Rancher using their MS FS logins.

 # Configuration