PR comments

reference/security.rst

@@ -39,7 +39,7 @@ and permissions, securely delegating authentication and authorisation from the c
 
 **Details**:
 
-- **JWKS endpoint**: ``<jimm-url>/.well-known/jwks.json``
+- **JWKS Endpoint**: ``<jimm-url>/.well-known/jwks.json``
 - **Key Type/Size**: RSA 4096 bits
 - **Signing Algorithm**: RS256
 
@@ -49,6 +49,9 @@ The following Go packages are used:
 - ``github.com/lestrrat-go/jwx/v2/jwt``
 - ``github.com/lestrrat-go/jwx/v2/jwk``
 
+The public and private key pairs are generated at startup and placed in Vault.
+Thee keys are periodically rotated.
+
 User Sessions
 -------------
 
@@ -76,27 +79,33 @@ The following Go packages are used:
 - ``github.com/lestrrat-go/jwx/v2/jwt``
 - ``github.com/lestrrat-go/jwx/v2/jwa``
 
+The shared secret is generated by the JIMM charm operator using Juju secrets
+and passed to the application.
+
 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.
 
-**Details**:
-
-- **Key Size**: >=512 bits
-- **Signing Algorithm**: ``HMAC-SHA256``
-
 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.
 
+**Details**:
+
+- **Key Size**: >=512 bits
+- **Signing Algorithm**: ``HMAC-SHA256``
+
 The following Go packages are used:
 
 - ``github.com/gorilla/sessions``
 - ``github.com/antonlindstrom/pgstore``
 
+The shared secret is generated by the JIMM charm operator using Juju secrets
+and passed to the application.
+
 OIDC Authentication
 -------------------
 
@@ -123,17 +132,18 @@ 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. The backend stores access 
-and refresh tokens, and the CLI receives a session token.
+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 a session token.
 
-This process does not rely on browser redirects and so is not susceptible to traditional browser vulnerabilities.
+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.
@@ -156,6 +166,11 @@ 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 stdlib.
+
 - ``crypto/hmac``
 - ``crypto/sha256``
 - ``golang.org/x/crypto/nacl/secretbox``
@@ -227,6 +242,8 @@ JAAS supports the use of CORS headers specifically for the Juju dashboard. The d
 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 update the above paragraph after we have a deploy dashboard how-to.
 
 The following Go package is used to validate CORS requests: