oidc-fastapi-test/README.md

# OIDC test application

*oidc-test* is a simple web application for testing different OIDC providers,
and a template for Python FastAPI.

It has been tested with some OIDC providers like Auth0 (public),
Keycloak (private), Forgejo (private and public with Codeberg).

It should work with Google, Azure and other cloud services providing
an OIDC authentication service.

It is a *stateless* application (no data are saved and it restarts as vanilla),
and there is no database connection,
although models are defined with the SQLModel library and it is designed
as a template for integration in other FastAPI/SQLModel applications.

Feedback welcome.

## Resource server

It also functions as a resource server in a OAuth architecture.
See a sibling test project, a web based OIDC/OAuth:
[oidc-vue-test](https://code.philo.ydns.eu/philorg/oidc-vue-test).

## RBAC

The application is also a playground for RBAC (Role Based Access control)
implemented with OIDC.
The application has few different resources (web pages) for testing RBAC.
The home page checks (with Javascript) if those are accessible
by the end user for convenience, color-coding the links to those pages.

2 roles are defined in the application: foorole and barrole.

If the user has these roles defined in the ID provider and they are exposed
in the `userinfo` endpoint,
the return code of these pages should be HTTP success (200).

If the user does not have the required role(s),
a HTTP access denied (401) code is returned.

## Deployment

A Python package and a container are provided.

## Configuration

The application reads a simple `yaml` file that you should configure
to expose different login options in the application's "Login" box, with values
given by the OIDC providers.

For example:

```yaml
oidc:
  secret_key: "ASecretNoOneKnows"
  show_session_details: yes
  providers:
    - id: auth0
      name: Okta / Auth0
      url: "https://<your_auth0_app_URL>"
      client_id: "<your_auth0_client_id>"
      client_secret: "client_secret_generated_by_auth0"
      hint: "A hint for test credentials"

    - id: keycloak
      name: Keycloak at somewhere
      url: "https://<the_keycloak_realm_url>"
      account_url_template: "/account"
      client_id: "<your_keycloak_client_id>"
      client_secret: "client_secret_generated_by_keycloak"
      hint: "User: foo, password: foofoo"

    - id: codeberg
      name: Codeberg
      url: "https://codeberg.org"
      account_url_template: "/user/settings"
      client_id: "<your_codeberg_client_id>"
      client_secret: "client_secret_generated_by_codeberg"
      resources:
        - name: List of repos
          id: repos
          url: /api/v1/user/repos
        - name: List of OAuth2 applications
          id: oauth2_applications
          url: /api/v1/user/applications/oauth2

cors_origins:
  - https://some.client
  - https://localhost:8000
```

The application reads the `OIDC_TEST_SETTINGS_FILE` environment variable
to determine the location of this file at startup.

For example, to run on port 8000 in a container,
with the setting file in the current working directory:

```sh
podman run -p 8000:80 --env OIDC_TEST_CONFIG_FILE=/app/settings.yaml --mount type=bind,source=settings.yaml,destination=/app/settings.yaml code.philo.ydns.eu/philorg/oidc-fastapi-test:latest
```