Skip to main content

Authenticate with any OpenId Connect/Oauth2 provider through authorization code flow. PKCE is also supported.

Project description

Summary

pypi downloads pypi status python versions django versions pipeline status license

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

PKCE is also supported.

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.session 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 ot 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

Optional middlewares

You can add some middlewares to add some features:

  • 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).

The first two 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.

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
OIDC_RP_USE_PKCE PKCE improve security, disable it only if your provider cannot handle it. True
OIDC_RP_FORCE_CONSENT_PROMPT Force to ask for consent on login, even if offline_access is not in scopes 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 email
None value means use OIDC_OP_EXPECTED_EMAIL_CLAIM value
You 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_token
This 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.
You should include at least any failure/error urls in it.
[]
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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_oauth2_authcodeflow-0.8.0.tar.gz (25.7 kB view hashes)

Uploaded Source

Built Distribution

django_oauth2_authcodeflow-0.8.0-py3-none-any.whl (30.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page