Add developer getting started guide

README.md

@@ -58,7 +58,7 @@ docker run -v $(pwd):/src \
 
 # What is it?
 
-Dashboard is "stateless" client for the Rancher APIs built with [Vue.js](https://vuejs.org/) and [NuxtJS](https://nuxtjs.org/).  It is normally build and packaged as a folder of static HTML/CSS/JS files which are bundled into a Rancher release, with the index.html returned by the API server as the "fallback" case for any request that looks like it came from a browser and does not match an API URL.
+Dashboard is "stateless" client for the Rancher APIs built with [Vue.js](https://vuejs.org/) and [NuxtJS](https://nuxtjs.org/).  It is normally built and packaged as a folder of static HTML/CSS/JS files which are bundled into a Rancher release, with the index.html returned by the API server as the "fallback" case for any request that looks like it came from a browser and does not match an API URL.
 
 Every k8s type, namespace, and operation that the logged in user has been granted access to is shown to them.  The default view for everything is the raw YAML from the k8s API for detail pages, and the `Table` view column data for list pages (i.e. what you get from `kubectl get <type> -o wide`).
 
@@ -129,7 +129,7 @@ There are lots of different APIs available in Rancher, but the primary two are [
       - "Watches" to find out when a resource changes are aggregated into a single websocket which keeps track of what's connected and can resume the stream, rather than many independent calls to the native k8s implementation
       - The "counts" resource internally watches everything to keep track of how many of every type of resource there are in every namespace and state, which allows us to show all the types that are "in use" and how many there are in the left nav.
       - Schemas and links on each resource efficiently identify what permissions the user making the request has, so that actions in the UI can be hidden or disabled if not allowed for the current user instead of letting them try and having the server reject it.
-      - Normalizing the differnet and sometimes inconsistent state/status/conditions data from resources into a single logical view of the world the UI can present.
+      - Normalizing the different and sometimes inconsistent state/status/conditions data from resources into a single logical view of the world the UI can present.
       - RPC-style actions to do more complicated workflows on the server side when appropriate
 
 ### Endpoints
@@ -195,24 +195,6 @@ We have no concrete plans for this, but can envision several situations where we
 
 To disable it for the whole server for development, add `--spa`.  To disable it for a single page load, add `?spa` (or `&spa`) to the query string.  It is harder, but possible, to write something that works in SSR but breaks in SPA, so these are good for debugging issues.
 
-### Multiple GitHub auth configs
-The auth system supports multiple GitHub auth URLs and using the appropriate one based on the Host header that a request comes in on.  Configuring this is not exposed in the regular UI, but is particularly useful for development against a server that already has GitHub setup.
-
-In `management.cattle.io.authconfig`, edit the `github` entry.  Add a `hostnameToClientId` map of Host header value -> GitHub client ID:
-
-```yaml
-hostnameToClientId:
-  "localhost:8005": <your GitHub Client ID for localhost:8005>
-```
-
-In the `secret`, namespace `cattle-global-data`, edit `githubconfig-clientsecret`.  Add GitHub client ID -> base64-encoded client secret to the `data` section:
-
-```yaml
-data:
-  clientsecret: <the normal client secret already configured>
-  <your client id>: <your base64-encoded client secret for localhost:8005>
- ```
-
 License
 =======
 Copyright (c) 2014-2021 [Rancher Labs, Inc.](http://rancher.com)

docs/developer/auth-providers.md

@@ -0,0 +1,48 @@
+# Auth Providers
+
+## Github
+
+### Developer Set up
+Follow the in-dashboard instructions when configuring a Github auth provider.
+
+### Multiple GitHub auth configs
+The auth system supports multiple GitHub auth URLs and using the appropriate one based on the Host header that a request comes in on.  Configuring this is not exposed in the regular UI, but is particularly useful for development against a server that already has GitHub setup.
+
+In `management.cattle.io.authconfig`, edit the `github` entry.  Add a `hostnameToClientId` map of Host header value -> GitHub client ID:
+
+```yaml
+hostnameToClientId:
+  "localhost:8005": <your GitHub Client ID for localhost:8005>
+```
+
+In the `secret`, namespace `cattle-global-data`, edit `githubconfig-clientsecret`.  Add GitHub client ID -> base64-encoded client secret to the `data` section:
+
+```yaml
+data:
+  clientsecret: <the normal client secret already configured>
+  <your client id>: <your base64-encoded client secret for localhost:8005>
+ ```
+
+## Keycloak
+
+### Developer Set Up
+Use the steps below to set up a Keycloak instance for dev environments and configure an Auth Provider for it.
+
+1. Bring up a local Keycloak instance in docker using the instructions at [here](https://www.keycloak.org/getting-started/getting-started-docker).
+
+   > Ensure that the admin user has a first name, last name and email. These fields are referenced in the Keycloak client's mappers which are then referenced in the Rancher's auth provider config.
+
+   > Double check the client has the correct checkboxes set, specifically the Mappers `group` entry.
+1. Using either the Ember or Vue UI set up the Keycloak auth provider by follow the instructions at [here](https://rancher.com/docs/rancher/v2.x/en/admin-settings/authentication/keycloak/)
+   | Field | Value |
+   |-------|-------|
+   | Display Name Field | givenName |
+   | User Name Field | email |
+   | UID Field | email |
+   | Groups Field| member |
+   | Entity ID Field| Depending on Rancher API Url. For instance when running Dashboard locally `https://192.168.86.26:8005/v1-saml/keycloak/saml/metadata` |
+   | Rancher API Host | Depending on Rancher API Url. For instance when running Dashboard locally `https://192.168.86.26:8005/`|
+   | Private Key | For key and cert files, export the Client in the Keycloak UI via the `Clients` list page and extract & wrap the `saml.signing.certificate` and `saml.signing.private.key` as cert files (see [step 5](https://gist.github.com/PhilipSchmid/506b33cd74ddef4064d30fba50635c5b) for more info). |
+   | Certificate | See Private Key section above|
+   | Metadata | For the SAML Metadata, export the Client in the Keycloack UI via the `Installation` tab as `SAML Metadata SPSSODescriptor` and then follow the `NOTE` instructions regarding `EntitiesDescriptor` and `EntityDescriptor`. For a better set of instructions see [step 6](https://gist.github.com/PhilipSchmid/506b33cd74ddef4064d30fba50635c5b)|
+

docs/developer/getting-started/README.md

@@ -0,0 +1,11 @@
+# Getting Started
+
+This guide is intended for developers new to Rancher and the Dashboard. It will be expanded over time and we welcome contributions.
+
+First take some time to understand the [README](../../../README.md). This covers a lot of useful information that this document references and supplements. It's helpful reviewing the `README` once again after experience is gained and concepts are more familiar.
+
+## Contents
+
+1. [Terminology](./terminology.md)
+1. [Development Environment](./development_environment.md)
+1. [Development](./development.md)