Tighten Up Service Roles

Reduce priviliges for services that require access to identities and
physical networks.  These need to be read, to extract readiness and
provider specific information, and deleted for cluster cleanup.
Additionally add in a new endpoint for fine grain API control of the
region service.  Finally document service accounts.

README.md

@@ -276,6 +276,30 @@ spec:
   - [email protected]
 ```
 
+### Service Organization
+
+When using an integration such as the [Unikorn Kubernetes Service](https://github.com/unikorn-cloud/kubernetes) you will need to create a service organization and groups in order for them to function.
+
+Taking Kubernetes cluster provisioning as an example, the provisioner is a Kubernetes controller that needs access to the region API in order to check the provisioning status of cloud identities, and possibly physical networks, before proceeding.
+Additionally it needs provider specific information from those resources to pass to the cluster provisioner.
+
+As these APIs are protected by oauth2 it needs a way to first acquire an access token, as it has no access to the requesting user's.
+To solve this problem we use the oauth2 `client_credentials` grant to authenticate the Kubernetes service against the Identity service.
+This takes the form of mutual-TLS authentication as defined by RFC-8705.
+
+When the access token is then passed to the Region service, it will authenticate the token against the Identity service, then it needs to retrieve the ACL to perform RBAC related checks on the API endpoints.
+For that reason, we need an organization and a group containing the client service user, mapping to a role that allows API access.
+
+The steps to create a service organization are exactly as described above:
+
+* Create an organization, e.g. `system` or `service`
+* Create a group for that service
+  * The group contains explicit user names e.g. `unikorn-kubernetes` as defined in the X.509 client certificate's common name (CN)
+  * The group defines a role relevant to that service e.g. `infra-manager-service`
+
+Individual services will document their CN and role requirements.
+All official Unikorn Cloud services will have their roles pre-defined by this repository.
+
 ## What Next?
 
 As you've noted, objects are named based on UUIDs, therefore administration is somewhat counterintuitive, but it does allow names to be mutable.

charts/identity/Chart.yaml

@@ -4,8 +4,8 @@ description: A Helm chart for deploying Unikorn's IdP
 
 type: application
 
-version: v0.2.31
-appVersion: v0.2.31
+version: v0.2.32
+appVersion: v0.2.32
 
 icon: https://raw.githubusercontent.com/unikorn-cloud/assets/main/images/logos/dark-on-light/icon.png
 

charts/identity/values.yaml

@@ -84,16 +84,18 @@ roles:
         projects: [create,read,update,delete]
         regions: [create,read,update,delete]
         identities: [create,read,update,delete]
+        physicalnetworks: [create,read,update,delete]
         kubernetesclustermanagers: [create,read,update,delete]
         kubernetesclusters: [create,read,update,delete]
-  # A region admin is a role primarily for the Kubernetes service that
-  # can manage identities and physical networks on behalf of a cluster.
-  region-admin:
-    decription: Region administrator
+  # An infrastructure manager service is a role primarily for Kubernetes like
+  # services that can manage identities and physical networks on behalf of a cluster.
+  infra-manager-service:
+    decription: Infrastructure manager service
     scopes:
       global:
-        regions: [create,read,update,delete]
-        identities: [create,read,update,delete]
+        regions: [read]
+        identities: [read,delete]
+        physicalnetworks: [read,delete]
   # An administrator can do anything within an organization.
   adminstrator:
     description: Organization administrator
@@ -106,6 +108,7 @@ roles:
         projects: [create,read,update,delete]
         regions: [read]
         identities: [create]
+        physicalnetworks: [create]
         kubernetesclustermanagers: [create,read,update,delete]
         kubernetesclusters: [create,read,update,delete]
   # A user can view projects they are a member of and
@@ -118,6 +121,7 @@ roles:
       project:
         projects: [read]
         identities: [create]
+        physicalnetworks: [create]
         kubernetesclustermanagers: [read]
         kubernetesclusters: [create,read,update,delete]
   # A reader can view projects they are a member of and view