astronauth 0.3.3

ASTRON Django Authentication app

ASTRONauth

Django App for quickly adding authentication to any Django app.

astronauth is based on the allauth package and updates the templates for follow the Design in ASTRON style (DIAS).

Installation

The package is available on pypi:

pip install astronauth

Django Settings

The following settings are the minimal settings required (also check the settings.py file.):

• SITE_ID is used by allauth, usually it can be set to 1 without any issue. See the Django documentation for more info.
• INSTALLED_APPS: make sure astronauth is listed before allauth since it overrides templates

INSTALLED_APPS = [
    # These are the default and should already be included
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    "my_app",   # if you override any of the templates, this should be here (e.g. custom navigation bar)

    ## These are required for ASTRONauth
    'django.contrib.sites',
    "astronauth",   # it is important that astronauth is included before allauth
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    'allauth.socialaccount.providers.keycloak',
]

• SOCIALACCOUNT_PROVIDERS: is a list of auth providers. astronauth mainly uses Keycloak:

SOCIALACCOUNT_PROVIDERS = {
    'keycloak': {
        'KEYCLOAK_URL': 'https://sdc-dev.astron.nl/auth',   # replace by https://keycloak.astron.nl/auth for production
        'KEYCLOAK_REALM': 'SDC',    # change this depending on which realm to use
        'SCOPE': ['openid', 'profile', 'email']
    }
}

• LOGIN_REDIRECT_URL is used to determine where users should be redirected after login. Usually the main index page is a good one (http://localhost:8000/ is used in development)

• While DEBUG=True Django hosts the file. For production purposes, consider the Django recommendations form their documentation.

• Important: with this configured, you should migrate the database: python manage.py migrate before further configuration. Also create a superuser:

$ DJANGO_SUPERUSER_PASSWORD=password python manage.py createsuperuser --username admin --email [e-mail] --noinput

Important: replace the username/password and email where necessary

Since astronauth is based on allauth, please take a look at their documentation for all available settings.

Rename session and CSRF Cookies

If multiple apps or services are hosted at the same machine/url, their session or csrf cookies might interfere. Therefore it is necessary to rename the session and csrf cookies to include the name of the app. Add the following to your settings.py in your Django project folder:

SESSION_COOKIE_NAME = 'my_service_name_session_id'
CSRF_COOKIE_NAME = 'my_service_csrftoken'

Adding a provider

Before adding the provider in your app, make sure you have a realm setup in Keycloak and configured a client in that Keycloak realm. Take note of the Client ID, since you will use it in astronauth.

Make sure that the following options are set:

• Client Protocol is openid-connect
• For granting acces there are two options:
  • Front-end applications: Acces Type is public
  • Back-end applications: Acces Type is confidential + Authorization Enabled is On (it also sets Service Account Enabled to On). Note that is provides a Secret key in the Credentials tab that you need to configure later in your application.
• Valid Redirect URIs contains a list or URI for your application. Include http://localhost:8000/ for development (Important: not recommended for production clients!)

Django Admin configuration

• Log into the Django admin interface (http://localhost:8000/admin/ in development)
• Make sure the Sites contains an entry (should be done by the migrate command) and update them if you need to
• In the Social Accounts section, click add on Social applications and use the following settings
  • Provider => Keycloak
  • Name => Keycloak (could be anything)
  • Client id => The Client ID configured in your Keycloak Realm.
  • Secret => The Secret key provided by the Keycloak Realm in the Credentials tab
  • Sites => Make sure the site is added, otherwise you will run into No providers available errors.

Adding a custom Navbar

You probably should override the navigation bar, so that it uses the logo of your own application and redirects to the correct view if you click on the logo. This can be done by creating a template file in one of your apps. Check integration/my_app/templates/astronauth/navbar.html.

Note: Make sure that your app is above astronauth in the INSTALLED_APPS setting for this to work.

Deployment

TODO

• example of hosting static files with nginx
• example of docker-compose with traefik as reverse proxy

Contributing

This repository contains a minimal Django project for local development usage.

# Install as an editable package so changes are reflected immediately
pip install -e .
# then from the integration directory
cd integration
# Run the migrations
python manage.py migrate
# Create a super user
DJANGO_SUPERUSER_PASSWORD=password python manage.py createsuperuser --username admin --email [e-mail] --noinput
# Load the setup data
python manage.py loaddata fixtures/test_data.json
# the app is then served via "http://localhost:8000/"
python manage.py runserver
# set the secret key from the KeyCloak realm in the administrator console for the Social Application Keycloak


# Follow the configuration steps mentioned above for adding a superuser and configuring a client.

Code Format

The provided tox.ini files has a command tox -e format to format your code for you.

Acknowledgements

TODO Determine which grants are applicable.