Skip to content

Latest commit

 

History

History
130 lines (83 loc) · 6.65 KB

README.md

File metadata and controls

130 lines (83 loc) · 6.65 KB
Raw

emeis

Build Status Coverage Black License: GPL-3.0-or-later

A generic user management service.

The word emeis ([e̞ˈmis]) comes from greek (εμείς) and means we.

Original RFC that led to emeis

Configuration

It's important to configure the app before the first start. When running for the first time, there is a data migration, that depends on settings from the config.

emeis is a 12factor app which means that configuration is stored in environment variables. Different environment variable types are explained at django-environ.

Common

A list of configuration options which you might need to configure to get emeis started in your environment.

General
  • SECRET_KEY: A secret key used for cryptography. This needs to be a random string of a certain length. See more.
  • ALLOWED_HOSTS: A list of hosts/domains your service will be served from. See more.
Database
  • DATABASE_ENGINE: Database backend to use. See more. (default: django.db.backends.postgresql)
  • DATABASE_HOST: Host to use when connecting to database (default: localhost)
  • DATABASE_PORT: Port to use when connecting to database (default: 5432)
  • DATABASE_NAME: Name of database to use (default: emeis)
  • DATABASE_USER: Username to use when connecting to the database (default: emeis)
  • DATABASE_PASSWORD: Password to use when connecting to database
i18n
  • LANGUAGE_CODE: Language code of the default language (default: en)
  • LANGUAGES: A list of supported languages (default: [en])

Additional options

Additional options you might want to configure

Metainfo fields

Emeis supports custom properties on all models via the metainfo JSON fields containing key-value pairs.

If you want to support ordering of such custom fields, add the respective keys to the EMEIS_META_FIELDS setting.

OIDC

For OIDC, a customized mozilla-django-oidc is used.

Most of the settings below are documented in it's respective documentation.

  • OIDC_OP_USER_ENDPOINT: Url of userinfo endpoint (see spec)
  • OIDC_VERIFY_SSL: Bool (default: true)
  • OIDC_BEARER_TOKEN_REVALIDATION_TIME: Time in seconds before bearer token validity is verified again. For best security, token is validated on each request per default. It might be helpful though in case of slow Open ID Connect provider to cache it. It uses cache mechanism for memorizing userinfo result. Number has to be lower than access token expiration time. (default: 0)
  • OIDC_CREATE_USER: Enables or disables automatic user creation during authentication (default: false). If set to false, users have to be created manually in emeis with the username set to the value that will be received in the OIDC_USERNAME_CLAIM.
  • OIDC_UPDATE_USER: Enables or disables updating of the user email address based on the email claim (default: false)
  • OIDC_USERNAME_CLAIM: Name of claim that contains the username (default: sub). This is needed for matching users from the received claims.
  • OIDC_EMAIL_CLAIM: Name of claim that contains the email address (default: email). This is only needed if OIDC_CREATE_USER or OIDC_UPDATE_USER are true
  • OIDC_OP_INTROSPECT_ENDPOINT: Url of introspection endpoint (optionally needed for Client Credentials Grant)
  • OIDC_RP_CLIENT_ID: ID of the client (optionally needed for Client Credentials Grant)
  • OIDC_RP_CLIENT_SECRET: Secret of the client (optionally needed for Client Credentials Grant)
  • EMEIS_OIDC_USER_FACTORY: Optional, factory function (or class) that defines an OIDC user object. See also here: Extending Emeis
Cache
  • CACHE_BACKEND: cache backend to use (default: django.core.cache.backends.locmem.LocMemCache)
  • CACHE_LOCATION: location of cache to use
CORS headers

Per default no CORS headers are set but can be configured with following options.

  • CORS_ORIGIN_ALLOW_ALL: If True, the whitelist will not be used and all origins will be accepted. (default: False)
  • CORS_ORIGIN_WHITELIST: A list of origin hostnames (including the scheme and with optional port) that are authorized to make cross-site HTTP requests.
Logging
  • LOG_LEVEL: The logging level of the console logging handler (default: INFO)
Anonymous write
  • ALLOW_ANONYMOUS_WRITE: If set to true, unauthenticated users are allowed to write data (default: false)

Their request will also go through the permission layer and access can be restricted/denied from there.

This setting can be handy when setting up emeis or during development, when no OIDC provider is available.

This should always be false in production environments.

Installation

Requirements

  • docker
  • docker-compose

After installing and configuring those, download docker-compose.yml and run the following command:

# only needs to be run once
echo UID=$UID > .env

docker-compose up -d

This will build the containers, start the services and run the database migrations. Additionally, it creates a user, scope, role and and ACL for administration based on the settings documented above

Getting started

You can now access the api at http://localhost:8000/api/v1/.

Read more about extending and configuring Emeis here: Extending Emeis.

Contributing

Look at our contributing guidelines to start with your first contribution.

Maintainer's Handbook

Some notes for maintaining this project can be found in the maintainer's handbook.