GitLocker: The Coding Marketplace

Description:

djangooauth2authcodeflow 1.2.2

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.

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)),

A slightly different version, by directly and only using the login_required from oauth2_authcodeflow.utils.
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:

Settings
Description
Default

OIDC_OP_DISCOVERY_DOCUMENT_URL
URL of your OpenID connect Provider discovery document url (recommended).If you provide this, the following configs will be ignored:- OIDC_OP_AUTHORIZATION_URL- OIDC_OP_TOKEN_URL- OIDC_OP_USERINFO_URL- OIDC_OP_JWKS_URL
None

OIDC_OP_AUTHORIZATION_URL
URL of your OpenID connect Provider authorization endpoint (not recommended, OIDC_OP_DISCOVERY_DOCUMENT_URL is preferred).
None

OIDC_OP_TOKEN_URL
URL of your OpenID connect Provider token endpoint (not recommended, OIDC_OP_DISCOVERY_DOCUMENT_URL is preferred).
None

OIDC_OP_USERINFO_URL
URL of your OpenID connect Provider userinfo endpoint (not recommended, OIDC_OP_DISCOVERY_DOCUMENT_URL is preferred).
None

OIDC_OP_JWKS_URL
URL of your OpenId connect Provider endpoint to get public signing keys (in PEM or DER format).This is used to verify the id_token.This is not recommended to provide this url here but rather use OIDC_OP_DISCOVERY_DOCUMENT_URL config.
None

OIDC_OP_END_SESSION_URL
URL of your OpenID connect Provider end session endpoint (not recommended, OIDC_OP_DISCOVERY_DOCUMENT_URL is preferred).
None

OIDC_OP_FETCH_USER_INFO
Fetch user info on login or not.
True

OIDC_OP_TOTAL_LOGOUT
Do a call to total logout will call the OP for a logout. Default true.Be careful, some OP will not follow the RFC and will not allow the user to NOT logout all connected apps.Azure is such a bad example.
True

OIDC_OP_EXPECTED_EMAIL_CLAIM
expected email key.
'email'

OIDC_OP_EXPECTED_CLAIMS
OIDC_OP_EXPECTED_EMAIL_CLAIM value is automatically included in this list.
[]

OIDC_RP_CLIENT_ID
OpenID Connect client ID provided for your Relaying Party/client by your OpenIdConnect Provider

OIDC_RP_CLIENT_SECRET
OpenID Connect client secret provided for your Relaying Party/client by your OpenIdConnect Provider.Could be empty in PKCE case.

OIDC_RP_USE_PKCE
PKCE improve security, disable it only if your provider cannot handle it.
True

OIDC_RP_FORCE_SECRET_WITH_PKCE
Force to send the client secret even when using PKCE.Only use this option if your provider don’t support PKCE without secret.
False

OIDC_RP_FORCE_CONSENT_PROMPT
Force to ask for consent on login, even if offline_access is not in scopes
False

OIDC_RP_AZURE_SPA
Azure require the 'Origin' header when using PKCE and SPA
False

OIDC_RP_SCOPES
The OpenID Connect scopes to request during login.The scopes could be usefull later to get access to other ressources.openid must be in the list.You can also include the email scope to ensure that the email field will be in the claims (recommended).You can also include the profile scope to get more (like names, …) info in the id_token (recommended).You can also get a refresh_token by specifying the offline_access scope.
['openid', 'email', 'profile', 'offline_access']

OIDC_RP_USERINFO_CLAIMS
OpenID Connect authorization request parameter userinfo member to optionaly add to id token request (dict type).
None

OIDC_RP_TOKEN_CLAIMS
OpenID Connect authorization request parameter id_token member to optionaly add to id token request (dict type).
None

OIDC_RP_SIGN_ALGOS_ALLOWED
Sets the algorithms the IdP may use to sign ID tokens.Typical values ar HS256 (no key required) and RS256 (public key required)The public keys might be defined in OIDC_RP_IDP_SIGN_KEY or deduced using the OIDC_OP_JWKS_URL config.
['HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512']

OIDC_RP_IDP_SIGN_KEY
Public RSA used to verify signatures. Overrides keys from JWKS endpoint.Should be in PEM or DER format.
None

OIDC_CREATE_USER
Enables or disables automatic user creation during authentication
True

OIDC_RANDOM_SIZE
Sets the length of the random string used in the OAuth2 protocol.
32

OIDC_PROXY
Defines a proxy for all requests to the OpenID Connect provider (fetch JWS, retrieve JWT tokens, Userinfo Endpoint).The default is set to None which means the library will not use a proxy and connect directly.For configuring a proxy check the Python requests documentation: https://requests.readthedocs.io/en/master/user/advanced/#proxies
None

OIDC_TIMEOUT
Defines a timeout for all requests to the OpenID Connect provider (fetch JWS, retrieve JWT tokens, Userinfo Endpoint).The default is set to None which means the library will wait indefinitely.The time can be defined as seconds (integer).More information about possible configuration values, see Python requests: https://requests.readthedocs.io/en/master/user/quickstart/#timeouts
None

OIDC_REDIRECT_OK_FIELD_NAME
Sets the GET parameter that is being used to define the redirect URL after succesful authentication
'next'

OIDC_REDIRECT_ERROR_FIELD_NAME
Sets the GET parameter that is being used to define the redirect URL after failed authentication
'fail'

OIDC_DJANGO_USERNAME_FUNC
Function or dotted path to a function that compute the django username based on claims.The username should be unique for this app.The default is to use a base64 url encode of the email hash (sha1).
get_default_django_username

OIDC_EMAIL_CLAIM
Claim name for emailNone value means use OIDC_OP_EXPECTED_EMAIL_CLAIM valueYou can also provide a lambda that takes all the claims as argument and return an email
None

OIDC_FIRSTNAME_CLAIM
You can also provide a lambda that takes all the claims as argument and return a firstname
'given_name'

OIDC_LASTNAME_CLAIM
You can also provide a lambda that takes all the claims as argument and return a lastname
'family_name'

OIDC_EXTEND_USER
Callable that takes the user, the claims and optionaly the request and access_token as arguments and that can extend user properties.You can also specify a dotted path to a callable.
None

OIDC_UNUSABLE_PASSWORD
Scramble the password on each SSO connection/renewal.If False, it will only scramble it when creating an account
True

OIDC_BLACKLIST_TOKEN_TIMEOUT_SECONDS
7 days by default
7 * 86400

OIDC_AUTHORIZATION_HEADER_PREFIX
Only used when using authorization in header:Authorization: Bearer id_tokenThis is only possible if oauth2_authcodeflow.middleware.BearerAuthMiddleware has been added to MIDDLEWARE setting list.
'Bearer'

OIDC_MIDDLEWARE_NO_AUTH_URL_PATTERNS
The RefreshAccessTokenMiddleware and RefreshSessionMiddleware will use this list to bypass auth checks.Any url listed here will not be tried to be authenticated using Auth Code Flow.You should include at least any failure/error or admin urls in it.
[]

OIDC_MIDDLEWARE_LOGIN_REQUIRED_REDIRECT
Redirect to login page if not authenticated when using LoginRequiredMiddleware.
True

OIDC_MIDDLEWARE_API_URL_PATTERNS
The RefreshAccessTokenMiddleware and RefreshSessionMiddleware will use this list to answer JSON response in case of refresh failure.Expected list of regexp URL patterns.
['^/api/']

OIDC_MIDDLEWARE_SESSION_TIMEOUT_SECONDS
7 days by default
7 * 86400