docs: under ref jaas, restore authc, authz, sec scope, and add rebac, plus fix links and spelling

tmihoc · tmihoc · commit 33859bbb5565 · 2025-03-24T09:43:11.000+01:00
diff --git a/.sphinx/spellingcheck.yaml b/.sphinx/spellingcheck.yaml
@@ -2,6 +2,7 @@ matrix:
 - name: rST files
   aspell:
     lang: en
+    # d: en_US
     d: en_GB
   dictionary:
     wordlists:
diff --git a/.wordlist.txt b/.wordlist.txt
@@ -2,6 +2,7 @@ addmodel
 addons
 auth
 authenticy
+authorization
 API
 APIs
 backend
@@ -26,6 +27,7 @@ hostname
 hostnames
 IAM
 installable
+Integrations
 JSON
 Juju
 Kubeflow
@@ -57,6 +59,7 @@ stateful
 subdirectories
 subfolders
 subtree
+superset
 Ubuntu
 UI
 UUID
diff --git a/howto/manage-juju-controllers.md b/howto/manage-juju-controllers.md
@@ -14,7 +14,8 @@ jimmctl remove-controller
 jimmctl set-controller-deprecated
 -->
 
-## Add a Juju controller to a JIMM controller
+(add-a-juju-controller)=
+## Add a Juju controller
 
 JIMM gives a centralised view of all models in the system. However the work of managing
 the models is delegated to a set of Juju controllers deployed in various clouds
@@ -32,8 +33,8 @@ a JIMM controller.
 For this tutorial you will need the following:
 
 - Basic knowledge of Juju
-- A JIMM controller deployed in MicroK8s, see {doc}`the tutorial <../tutorial/deploy_jaas_microk8s>`.
-- Administrator permission on the JIMM controller, see {doc}`bootstrapping permissions <./bootstrap_permissions>`.
+- A JIMM controller deployed in MicroK8s, see {doc}`the tutorial <../tutorial/index>`.
+<!--- Administrator permission on the JIMM controller, see {ref}`add-a-juju-controller`.-->
 
 
 ### Prelude
