Merge pull request #1299 from rancher/staging

v2.2 Docs

Author: Denise

content/os/v1.x/en/about/running-rancher-on-rancherOS/_index.md

@@ -37,7 +37,7 @@ rancher:
 ```
 <br>
 
-> **Note:** You can not name the service `rancher-agent` as this will not allow the rancher/agent container to be launched correctly. Please read more about why [you can't name your container as `rancher-agent`](https://rancher.com/docs/rancher/v1.6/en/faqs/agents/#adding-in-name-rancher-agent).
+> **Note:** You can not name the service `rancher-agent` as this will not allow the rancher/agent container to be launched correctly. Please read more about why [you can't name your container as `rancher-agent`]({{< baseurl >}}/rancher/v1.6/en/faqs/agents/#adding-in-name-rancher-agent).
 
 ### Adding in Host Labels
 

content/rancher/v2.x/en/admin-settings/_index.md

@@ -1,9 +1,43 @@
 ---
-title: Administration
+title: Global Configuration
 weight: 1100
 aliases:
   - /rancher/v2.x/en/concepts/global-configuration/
   - /rancher/v2.x/en/tasks/global-configuration/
+  - /rancher/v2.x/en/concepts/global-configuration/server-url/
+  - /rancher/v2.x/en/tasks/global-configuration/server-url/
+  - /rancher/v2.x/en/admin-settings/server-url/
+  - /rancher/v2.x/en/admin-settings/log-in/
 ---
 
-After installation, the system administrator should configure Rancher to configure security, default settings, and user access.
+After installation, the [system administrator]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/global-permissions/) should configure Rancher to configure authentication, authorization, security, default settings, security policies, drivers and global DNS entries.
+
+## First Log In
+
+After you log into Rancher for the first time, Rancher will prompt you for a **Rancher Server URL**.You should set the URL to the main entry point to the Rancher Server. When a load balancer sits in front a Rancher Server cluster, the URL should resolve to the load balancer. The system will automatically try to infer the Rancher Server URL from the IP address or host name of the host running the Rancher Server. This is only correct if you are running a single node Rancher Server installation. In most cases, therefore, you need to set the Rancher Server URL to the correct value yourself.
+
+>**Important!** After you set the Rancher Server URL, we do not support updating it. Set the URL with extreme care.
+
+## Authentication
+
+One of the key features that Rancher adds to Kubernetes is centralized user authentication. This feature allows to set up local users and/or connect to an external authentication provider. By connecting to an external authentication provider, you can leverage that provider's user and groups.
+
+For more information how authentication works and how to configure each provider, see [Authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/).
+
+## Authorization
+
+Within Rancher, each person authenticates as a _user_, which is a login that grants you access to Rancher. Once the user logs in to Rancher, their _authorization_, or their access rights within the system, is determined by the user's role. Rancher provides built-in roles to allow you to easily configure a user's permissions to resources, but Rancher also provides the ability to customize the roles for each Kubernetes resource.
+
+For more information how authorization works and how to customize roles, see [Roles Based Access Control (RBAC)]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/).
+
+## Pod Security Policies
+
+_Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification, e.g. root privileges. If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message.
+
+For more information how to create and use PSPs, see [Pod Security Policies]({{< baseurl >}}/rancher/v2.x/en/admin-settings/pod-security-policies/).
+
+## Provisioning Drivers
+
+Drivers in Rancher allow you to manage which providers can be used to provision [hosted Kubernetes clusters]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/hosted-kubernetes-clusters/) or [nodes in an infrastructure provider]({{< baseurl >}}/rancher/v2.x/en/cluster-provisioning/rke-clusters/node-pools/) to allow Rancher to deploy and manage Kubernetes.
+
+For more information, see [Provisioning Drivers]({{< baseurl >}}/rancher/v2.x/en/admin-settings/drivers/).

content/rancher/v2.x/en/admin-settings/authentication/_index.md

@@ -1,6 +1,6 @@
 ---
 title: Authentication
-weight: 1110
+weight: 1115
 aliases:
     - /rancher/v2.x/en/concepts/global-configuration/authentication/
     - /rancher/v2.x/en/tasks/global-configuration/authentication/
@@ -12,9 +12,9 @@ This centralized user authentication is accomplished using the Rancher authentic
 
 <!-- todomark add diagram -->
 
-### External vs. Local Authentication
+## External vs. Local Authentication
 
-The Rancher authentication proxy integrates with the following external authentication services. The following table lists the first version of Rancher each service debuted. 
+The Rancher authentication proxy integrates with the following external authentication services. The following table lists the first version of Rancher each service debuted.
 
 | Auth Service                                                                                     | Available as of  |
 | ------------------------------------------------------------------------------------------------ | ---------------- |
@@ -26,13 +26,21 @@ The Rancher authentication proxy integrates with the following external authenti
 | [Microsoft AD FS]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/) | v2.0.7           |
 | [PingIdentity]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/ping-federate/)     | v2.0.7           |
 | [Keycloak]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/keycloak/)              | v2.1.0           |
-
+| [Okta]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/okta/)                      | v2.2.0           |
 <br/>
-However, Rancher also provides local authentication.
+However, Rancher also provides [local authentication]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/local/).
+
+In most cases, you should use an external authentication service over local authentication, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if Active Directory is down.
+
+## Users and Groups
+
+Rancher relies on users and groups to determine who is allowed to log in to Rancher and which resources they can access. When authenticating with an external provider, groups are provided from the external provider based on the user. These users and groups are given specific roles to resources like clusters, projects, multi-cluster apps, and global DNS providers and entries. When you give access to a group, all users who are a member of that group in the authentication provider will be able to access the resource with the permissions that you've specified. For more information on roles and permissions, see [Role Based Access Control]({{< baseurl >}}/rancher/v2.x/en/admin-settings/rbac/).
+
+> **Note:** Local authentication does not support creating or managing groups.
 
-In most cases, you should use an external authentication service over local, as external authentication allows user management from a central location. However, you may want a few local authentication users for managing Rancher under rare circumstances, such as if Active Directory is down.
+For more information, see [Users and Groups]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/user-groups/)
 
-### External Authentication Configuration and Principal Users
+## External Authentication Configuration and Principal Users
 
 Configuration of external authentication requires:
 

content/rancher/v2.x/en/admin-settings/authentication/azure-ad/_index.md

@@ -122,12 +122,10 @@ 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).
-       >
-       > ![Reply URL Example]({{< baseurl >}}/img/rancher/azure-reply-url.png)
 
 1. Click **Save**.
 
-**Result:** Your reply URL is saved. 
+**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.
 
@@ -179,13 +177,13 @@ Enter the values that you copied to your [text file](#tip).
 
 1. Select **Azure AD**.
 
-1. Complete the **Configure Azure AD Account** form using the information you copied while completing [Copy Azure Application Data](#4-copy-azure-application-data).
+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>
 
-    The following table maps the values you copied in the Azure portal to the fields in Rancher. 
+    The following table maps the values you copied in the Azure portal to the fields in Rancher.
 
     | Rancher Field      | Azure Value                           |
     | ------------------ | ------------------------------------- |

content/rancher/v2.x/en/admin-settings/authentication/keycloak/_index.md

@@ -58,13 +58,7 @@ If your organization uses Keycloak Identity Provider (IdP) for user authenticati
 
 **Result:** Rancher is configured to work with Keycloak. Your users can now sign into Rancher using their Keycloak logins.
 
->**Keycloak Identity Provider Caveats:**
->
->- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
->- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other  user IDs that may match.
->- When adding groups, you *must* select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
->
->   - The group drop-down shows *only* the groups that you are a member of. You will not be able to add groups that you are not a member of.
+{{< saml_caveats >}}
 
 ## Annex: Troubleshooting
 

content/rancher/v2.x/en/admin-settings/authentication/local/_index.md

@@ -1,12 +1,16 @@
 ---
-title: Configuring Local Authentication
+title: Local Authentication
 weight: 1111
 aliases:
     - /rancher/v2.x/en/tasks/global-configuration/authentication/local-authentication/
 ---
 
+Local authentication is the default until you configure an external authentication provider. Local authentication is where Rancher stores the user information, i.e. names and passwords, of who can log in to Ranchehr. By default, the `admin` user that logs in to Rancher for the first time is a local user.
+
+## Adding Local Users
+
 Regardless of whether you use external authentication, you should create a few local authentication users so that you can continue using Rancher if your external authentication service encounters issues.
 
-1.	From the **Global** view, select **Users** from the main menu.
+1.	From the **Global** view, select **Users** from the navigation bar.
 
 2.	Click **Add User**. Then complete the **Add User** form. Click **Create** when you're done.

content/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/_index.md

@@ -30,12 +30,7 @@ Setting up Microsoft AD FS with Rancher Server requires configuring AD FS on you
 - [1 — Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)
 - [2 — Configuring Rancher for Microsoft AD FS]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/rancher-adfs-setup)
 
->**Active Directory Federation Service Caveats:**
->
->- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
->- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other  user IDs that may match.
->- When adding groups, you *must* select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
->   - The group drop-down shows *only* the groups that you are a member of. You will not be able to add groups that you are not a member of.
+{{< saml_caveats >}}
 
 
 ### [Next: Configuring Microsoft AD FS for Rancher]({{< baseurl >}}/rancher/v2.x/en/admin-settings/authentication/microsoft-adfs/microsoft-adfs-setup)

content/rancher/v2.x/en/admin-settings/authentication/okta/_index.md

@@ -0,0 +1,50 @@
+---
+title: Configuring Okta (SAML)
+weight: 1210
+---
+
+_Available as of v2.2.0_
+
+If your organization uses Okta Identity Provider (IdP) for user authentication, you can configure Rancher to allow your users to log in using their IdP credentials.
+
+## Prerequisites
+
+In Okta, create a SAML Application with the settings below. See the [Okta documentation](https://developer.okta.com/standards/SAML/setting_up_a_saml_application_in_okta) for help.
+
+Setting | Value    
+------------|------------
+`Single Sign on URL` | `https://yourRancherHostURL/v1-saml/okta/saml/acs`
+`Audience URI (SP Entity ID)` | `https://yourRancherHostURL/v1-saml/okta/saml/metadata`
+
+## Configuring Okta in Rancher
+
+1.	From the **Global** view, select **Security > Authentication** from the main menu.
+
+1.	Select **Okta**.
+
+1.	Complete the **Configure Okta Account** form. The examples below describe how you can map Okta attributes to fields within Rancher.
+
+    | Field                     | Description                                                                   |
+    | ------------------------- | ----------------------------------------------------------------------------- |
+    | Display Name Field        | The attribute that contains the display name of users.                    |
+    | User Name Field           | The attribute that contains the user name/given name.                     |
+    | UID Field                 | An attribute that is unique to every user.                 |
+    | Groups Field              | Make entries for managing group memberships.                                 |
+    | Rancher API Host          | The URL for your Rancher Server.                                              |
+    | Private Key / Certificate | A key/certificate pair to create a secure shell between Rancher and your IdP. |
+    | Metadata XML              | The `Identity Provider metadata` file that you find in the application `Sign On` section.  |
+
+    >**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.crt
+
+
+1. After you complete the **Configure Okta Account** form, click **Authenticate with Okta**, which is at the bottom of the page.
+
+    Rancher redirects you to the IdP login page. Enter credentials that authenticate with Okta IdP to validate your Rancher Okta configuration.
+
+    >**Note:** If nothing seems to happen, it's likely because your browser blocked the pop-up. Make sure you disable the pop-up blocker for your rancher domain and whitelist it in any other extensions you might utilize.
+
+**Result:** Rancher is configured to work with Okta. Your users can now sign into Rancher using their Okta logins.
+
+{{< saml_caveats >}}

content/rancher/v2.x/en/admin-settings/authentication/ping-federate/_index.md

@@ -45,9 +45,4 @@ If your organization uses Ping Identity Provider (IdP) for user authentication,
 
 **Result:** Rancher is configured to work with PingIdentity. Your users can now sign into Rancher using their PingIdentity logins.
 
->**Ping Identity Provider Caveats:**
->
->- SAML Protocol does not support search or lookup for users or groups. Therefore, there is no validation on users or groups when adding them to Rancher.
->- When adding users, the exact user IDs (i.e. `UID Field`) must be entered correctly. As you type the user ID, there will be no search for other  user IDs that may match.
->- When adding groups, you *must* select the group from the drop-down that is next to the text box. Rancher assumes that any input from the text box is a user.
->   - The group drop-down shows *only* the groups that you are a member of. You will not be able to add groups that you are not a member of.
+{{< saml_caveats >}}