Summary

Authenticate with any OpenId Connect/Oauth2 provider through authorization code flow with Django.

Supported protocols:

• Oauth 2.0
• PKCE
• OpenIDConnect 1.0

Wording

• OP = OpenId Connect Provider, the auth server
• RP = Relying Party, the client, your application

Setup

• add oauth2_authcodeflow to the INSTALLED_APPS (after django.contrib.auth and django.contrib.sessions apps)

• add path('oidc/', include('oauth2_authcodeflow.urls')), in your global urls.py file.

  You can change the path prefix to what you want

• add oauth2_authcodeflow.auth.AuthenticationBackend to the AUTHENTICATION_BACKENDS config.

  You can keep django.contrib.auth.backends.ModelBackend as a second-fallback auth mechanism.

• get your callback urls by doing:

./manage.py oidc_urls [--secure] <HOST_NAME>

• Configure your application on the OpenId Connect Provider.

  This should give you a client_id and a secret_id.

  You will need to fill the redirect_url and logout_url there.

• Ensue to include the sid, email, first name, last name (if applicable) parameters in the id token claims on the OP.

• Ensure that django.contrib.sessions.middleware.SessionMiddleware is in MIDDLEWARE

Minimal configuration

• SESSION_COOKIE_SECURE to True if your Django is served through HTTPS
• OIDC_OP_DISCOVERY_DOCUMENT_URL to the well-known openid configuration url of the OP
• OIDC_RP_CLIENT_ID client id provided by the OP
• OIDC_RP_CLIENT_SECRET secrect id provided by the OP

Login

Get your browser/frontend to go to the oidc_authentication page name (/oidc/authenticate by default) with the following parameters:

• next: the url to redirect on success
• fail: the url to redirect on failure, error query string may contain an error description

Logout

Get your browser/frontend to go to the oidc_logout page name (/oidc/logout by default) with the following parameters:

• next: the url to redirect on success
• fail: the url to redirect on failure, error query string may contain an error description

Logout from the OP as well

This will logout the user from the application but also from the OP (if user say yes) and the OP should also logout the user from all other apps connected to this OP.

The spec is not well followed by the OP, so you mileage may vary.

Get your browser/frontend to go to the oidc_total_logout page name (/oidc/total_logout by default) with the following parameters:

• next: the url to redirect on success
• fail: the url to redirect on failure, error query string may contain an error description

Protect your urls

At least three options are possible.

1. Use default django way to limit access to logged-in users by defining LOGIN_URL in your settings and and login_required decorators in your views.

# settings.py
from django.urls import reverse_lazy
from django.utils.text import format_lazy
LOGIN_URL = format_lazy('{url}?fail=/', url=reverse_lazy(OIDC_URL_AUTHENTICATION_NAME))
# urls.py
from django.contrib.auth.decorators import login_required
path('restricted_url/', login_required(your_view)),

2. A slightly different version, by directly and only using the login_required from oauth2_authcodeflow.utils.
3. Use the LoginRequiredMiddleware with OIDC_MIDDLEWARE_NO_AUTH_URL_PATTERNS configuration.

Optional middlewares

You can add some middlewares to add some features:

• oauth2_authcodeflow.middleware.LoginRequiredMiddleware to automaticaly force a login request to urls not in OIDC_MIDDLEWARE_NO_AUTH_URL_PATTERNS if not authenticated.
• oauth2_authcodeflow.middleware.RefreshAccessTokenMiddleware to automaticaly refresh the access token when it’s expired.
• oauth2_authcodeflow.middleware.RefreshSessionMiddleware to automaticaly ask for a new id token when it’s considered expired.
• oauth2_authcodeflow.middleware.BearerAuthMiddleware to authenticate the user using Authorization HTTP header (API, scripts, CLI usage).

LoginRequiredMiddleware will refresh to the original page uppon user logged-in.

RefreshAccessTokenMiddleware and RefreshSessionMiddleware will try the refresh and return a redirect to the same page (or the one configured as next in the login phase) if the refresh cannot happen.

Use them to silently refresh your access/id tokens.

BearerAuthMiddleware will use oauth2_authcodeflow.auth.BearerAuthenticationBackend to authenticate the user based on Authorization HTTP header instead of using the sessions.

Use this to allow to authenticate without cookies/session. You then need to login with from_cli=1 in your login url. You then needs to go to the displayed url with a browser and copy the result http header to make further requests.

Signals

One can use Django user_logged_in and user_logged_out signals to know and act when a user is logged in or disconnected.

Full configuration

Secure session cookie settings:

• SESSION_COOKIE_AGE to a reasonable time (default 2 weeks)
• SESSION_COOKIE_HTTPONLY must be True (default True)
• SESSION_COOKIE_PATH be sure to use / to prevent some weird behavior (default /)
• SESSION_COOKIE_SAMESITE should be Lax (default Lax)
• SESSION_COOKIE_SECURE should be True in https context (default False)

Specific OIDC settings: