106 lines
5.1 KiB
Markdown
106 lines
5.1 KiB
Markdown
# keycloak-collective-portal
|
|
|
|
> **WARNING**: this software is in a pre-alpha quality state and is an initial
|
|
> prototype. It is being developed within the context of
|
|
> [lumbung.space](https://lumbung.space/) and may have hard-coded values and
|
|
> configuration specifically for that environment. If the idea of this software
|
|
> sounds interesting to you, please let us know on the issue tracker!
|
|
|
|
[](https://drone.autonomic.zone/autonomic-cooperative/keycloak-collective-portal)
|
|
|
|
> Community Keycloak SSO user management
|
|
|
|
This is a small Python app that allows you to create custom web pages, outside
|
|
of the Keycloak administration interface, which can be used to manage users in
|
|
Keycloak. This is done via the REST API. It was designed with collective
|
|
management in mind. Existing Keycloak users can authenticate with the app and
|
|
then do things like invite others, send verification emails and so on. Anything
|
|
that the REST API supports, this app can support. We aim to strive for the
|
|
usability which is often lacking in Enterprise Software ™ environments
|
|
(Keycloak is made within the context of RedHat / IBM). This is the No Admins,
|
|
No Masters edition of Keycloak.
|
|
|
|
## Feature set
|
|
|
|
- **invite links** ([demo video](https://matrix.autonomic.zone/_matrix/media/r0/download/autonomic.zone/HRQwVkAwGdxIwaqFhUttbckB)):
|
|
- Any collective member with an existing Keycloak account can log in and generate them
|
|
- They are valid for 30 days by default (configurable via `INVITE_TIME_LIMIT`)
|
|
- Anyone with an invite link can create an account on the Keycloak, so don't share publicly!
|
|
- There is no access granularity on the account creation implemented yet, so the accounts are "global"
|
|
- **New**: it is possible to only allow "admins" to log in, see [feature flags](#feature-flags)
|
|
- Once the user fills in their name, email, password they will receive an email verification mail
|
|
|
|
If you want a feature implemented, please open an issue to discuss.
|
|
|
|
## Getting Started
|
|
|
|
### From a system administrator perspective
|
|
|
|
A note on permissions: we use the `admin-cli` client and a fine grained, secure
|
|
access configuration for making requests from this app to your Keycloak
|
|
instance. We aim to follow the Keycloak documentation and recommended practices
|
|
on security so that `keycloak-colective-portal` is a safe option to add into
|
|
your technology stack.
|
|
|
|
- Ensure that your `admin-cli` client under your Client settings has the following config:
|
|
- **Settings tab**:
|
|
- **Client authentication**: `ON`
|
|
- **Service Accounts Roles**: `ON`
|
|
- **Authentication flow**: Make sure "Standard flow" is checked
|
|
- **Valid redirect URIs**: `https://{your keycloak-collective-portal domain}/auth/keycloak`
|
|
- **Scope tab**:
|
|
- **Full scope allowed**: `OFF`
|
|
- **Service Account Roles tab**:
|
|
- Click "To manage detail and group mappings, click on the username service-account-admin-cli", then "Role mappings", "Assign role", then change the dropdown to "Filter by clients", and add `realm-management:manage-users`, `realm-management:view-users`, `account:manage-account` and `account:view-profile`
|
|
- Deploy using [`coop-cloud/keycloak-colective-portal`](https://git.autonomic.zone/coop-cloud/keycloak-collective-portal)
|
|
- See the example [.env.sample](.env.sample) for the configuration available, more documentation will follow soon.
|
|
|
|
### From a collective member perspective
|
|
|
|
- Visit `https://<your-portal-url>` (ask your system adminstrator friends)
|
|
- Log in with your usual login details
|
|
- Follow the instructions on the web page to perform administrative actions
|
|
|
|
## Feature Flags
|
|
|
|
### Only admins can log in
|
|
|
|
#### Keycloak
|
|
|
|
- Create a new group under `Groups` called `Administrators` (case sensistive!)
|
|
- Create a new scope under `Client scopes`
|
|
- Name: `groups`
|
|
- Type: `Optional`
|
|
- Include in token scope: `yes`
|
|
- Under the `Mappers` tab of this client scope, choose `Add mapper`
|
|
- Mapper type/Name: `Groups Membership`
|
|
- Token claim name: `groups`
|
|
- Add to ID token: `yes`
|
|
- Add to access token: `yes`
|
|
- Add to userinfo: `yes`
|
|
- Add this client scope to your `admin-cli` client as `Optional`
|
|
- Add a test user to this group under `Users`
|
|
|
|
#### Keycloak Community Portal
|
|
|
|
- Set `FEATURE_FLAG_ADMINS_ONLY=True` in your `.env`
|
|
- You may want to customise `KEYCLOAK_GROUPS_KEY` / `KEYCLOAK_ADMINS_GROUP` if
|
|
you changed the value of `groups` / `Administrators` above
|
|
|
|
## Hacking
|
|
|
|
It's a [FastAPI](https://fastapi.tiangolo.com/) application (if you know
|
|
[Flask](https://flask.palletsprojects.com/en/2.0.x/) /
|
|
[Sanic](https://sanic.readthedocs.io/en/stable/) then it is more or less the
|
|
same thing). Currently being developed with Python 3.9. Once we move out of the
|
|
prototype stage, more version compatability will be offered. You'll need a
|
|
working Keycloak install as well to fill in correct `.env` values. A more
|
|
covenient development environment will come along shortly too.
|
|
|
|
```
|
|
$ docker run -p 6379:6379 -d redis:6-alpine
|
|
$ cp .env.sample .env # fill with real values
|
|
$ set -a && source .env && set +a
|
|
$ make
|
|
```
|