diff --git a/docs/config.md b/docs/config.md index 2848ce431aaec2b8ba6b644f8b0a7ea2bcf29727..2832ad8446ff61d636b576df011853e17d8c1a52 100644 --- a/docs/config.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index ca1e30b4cfc70ed11aebd85dfb10e2025193963b..93c254b59927d2136e65885ab9fbf28973056b61 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,23 @@ -# 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 diff --git a/docs/roles.md b/docs/roles.md new file mode 100644 index 0000000000000000000000000000000000000000..e5f052cb626ca881f42635fcf78b8a9a22d62e60 --- /dev/null +++ b/docs/roles.md @@ -0,0 +1,15 @@ +# 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