add JAAS security doc

.custom_wordlist.txt

@@ -10,6 +10,8 @@ Charmhub
 CLI
 CN
 config
+CORS
+CSRF
 Diátaxis
 DNS
 dropdown
@@ -24,6 +26,7 @@ GitHub
 Google
 Grafana
 HAProxy
+HMAC
 https
 IAM
 IdP
@@ -36,6 +39,9 @@ JSON
 juju
 Juju
 Juju's
+JWKS
+JWT
+JWTs
 K8s
 Keystore
 Kratos
@@ -85,7 +91,9 @@ ReBAC
 reST
 reStructuredText
 roadmap
+RSA
 RTD
+SHA
 Skype
 Snapcraft
 SSH
@@ -108,4 +116,5 @@ VMs
 webhook
 Websocket
 Xbox
+XSRF
 YAML

.wordlist.txt

@@ -1,16 +1,22 @@
 addmodel
 addons
+auth
+authenticy
 API
 APIs
+backend
 balancer
 Charmhub
+cryptographic
+cryptographically
 CLI
 Diátaxis
 dropdown
 EBS
 EKS
 enablement
 favicon
+filesystem
 Furo
 Git
 GitHub

explanation/jaas_security_scope.rst

@@ -1,6 +1,11 @@
 JAAS 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

reference/index.rst

@@ -1,7 +1,15 @@
 Reference
 =========
 
-**Technical information** - specifications, APIs, and reference docs.
+**Technical information** - security, APIs, and reference docs.
+
+Security
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   JAAS Security <security>
 
 .. toctree::
    :maxdepth: 1

reference/security.rst

