docs: Update instructions for latest Kanidm security requirements

Also general doc updates and better formatting for readability.

Author: jinnatar

README.md

@@ -3,8 +3,7 @@
 i.e. How to connect legacy web apps that only support SAML to be backed by Kanidm OIDC. While the configs in this repo can be educational for rolling your own SATOSA setup, an opinionated ENV configurable container image is also provided.
 
 > [!CAUTION]
-> This is an early version that only supports a 1:1 proxy config where a single SAML supporting web service auths via a single OIDC endpoint.
-> The intent is to morph into a "v2" that allows a dynamic mapping of multiple systems to multiple OIDC endpoints via a single SAML proxy. The simpler version will be preserved for educational purposes but is intended to become "legacy".
+> This example on purpose only supports a 1:1 proxy config where a single SAML supporting web service auths via a single OIDC endpoint. To limit blast radius, just deploy multiple if you have multiple SAML-only services.
 
 ## TODO items on the roadmap
 1. Get rid of the idpyoidc git build once there's a release that contains ES256 support.
@@ -15,7 +14,7 @@ i.e. How to connect legacy web apps that only support SAML to be backed by Kanid
 The container built at `ghcr.io/jinnatar/satosa-saml-proxy:latest` is a proof of concept using the SATOSA configs in the repo. The guides below will assume you are using it, but nothing prevents you from using the same configs and ENV config with any other supported SATOSA installation method. I am using the container myself in my environment and have a vested interest in keeping it going and tested.
 
 The caveats with the container and/or trying to go without it:
-- While recent releases of SATOSA support PKCE, they depend on the Python library `idpyoidc` for this. Unfortunately it has an issue that prevents using ES256 for signing with released versions. The container thus uses [a branch from git](https://github.com/IdentityPython/idpy-oidc/tree/issuer_metadata) that contains the fix for this. Once a full release is made with said fix that will be used specifically. Once SATOSA requires a high enough release of `idpyoidc` that contains a fix, we can stop with this nonsense altogether.
+- While recent releases of SATOSA support PKCE, they depend on the Python library `idpyoidc` for this. Unfortunately it has an issue that prevents using `ES256` for signing with released versions. The container thus uses [a branch from git](https://github.com/IdentityPython/idpy-oidc/tree/issuer_metadata) that contains the fix for this. Once a full release is made with said fix that will be used specifically. Once SATOSA requires a high enough release of `idpyoidc` that contains a fix, we can stop with this nonsense altogether.
 - The containers are now version tagged as per SATOSA upstream versions. However, due to the above nonsense those tags will be updated later when better build provenance is available.
 
 ### Container config options
@@ -67,23 +66,35 @@ SAML is a bit *involved* so we need to prep a persistent certificate and provide
 ### Practical example: Ceph SSO via Kanidm
 1. Pre-create your users in Ceph to give them the correct authz. In this example we'll use short usernames for simplicity so that needs to match.
 1. Create your Kanidm OIDC configuration the usual way, no need to disable PKCE!
-   ```
-   kanidm system oauth2 create ceph Ceph https://saml.example.com  # **Important**, give the proxy URL here.
-   kanidm system oauth2 prefer-short-username ceph # Use short usernames for convenience
-   kanidm system oauth2 update-scope-map ceph ceph_admins openid profile email  # Create the scope map, don't forget to create the group and add your Ceph admins to it.
-   kanidm system oauth2 show-basic-secret ceph  # Get your client_secret for use later on.
+   ```shell
+   # **Important** give the upstream Ceph landing page URL here:
+   kanidm system oauth2 create ceph Ceph https://ceph.example.com
+
+   # **Important** give the proxy callback URL here. The full value depends on $OIDC_NAME:
+   kanidm system oauth2 add-redirect-url ceph https://ceph-saml.example.com/oidc_ceph
+
+   # Use short usernames for convenience
+   kanidm system oauth2 prefer-short-username ceph
+
+   # Create the scope map, don't forget to create the group and add your Ceph admins to it.
+   kanidm system oauth2 update-scope-map ceph ceph_admins openid profile email  
+
+   # Get your client_secret for use later on:
+   kanidm system oauth2 show-basic-secret ceph
    ```
 1. Create your SAML2 certs and set their permissions as per the generic steps above, nothing special here.
 1. We can't get Ceph to spit out it's metadata XML before the proxy is functioning so we skip ahead.
 1. Config your ENV variables into a new env file, `ceph.env`. If you don't change the ENCRYPTION_KEY value you deserve everything you get as a result.
    ```shell
-   LOG_LEVEL=debug  # Enables debug logging for troubleshooting. Change this to "info" when everything works!
+   # Enables debug logging for troubleshooting. Change this to "info" when everything works!
+   LOG_LEVEL=debug
    ENCRYPTION_KEY=+OSDGTYdWxesiUwcMEzaGzwCx81YHhzOFgsitMn9A/c=
    OIDC_CLIENT_ID=ceph
-   OIDC_CLIENT_SECRET=# You got this above from kanidm
+   # The client secret you got in a previous step: 
+   OIDC_CLIENT_SECRET=
    OIDC_ISSUER_URL=https://idm.example.com/oauth2/openid/ceph
    OIDC_NAME=oidc_ceph
-   PROXY_BASE_URL=https://saml.example.com
+   PROXY_BASE_URL=https://ceph-saml.example.com
    SAML_METADATA=dummy-metadata.xml
    SAML_NAME=saml_ceph
    ```
@@ -96,7 +107,10 @@ SAML is a bit *involved* so we need to prep a persistent certificate and provide
    ```
 1. Register the proxy with Ceph, giving it the Ceph URL, SAML metadata endpoint and an attribute field name to expect for the username.
    ```shell
-   ceph dashboard sso setup saml2 https://ceph.example.com https://saml.example.com/saml_ceph/metadata.xml urn:oid:0.9.2342.19200300.100.1.1
+   ceph dashboard sso setup saml2 \
+    https://ceph.example.com \
+    https://ceph-saml.example.com/saml_ceph/metadata.xml \
+    urn:oid:0.9.2342.19200300.100.1.1
    ```
 1. Assuming registration was succesful, we can now get the Ceph side SAML metadata:
    ```shell
@@ -111,4 +125,4 @@ SAML is a bit *involved* so we need to prep a persistent certificate and provide
     ghcr.io/jinnatar/satosa-saml-proxy:latest
     ```
 
-1. Restart the proxy and go test Ceph SSO!
+1. Restart the proxy and go test Ceph SSO! Once it's all working, amend your env one more time to set `LOG_LEVEL=info`!