More docs

docs/config.md

@@ -26,4 +26,42 @@ dbp_relay_auth:
     frontend_keycloak_realm: ~ # Example: client-docs
     # The ID for the keycloak client (authorization code flow) used for API docs or similar
     frontend_keycloak_client_id: ~ # Example: client-docs
-```
\ No newline at end of file
+```
+
+## Configuration Discovery
+
+The auth bundle requires for the OIDC server to implement [OpenID Connect
+Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) as well
+as the metadata defined in the [OAuth 2.0 Authorization Server
+Metadata](https://datatracker.ietf.org/doc/html/rfc8414).
+
+Example: https://auth-demo.tugraz.at/auth/realms/tugraz-vpu/.well-known/openid-configuration
+
+
+## Token Validation Modes
+
+There are two modes of operation:
+
+* **Local validation** (default): The bundle fetches (and caches) the public
+  singing key from the OIDC server and verifies the access token signature (and
+  all other properties like expiration dates) in process. The has the upside of
+  being a fast, but has the downside of not taking token revocation into
+  account, so should only be used if the access tokens lifetime isn't too long.
+  Another extra requirement is that the system clock of the gateway and the OIDC
+  server shouldn't deviate too much to avoid valid tokens being marked as
+  expired or not valid yet.
+
+* **Remote validation**: The bundle passes the access token to the OIDC server
+  introspection endpoint for each request. This adds overhead to each request but
+  everything is handled by the OIDC server.
+
+
+## Frontend Keycloak Config (FIXME)
+
+At this time the bundle is still depending on Keycloak as a specific OIDC server
+for some optional functionality. The auth bundle handles the OIDC login
+component of the OpenAPI docs provided by the core bundle (the login button at
+the top left).
+
+We are looking into providing a frontend web component that works with all OIDC
+serves to remove this dependency.

docs/index.md

-# About
\ No newline at end of file
+# Overview
+
+The auth bundle connects the core bundle with an OIDC server. For each request
+it validates the passed access token, creates a Symonfy user and assigns Symfony
+roles to that user.
+
+```mermaid
+graph LR
+    style auth_bundle fill:#606096,color:#fff
+
+    oidc_server("OIDC Server")
+
+    subgraph API Gateway
+        api(("API"))
+        core_bundle("Core Bundle")
+        auth_bundle("Auth Bundle")
+    end
+
+    api --> core_bundle
+    core_bundle --> auth_bundle
+    auth_bundle --> core_bundle
+    auth_bundle --> oidc_server
+```
\ No newline at end of file

docs/roles.md

+# Custom Roles Mapping
+
+The auth bundle provides a default Symfony service implementing the
+`UserRolesInterface` interface which translates OAuth2 token scopes into Symfony
+roles. By default it creates roles with the prefix `ROLE_SCOPE_` and appends the scopes in uppercase.
+
+Examples:
+
+* `my-scope` → `ROLE_SCOPE_MY-SCOPE`
+* `MyScope`  → `ROLE_SCOPE_MYSCOPE`
+
+You can override this by registering your own symfony service which implements
+`UserRolesInterface` and implementing the `getRoles()` method. There you can
+change the mapping and also inject roles from other sources, like LDAP for
+example.
\ No newline at end of file