@@ -0,0 +1,254 @@
+JAAS Security Overview
+=======================
+
+This document provides an overview of JAAS security measures, focusing on areas related to 
+sensitive data storage, transmission, and cryptographic technologies.
+
+Cloud Credentials
+-----------------
+
+Cloud credentials are API keys used by Juju/JAAS to provision cloud infrastructure. 
+These credentials are securely uploaded to and stored by JAAS. 
+When a model is created, the key is passed to the Juju controller to manage cloud resources.
+
+User-provided cloud credentials are stored securely in a `Vault <https://www.vaultproject.io/>`__, 
+a tool for managing secrets. Ensuring the secure handling of these credentials is essential 
+to prevent unauthorised access or data breaches.
+
+Vault encrypts credentials at rest and provides mechanisms to prevent unauthorised access.
+
+JAAS - Juju Communication
+--------------------------
+
+JAAS acts as an authentication gateway between users and Juju controllers. 
+Juju controllers trust JAAS by setting the ``login-token-refresh-url`` during bootstrap.
+More information on setting up a Juju controller for JAAS can be found in our :doc:`how-to guide <../how-to/add_controller>`.
+
+Trust between Juju controllers and JAAS is established through asymmetric cryptography 
+and `JSON Web Tokens (JWTs) <https://jwt.io/introduction>`__.
+
+.. hint::
+    While JWTs are also used for user sessions, the tokens exchanged between JAAS and Juju controllers are separate from user tokens.
+
+The ``login-token-refresh-url`` points to a 
+`JSON Web Key Set (JWKS) <https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets>`__
+endpoint, containing public keys used to verify tokens issued by JAAS.
+
+The JWKS public and private key pair are generated at startup and placed in Vault.
+The keys are then periodically rotated.
+
+When JAAS makes requests to a Juju controller, a JWT is issued that encodes user information 
+and permissions, securely delegating authentication and authorisation from the controller to JAAS.
+
+Details:
+
+- **JWKS Endpoint**: ``<jimm-url>/.well-known/jwks.json``
+- **Key Type/Size**: RSA 4096 bits
+- **Signing Algorithm**: RS256
+
+The following Go packages are used:
+
+- ``github.com/lestrrat-go/jwx/v2/jwa``
+- ``github.com/lestrrat-go/jwx/v2/jwt``
+- ``github.com/lestrrat-go/jwx/v2/jwk``
+
+User Sessions
+-------------
+
+CLI-Based Sessions
+^^^^^^^^^^^^^^^^^^
+
+When authenticating the Juju CLI to JAAS, users go through an OAuth login flow, 
+(see `Device Code Flow`_) after which the CLI is issued a JWT as an application 
+session token. This token is stored on the filesystem and sent with each request,
+eliminating the need for repeated logins.
+
+While Juju controller tokens use asymmetric cryptography, session tokens for 
+users are signed using symmetric cryptography (i.e., a shared secret) with a 
+cryptographic hash function. A symmetric-key signature is used here because only 
+JAAS needs to verify the token.
+
+The shared secret is generated by the JIMM charm operator using Juju secrets
+and passed to the application.
+
+JWTs for CLI sessions contain the user's email address, so they must be secured 
+to prevent information leakage and malicious account use.
+
+Details:
+
+- **Key Size**: >=512 bits
+- **Signing Algorithm**: HS256
+
+The following Go packages are used:
+
+- ``github.com/lestrrat-go/jwx/v2/jwt``
+- ``github.com/lestrrat-go/jwx/v2/jwa``
+
+Browser Cookies
+^^^^^^^^^^^^^^^
+
+In the Juju dashboard, session management is handled using cookies, which store 
+cryptographically encoded values that allow the server to retrieve session data.
+Like CLI sessions, JAAS uses symmetric cryptography with a shared secret.
+
+Unlike the CLI session tokens, browser session cookies only store an encoded 
+session ID rather than personal user information like email addresses.
+While they do not store user information, they must still be kept safe to prevent 
+malicious account use.
+
+The shared secret is generated by the JIMM charm operator using Juju secrets
+and passed to the application.
+
+Details:
+
+- **Key Size**: >=512 bits
+- **Signing Algorithm**: HMAC-SHA256
+
+The following Go packages are used:
+
+- ``github.com/gorilla/sessions``
+- ``github.com/antonlindstrom/pgstore``
+
+OIDC Authentication
+-------------------
+
+JAAS uses OAuth 2.0 and OpenID Connect (OIDC) for user authentication. 
+You can learn more from this `overview <https://developer.okta.com/docs/concepts/oauth-openid/>`__.
+
+The following Go packages are used:
+
+- ``golang.org/x/oauth2``
+- ``golang.org/x/oauth2/clientcredentials``
+- ``github.com/coreos/go-oidc/v3/oidc``
+
+Authorisation Code Flow
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In a browser-based login, users follow the `authorisation code flow <https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow>`__.
+Upon successful login, the access and refresh tokens are stored on the backend, 
+and a session cookie is issued to the user's browser as described in `Browser Cookies`_.
+
+To protect against `CSRF attacks <https://auth0.com/docs/secure/attack-protection/state-parameters>`__,
+the backend issues a random nonce in the ``state`` parameter of the OAuth authorisation code flow.
+
+Device Code Flow
+^^^^^^^^^^^^^^^^
+
+For CLI logins, the `device code flow <https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow>`__
+is used, where the Juju CLI prompts the user to log in via a browser with a random code. The backend 
+stores access and refresh tokens, and the CLI receives an application session token.
+
+This process does not rely on browser redirects and is not susceptible to traditional browser vulnerabilities.
+
+Client Credential Flow
+^^^^^^^^^^^^^^^^^^^^^^
+
+For machine-to-machine authentication, the 
+`client credentials flow <https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow>`__
+is used. However, in JAAS, the client application sends its credentials to JAAS, which proxies them to the identity provider.
+A good example of this includes the Juju Terraform Provider where the client-credential flow is employed.
+
+This scheme simplifies authentication for client applications but is only possible since JAAS is a trusted
+application in the system.
+
+Macaroons & Offer Authentication
+--------------------------------
+
+Macaroons are a tool for decentralised authentication similar to JSON Web Tokens.
+The `Go Macaroon package <https://pkg.go.dev/gopkg.in/[email protected]>`__ is used by JAAS and has more
+details on the low-level operations that Macaroons are capable of.
+
+Macaroons are used by Juju for various purposes but in JAAS their primary purpose is for authorising 
+cross-model relations between controllers. When two Juju controllers (that are connected to JAAS) 
+communicate for the purposes of sharing an application offer, JAAS acts as the source of truth for 
+authorisation data. These checks are handled using macaroons.
+
+Macaroons use a combination of HMAC for cryptographic signatures and symmetric encryption to encode
+the scope (or caveats) of what a macaroon is entitled to.
+
+These operations are performed using ``HMAC-SHA256`` and ``XSalsa20-Poly1305``. The following Go 
+packages are used by the underlying macaroon package for these operations:
+
+.. hint::
+
+  For those new to Go, the ``crypto/hmac`` and ``crypto/sha256`` packages below
+  are included in the Go standard library.
+
+- ``crypto/hmac``
+- ``crypto/sha256``
+- ``golang.org/x/crypto/nacl/secretbox``
+
+Additionally, the higher-level `Macaroon Bakery package <https://github.com/go-macaroon-bakery/macaroon-bakery>`__
+is used to interface with macaroons and introduces public key cryptography to perform similar operations
+as mentioned above. This allows services to trust macaroons generated externally.
+
+These operations are performed using ``Ed25519`` and ``XSalsa20-Poly1305``. The following Go packages are 
+used by the underlying macaroon bakery package for these operations:
+
+- ``golang.org/x/crypto/nacl/box``
+- ``golang.org/x/crypto/curve25519``
+
+When a Juju controller is connected to JAAS, the ``login-token-refresh-url`` is used to determine where 
+the JAAS macaroon public key is located. This public key is used when Juju controllers issue macaroons 
+and enforces that the macaroon can only be  discharged by JAAS, who holds the private key. Discharging 
+a macaroon refers to the process of verifying its claims.
+
+Specific details are below:
+
+- **Macaroon Public Key endpoint:** ``<jimm-url>/macaroons/publickey``
+- **Key Type:** Ed25519 (256-bit key)
+- **Signing algorithm:** Ed25519
+
+TLS Communication
+-----------------
+
+TLS encryption is enforced between various components in JAAS, using Go's standard 
+library (``crypto/tls`` and ``crypto/x509``). The minimum supported version is TLS v1.2.
+
+Client - JAAS
+^^^^^^^^^^^^^
+
+The GO Juju client enforces TLS for all connections to JAAS, including the 
+Juju CLI and Juju Terraform Provider.
+
+JAAS - Juju Controllers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+JAAS enforces TLS when connecting to Juju controllers.
+
+JAAS - OpenFGA
+^^^^^^^^^^^^^^
+
+TLS is not currently enforced between JAAS and OpenFGA due to a lack of TLS support in the OpenFGA charm operator.
+
+JAAS - Vault
+^^^^^^^^^^^^
+
+JAAS assumes TLS is used to communicate with Vault. 
+The Vault charm uses TLS by default.
+
+JAAS - PostgreSQL
+^^^^^^^^^^^^^^^^^
+
+JAAS does not enforce TLS when communicating with PostgreSQL, but 
+it can be enabled when using the PostgreSQL charm.
+TLS is not enabled by default.
+
+CORS
+----
+
+CORS or Cross-Origin Resource Sharing is a browser security feature designed to prevent 
+malicious use of your online credentials. Read more about CORS 
+`here <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#what_requests_use_cors>`__.
+
+JAAS supports the use of CORS headers specifically for the Juju dashboard. The dashboard
+requires the ability to send cross-origin requests from the domain where it is hosted to
+the domain where JAAS is hosted. More information on how to set up CORS to securely handle
+these requests will be available in a future how-to guide.
+
+..
+  TODO(Kian): update the above paragraph after we have a deploy dashboard how-to.
+
+The following Go package is used to validate CORS requests:
+
+- ``github.com/rs/cors``