Merge pull request #81 from rackerlabs/extend-auth

docs: add authorization information to docs

docs/auth.md

@@ -1,4 +1,4 @@
-# Authentication
+# Authn / Authz
 
 You must configure how users and operators will authenticate against the various services
 provided by Understack. At this time [Dex IdP](https://dexidp.io) is used for all the
@@ -12,12 +12,14 @@ services and a connector must be configured to provide authentication.
     `domain` key in the `keystone_internal` section to the UUID of the `operator`
     domain.
 
-## Azure OIDC
+## User Authentication
+
+### Azure OIDC
 
 To use Azure OIDC support you must first create an Azure Entra Application Registration
 and configure it for OIDC authentication.
 
-### Azure App Registration
+#### Azure App Registration
 
 1. From the `Azure Entra` > `App registrations` menu, choose `New registration`.
 2. Enter a Name for the application (e.g. Undercloud).
@@ -31,13 +33,13 @@ You will then make a note of the following pieces of information for your applic
 - Application ID or Client ID (same value, two different names) we'll call this `{client_id}`.
 - Directory ID or Tenant ID (same value, two different names) we'll call this `{tenant_id}`.
 
-### Azure App Secret
+#### Azure App Secret
 
 1. From the `Certificates & secrets` menu, choose `New client secret`
 2. Enter a Name for the secret (e.g. Undercloud-SSO).
 3. Copy and save this value and we'll use it for the `{client_secret}`.
 
-### Azure Dex Configuration
+#### Azure Dex Configuration
 
 In `clusters/${DEPLOY_NAME}/components/dexidp.yaml` under the `valuesFiles` key
 add `$values/components/dexidp/values-azure.yaml` beneath  `values-generic.yaml`
@@ -71,7 +73,30 @@ kubectl --namespace dex \
 
 You must remember to commit this file to your `${UC_DEPLOY}` repo.
 
-## Static Users
+### Static Users
 
 Users can be created in OpenStack Keystone in the `operator` domain for
 testing purposes.
+
+## User Authorization
+
+Once users can authenticate to the system, they must be granted authorization
+to different parts of the system. The default groups through the system are:
+
+- ucadmin - administrator of the system
+- dctech - DC Tech with access to physical systems
+- neteng - Network Engineer with access to IPAM and Network configuration
+- user - consumer of resources and hardware provided by the system
+
+### Nautobot
+
+To customize the administrator group set the following in your
+`helm-configs/${DEPLOY_NAME}/nautobot.yaml`
+
+```yaml title=helm-configs/${DEPLOY_NAME}/nautobot.yaml
+nautobot:
+  extraEnvVars:
+    # ignoring existing values here, don't remove
+    - name: DEX_SUPERUSER_GROUPS
+      value: your-admin-group
+```

docs/gitops-install.md

@@ -158,6 +158,8 @@ values files or kustomize patches. This should be considered a rough template
 that is yours to modify. Once you've made all the changes you want to make,
 ensure that you `git push` your `$UC_DEPLOY` repo so that ArgoCD can access it.
 
+For authentication, please review the [authentication](auth.md) documentation.
+
 For OpenStack Helm components, an empty file in `$UC_DEPLOY/helm-configs/my-k3s`
 has been created for each component for you to use for customization.