diff --git a/howto/manage-models.md b/howto/manage-models.md
@@ -10,8 +10,8 @@ In many scenarios it is necessary to migrate models to and from an environment t
 
 - A standalone Juju controller with a model (optionally with a running application).
 - A basic understanding of Juju model migrations, see the [docs](https://juju.is/docs/juju/manage-models).
-- A running JAAS, see the {doc}`tutorial <../tutorial/deploy_jaas_microk8s>`.
-- Administrator permissions for JAAS, see our {doc}`how-to <./bootstrap_permissions>`.
+- A running JAAS, see the {doc}`the tutorial <../tutorial/index>`.
+- Administrator permissions for JAAS, see our {doc}`how-to <./manage-your-jaas-deployment>`.
 
 ### 1. Create a new Juju controller
 
@@ -28,7 +28,7 @@ is required.
 In order to use models with JAAS, the models must be running on a Juju controller that is properly configured. The
 necessary config values cannot be set after bootstrap time, so any existing models must be migrated to a new controller.
 
-The process of creating a local Juju controller that is properly configured is described in {doc}`this how-to <./add_controller>`.
+The process of creating a local Juju controller that is properly configured is described in {ref}`add-a-juju-controller`.
 
 Once a Juju controller that is configured to communicate with JIMM has been created, move onto the next step.
 
@@ -104,10 +104,10 @@ The below is useful if you want to move the model to a specific controller.
 ### Prerequisites
 
 - A basic understanding of Juju model migrations, see the [docs](https://juju.is/docs/juju/manage-models).
-- A running JAAS with with multiple controllers attached, see the {doc}`tutorial <../tutorial/deploy_jaas_microk8s>` for deploying JAAS.
-- Administrator permissions for JAAS, so our {doc}`how-to <./bootstrap_permissions>`.
+- A running JAAS with with multiple controllers attached, see the {doc}`the tutorial <../tutorial/index>` for deploying JAAS.
+- Administrator permissions for JAAS, so our {ref}`add-a-juju-controller`.
 
-Connecting multiple controllers to JAAS can be accomplished adding LXD controllers as described in our {doc}`how-to <./add_controller>`.
+Connecting multiple controllers to JAAS can be accomplished adding LXD controllers as described in {ref}`add-a-juju-controller`.
 
 ### 1. Identify the new controller
 
diff --git a/howto/manage-service-accounts.md b/howto/manage-service-accounts.md
@@ -1,6 +1,6 @@
 (manage-service-accounts)=
 # Manage service accounts
-> See also: {ref}`service account`
+<!-->> See also: {ref}`service account`-->
 
 (manage-a-service-accounts-relation-to-an-entity)=
 ## Manage a service account's relation to an entity
diff --git a/howto/manage-your-jaas-deployment.md b/howto/manage-your-jaas-deployment.md
@@ -14,7 +14,7 @@ JAAS supports Juju controllers with a minimum version 3.4.
 ```
 
 
-TBA (for now please see the tutorial)
+TBA (for now please see {doc}`the tutorial <../tutorial/index>`)
 
 <!--
 To deploy JAAS:
@@ -127,8 +127,8 @@ juju config jimm juju-dashboard-location="<juju-dashboard-url>"
 
 For this how-to you will need the following:
 
-- A basic understanding of JAAS tags, see our {doc}`explanation doc<../explanation/jaas_tags>`.
-- A running JAAS environment, see {doc}`our tutorial <../tutorial/deploy_jaas_microk8s>`.
+- A basic understanding of JAAS tags, see {ref}`tag`.
+- A running JAAS environment, see {doc}`the tutorial <../tutorial/index>`.
 - An understanding of Juju permissions, see the [Juju docs](https://juju.is/docs/juju/user-permissions).
 
 ### Creating an admin user
@@ -183,7 +183,7 @@ For the complete list of components in COS, read the
 - A running `COS-Lite` bundle.
   You can follow the [Getting started on MicroK8s](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s).
   tutorial to get you started. Make sure to follow the section **Deploy the COS Lite bundle with overlays** section to create offers.
-- A running JAAS. Please refer to the deployment {doc}`tutorial<../tutorial/deploy_jaas_microk8s>`.
+- A running JAAS. Please refer to the deployment {doc}`the tutorial <../tutorial/index>`.
 
 ```{tip}
 [Juju offers](https://juju.is/docs/juju/manage-offers) are a way of sharing software as a service between models. Make sure you deploy COS and setup offers so that you can relate to it across models.
@@ -313,7 +313,8 @@ You will find the available dashboards by clicking on the Dashboards menu
 [cos]: https://charmhub.io/topics/canonical-observability-stack
 
 
-## Equip JAAS with TLS ingress
+(equip-your-jaas-deployment-with-tls-ingress)=
+## Equip your JAAS deployment with TLS ingress
 
 The NGINX Ingress Integrator is a charm responsible for creating Kubernetes ingress rules,
 these rules can be hardened via TLS and the charm provides a means to do so. See [here](https://charmhub.io/nginx-ingress-integrator).
@@ -341,7 +342,7 @@ To explore Juju Dashboard features you can go [here](https://juju.is/docs/juju/t
 
 For this how-to you will need the following:
 
-- A running JAAS environment, see {doc}`our tutorial <../tutorial/deploy_jaas_microk8s>`.
+- A running JAAS environment, see {doc}`the tutorial <../tutorial/index>`.
 
 ### Deploy Juju Dashboard
 
@@ -356,7 +357,7 @@ juju integrate dashboard jimm-app
 Then you need to expose your dashboard through an ingress.
 
 ```{tip}
-You can follow {doc}`this guide <./setup_ingress_with_tls>` to add TLS to your ingress.
+You can follow {ref}`equip-your-jaas-deployment-with-tls-ingress` to add TLS to your ingress.
 ```
 
 ```text
diff --git a/howto/use_terraform.md b/howto/use_terraform.md
@@ -11,9 +11,9 @@ For this how-to you will need the following:
 - An identity provider that can be used to create OAuth2.0 client credentials.
 - Client credentials (`client_id` and `client_secret`) generated by the above identity provider.
 - A deployed JAAS configured to trust the identity provider. For instructions on
-  how to deploy JIMM read {doc}`../tutorial/deploy_jaas_microk8s`.
+  how to deploy JIMM read {doc}`the tutorial <../tutorial/index>`.
 - A Juju controller added to JIMM that can be used to control your chosen cloud. For instructions
-  on how to add one read {doc}`add_controller`.
+  on how to add one read {ref}`add-a-juju-controller`.
 - A Juju client.
 - Cloud credentials for the chosen cloud (see [here](https://juju.is/docs/juju/manage-credentials)).
 - Basic knowledge of Terraform, Juju Terraform provider and Juju.
diff --git a/redirects.txt b/redirects.txt
@@ -20,10 +20,10 @@ explanation/jaas_tags/ reference/tag/
 reference/authorisation_model/ reference/jaas/authorisation_model/
 reference/authorisation_data/ reference/jaas/authorisation_data/
 reference/security/ reference/jaas/security/
-explanation/authentication/ reference/jaas/authentication/
-explanation/authorisation/ reference/jaas/authorisation/
+explanation/authentication/ reference/jaas/jaas-authentication/
+explanation/authorisation/ reference/jaas/jaas-authorization/
 explanation/jaas_architecture/ reference/jaas/jaas_architecture/
-explanation/jaas_security_scope/ reference/jaas/jaas_security_scope/
+explanation/jaas_security_scope/ reference/jaas/jaas-security-scope/
 howto/integrate_with_cos/ howto/manage-jimm-controllers/
 howto/migrate_models/ howto/manage-models/
 howto/migrate_models_internal/ howto/manage-models/
@@ -33,13 +33,13 @@ howto/setup_dashboard/ howto/manage-jimm-controllers/
 howto/bootstrap_permissions/ howto/manage-jimm-controllers/
 reference/jaas/authorisation_data/ reference/relation/
 reference/jaas/authorisation_model/ reference/relation/
-reference/jaas/authorisation/ reference/relation/
+reference/jaas/authorisation/ reference/jaas/jaas-authorization
 explanation/jaas_overview/ reference/jaas/jaas_architecture/
 howto/manage-jimm-controllers/ howto/manage-your-jaas-deployment/
 howto/setup_new_users/ howto/manage-users/
 reference/juju_required_version/ reference/jaas/supported-juju-versions/
-reference/jaas/authentication/ reference/jaas/security/
-reference/jaas/jaas_security_scope/ reference/jaas/security/
+# reference/jaas/authentication/ reference/jaas/security/
+# reference/jaas/jaas_security_scope/ reference/jaas/security/
 reference/jaas/security_hardening/ reference/jaas/security/
 reference/jaas/jaas_architecture/ reference/jaas/jaas-architecture/
 reference/jaas/security/ reference/jaas/jaas-security/
diff --git a/reference/audit_logs.md b/reference/audit_logs.md
@@ -16,7 +16,7 @@ Filtering audit logs is also possible along a variety of fields including but no
 user executing the request, model name and command.
 
 Finally, access to audit logs is, by default, only afforded to JIMM superusers i.e. administrators of JIMM.
-Read access to audit logs can be granted to other users via `jimmctl`, see {doc}`/tutorial/group_management`
+Read access to audit logs can be granted to other users via `jimmctl`, see {ref}`manage-groups`.
 
 ## Filter Logs
 
diff --git a/reference/jaas/jaas-architecture.md b/reference/jaas/jaas-architecture.md
@@ -1,3 +1,4 @@
+(jaas-architecture)=
 # Architecture
 
 The diagram below shows an overall picture of JAAS architecture.
@@ -32,7 +33,7 @@ The remainder of this document briefly goes into more detail on JAAS' deployment
 
 The components of JAAS are deployed via Juju K8s charms. This implies that in order to deploy JAAS, you
 must first bootstrap a single Juju controller to manage the components of JAAS, this is described in
-more detail in our {doc}`tutorial <../tutorial/deploy_jaas_microk8s>`.
+more detail in our {ref}`tutorial`.
 
 Not all the components of JAAS are expected to be deployed on Kubernetes. With the use of Juju [offers](https://juju.is/docs/juju/manage-offers)
 certain components can be deployed to virtual machines and used by the Kubernetes charms. These components
diff --git a/reference/jaas/jaas-authentication.md b/reference/jaas/jaas-authentication.md
@@ -0,0 +1,45 @@
+(jaas-authentication)=
+# Authentication
+
+As a brief refresher, authentication refers to the process of proving something to be true, in this case proving that
+the user logging in is who they say they are.
+
+This is one of the key features of JAAS. Where Juju controllers implement login via commonly understood username/password authentication,
+JAAS uses [OAuth 2.0](https://auth0.com/intro-to-iam/what-is-oauth-2) and [OIDC](https://developer.okta.com/blog/2019/10/21/illustrated-guide-to-oauth-and-oidc).
+While a full explanation of OAuth and OIDC are out of the scope of this document, you are likely already familiar with
+the benefits of these standards when you log into various services across the internet.
+
+These standards define how services can access your resources on your behalf and how services can authenticate your identity.
+When logging into a web application that employs OIDC you will commonly be asked to login via a different website or provider,
+like your email or social media provider and this information is then securely passed onto the original application.
+
+#3 Login Providers
+
+Because JAAS uses the OAuth 2.0/OIDC standard, theoretically various providers can be connected to JAAS and used as a login provider.
+However, due to the varying security practices and slight deviations from the standard, not all providers are supported with JAAS.
+
+Officially, JAAS supports [Ory Hydra](https://www.ory.sh/hydra/), a cloud native OAuth 2.0 and OIDC server. This is a key component of
+the [Canonical identity platform](https://charmhub.io/topics/canonical-identity-platform) which not only provides a standards compliant OAuth/OIDC server but also allows you to configure
+social sign-on via other OIDC compliant identity providers (e.g. Azure AD, Google, Okta, etc.).
+
+
+## Authentication Methods
+
+JAAS offers multiple OAuth 2.0 flows (a sequence of steps to login). Each of which is referred to as a **grant type**.
+
+**Authorisation Code grant**: This flow is the most common and used primarily by web applications. You will encounter this flow with JAAS when using
+the Juju dashboard. The login process will redirect your browser to JAAS' identity provider and ask you to login before redirecting you
+to the dashboard. At this point you have been authenticated and can use your resources through the graphical interface.
+
+**Device Code grant**: You will encounter this flow when using the Juju CLI with JAAS. If you are logging in for the first time or if your
+session has expired you will be prompted with URL and unique code. Navigating to the page will ask you to login and provide the code.
+During this time the CLI will continually ping the server until authentication is complete.
+
+## Sessions
+
+A brief mention on sessions is also important in the context of authentication. While JAAS authenticates a user by communicating with
+an external identity provider, this is neither performant nor would make a great user experience if a user were asked to log in after each interaction.
+
+To solve this, JAAS also provides users with their own application sessions. Depending on your authentication flow, your session with
+JAAS will last a varying amount of time until you are asked to log in again. This is a configurable option to cater for different
+organisational needs.
diff --git a/reference/jaas/jaas-authorization.md b/reference/jaas/jaas-authorization.md
@@ -0,0 +1,24 @@
+(jaas-authorization)=
+# Authorization
+
+JAAS provides enterprise-level features on top of Juju. One such features is enhanced authorization, which provides enterprises with more control over user permissions to access underlying Juju resources (e.g. controllers or models). JAAS utilises [Relationship-Based Access Control (ReBAC)](https://en.wikipedia.org/wiki/Relationship-based_access_control) by using [OpenFGA](https://openfga.dev/) as the back-end service for ReBAC. You can read more about Juju's permission model in [here](https://juju.is/docs/juju/user-permissions).
+
+
+## What is ReBAC?
+
+Unlike [Role-Based Access Control (RBAC)](https://en.wikipedia.org/wiki/Role-based_access_control) where permission sets are managed by the concept of *roles*, in ReBAC, a user's access to a resource is modelled through a *relation*, which can be either direct or indirect (the result of another relation). This makes ReBAC more dynamic in comparison to RBAC, and also more suitable for complex authorization schemes where there are large number of users and resources.
+
+As an example, consider a simple file-system structure with two kinds of resources: directories and files. Without ReBAC, you need to be explicit about every user's permissions (or set of permissions, as roles) to every file or directory. But, with ReBAC, you can achieve the same result with much less effort and data, by defining the right relations. For instance, you can assign the `read::directory:foo` relation to a user (meaning that the user has `read` relation to the `directory` named `foo`), and then the user will have the read access to all files and directories under `foo`. Note that, you only declared *one* relationship (or more precise, *tuple*), and the other relations are automatically inferred from that.
+
+
+## JAAS authorization components
+
+Conceptually, the JAAS authorization system consists of two main components:
+
+1. **authorization model**, which defines the schema of different entity types (e.g. controllers, users, or groups), the possible relationships between them (e.g. group memberships, or administrator relation for controllers), and the inheritance structure for permissions (e.g. a controller administrator is also an administrator for all models on that controller).
+
+2. **Tuples (or relationship data)**, which represent a set of individual relationships between concrete entities (e.g., a user named *foo* is an *admin* of a controller named *bar*).
+
+Inherently, the authorization model is a static component and cannot be changed by the administrators of JAAS. On the other hand, the tuples, are dynamic data and JAAS provides tools for administrators to manipulate them.
+
+> See more: {ref}`relation`
diff --git a/reference/jaas/jaas-rebac-admin-backend.md b/reference/jaas/jaas-rebac-admin-backend.md
@@ -3,14 +3,6 @@
 The ReBAC Admin API is a REST API that provides various endpoints to query or
 manipulate relationships in JAAS ReBAC authorisation model.
 
-```{tip}
-For an explanation on Relationship-Based Access Control (ReBAC) check out {doc}`this <../explanation/authorisation>` explanation topic.
-```
-
-```{tip}
-As a reference on JAAS authorisation model, check out {doc}`this <../reference/authorisation_model>` reference topic.
-```
-
 ## OpenAPI specification
 
 The OpenAPI spec can be found at `https://<jimm-deployment>/rebac/v1/swagger.json`
@@ -29,6 +21,6 @@ JAAS implements a subset of the operations described in the OpenAPI spec.
 | ✅  | `capabilities` ||
 | ✅  | `groups` ||
 | ✅  | `resources` ||
+| ✅  | `roles`      ||
 | 🟡  | `identities`  |   No support for creation, update and deletion.|
-| ❌  | `roles`      |    No support for roles.|
 | ❌  | `authentication` | No support for identity provider management.|
diff --git a/reference/jaas/jaas-security-scope.md b/reference/jaas/jaas-security-scope.md
@@ -0,0 +1,44 @@
+# Security Scope
+
+<!--   TODO (Kian):
+   Much of this document's content is now covered in the security doc in reference/security and reused where possible.
+   We should consider what parts of this doc to remove and where to better put the parts that we keep.
+-->
+
+The scope of JAAS' security covers multiple aspects, including:
+
+## Secure Communication
+
+JAAS ensures secure communication between controllers (management nodes) and models (namespaces)
+by means of authorisation, authentication and TLS encryption to prevent unauthorised access
+and prevent data interception or tampering.
+
+Additionally, when communicating with any controller, JAAS uses token based authorisation whilst
+additionally acting as the IdP (Identity Provider) for said tokens.
+
+## Access control and authentication
+
+JAAS provides an abstraction layer of access control on top of Juju. JAAS does this by backing its users
+with an IdP (Identity Provider). Various identity providers can be used for this purpose (e.g. Google or Microsoft).
+We recommend the [Canonical identity platform](https://charmhub.io/topics/canonical-identity-platform) as the preferred IdP for JAAS. The IdP will handle user
+authentication on behalf of JAAS using OAuth 2.0 and OIDC. For authorisation, JAAS provides this by means
+of tags and ReBAC (Relation-Based Access Control).
+
+See the following pages for more details on how JAAS provides {ref}`jaas-authentication` and {ref}`jaas-authorization`.
+
+## Auditing and logging
+
+JAAS provides audit logs of all access to each model managed by JAAS, including information on which user
+performed the action. Currently, JAAS does not provide a way to view the logs of applications within models.
+
+## Model and user isolation
+
+JAAS, like Juju, enables users with the correct cloud credentials associated with their user
+to create models [under that clouds controller] for different applications, services, and
+environments via the JAAS controller.
+
+## Secure storage and handling of secrets
+
+User provided cloud credentials are stored securely and safely within a secret vault. It is
+essential to handle these secrets securely to prevent unauthorised access and data breaches
+to the users cloud.
diff --git a/reference/jaas/jaas-security.md b/reference/jaas/jaas-security.md
diff --git a/reference/relation.md b/reference/relation.md
diff --git a/reference/service-account.md b/reference/service-account.md
diff --git a/tutorial/index.md b/tutorial/index.md
