About settings

Tip

We provide a way to autoconfigure many settings using your identity provider autoconfiguration endpoints.

Tip

We provide Provider classes which implement setting generation for some popular identity providers (Keycloak, etc.).

All those settings must be defined in settings.py under the variable name DJANGO_PYOIDC. You should define them as a nested dictionary. The key to this dictionary is called your provider name (or op_name in some places). All your settings configuration are local to this provider. This allows multi-provider configurations.

Important

Manually defined settings replaces settings from providers.

Identity provider configuration

provider_class

Default: “django_pyoidc.providers.Provider”

Use this setting to plug in a provider class that will be used to generate the settings of your identity provider. Some providers expect to receive custom arguments: you should define them as settings.

For example, the Keycloak10Provider can use two arguments: keycloak_base_uri and keycloak_realm. If you wish to use them, define them in DJANGO_PYOIDC as your identity provider setting.

provider_discovery_uri

This settings should be the URL of an OIDC autoconfiguration endpoint. We will use this setting to discover and store all the URLs needed to perform user authentication.

Note

The .well-known/openid-configuration part of this url is not necessary, it will automatically be added.

client_secret

This setting configures the client secret used to authenticate your application with an identity provider.

Note

If you only have a client_id and not client_secret it means your OIDC client (application) was defined as a public application, which is normally only done for JavaScript SLA applications. A regular web application should have a client_secret, and an API backend application too.

client_id

This setting configures the client id used to authenticate your application with an identity provider.

use_introspection_on_access_tokens

Default: True

This setting is enabled by default on Django Rest Framework authentication (when you use drf for the key in DJANGO_PYOIDC, see Configuring django_rest_framework for more details). You can also activate it for more classical providers. But in DRF mode the access_token is the only information you receive from the user, and you need to extract claims from the token, that’s why we use introspection to both validate the token and get more information from it.

When this setting is enabled, we will use the introspection endpoint of the identity provider to perform token validation and return a clear extraction of the access_token.

When disabled, no access token verification is performed. You should define hook_validate_access_token to process the token as no token will be valid.

If you need information from the access_token activating this setting will add a round trip to the SSO server, but at the end you’ll have all the access_tokens claims in clear text.

You should also read the documentation about hook_validate_access_token

scopes

Default : [‘openid’]

The list of scopes requested by the OIDC Client when sending an authentication request.

oidc_paths_prefix

Default: dynamically computed using the name of your identity provider.

This is the prefix of the various url names created automagically by the OIDCHelper (when using get_urlpatterns). If not set it defaults to the op_name.

Note

One of the URL is the one referenced by the setting oidc_callback_path.

Warning

If your prefix starts with a / it will be removed.

You can use this setting to change the prefix used to name the URLs generated by this library. By default the URLS are named <op_name>-[login|callback|logout|etc.].

Configuring this setting allows you to swap <op_name> with an other value.

oidc_callback_path

This setting is used to reference the callback view that should be provided as the redirect_uri parameter of the Authorization Code Flow. A default path <op_name>-callback will be used if nothing is provided. This path is used internally to manage the authentication. You can alternatively use callback_uri_name to provide a named route for this path, this alternative will be better because using only oidc_callback_path you need to know the route prefix used on your oidc routes if any.

callback_uri_name

Name of a Django route that can be used to generate the oidc_callback_path value. If you used the OIDCHelper get_urlpatterns the default callback was created with a name <op_name>-callback (which is also the default path value). But the routes namespaces used with get_urlpatterns may be needed. So your final value for this route name should be something like “oidc_auth:mysso-callback” if “oidc_auth” was your route namespace and my_sso is your op_name.

Advanced identity provider configuration

oidc_logout_query_string_redirect_parameter

Todo

oidc_logout_query_string_extra_parameters_dict

Default: {}

All the key/values of this dictionary are used as http query params when performing a logout request to the identity provider.

client_authn_method

Default: see oic/utils/authn/client.py:437

Methods that the OIDC client can use to authenticate itself. It’s a dictionary with method names as keys and method classes as values.

use_introspection_audience_check

Default: True

This setting allows you to disable the audience check.

This settings is related to the drf implementation. By default, this library performs audience checks against the token received. We look for an aud key in the received token, and check that it’s value is the same as our client ID.

We believe that the only use case for this settings is if your identity provider does not put the audience in the generated tokens.

Login/Logout redirections

post_logout_redirect_uri

This setting configures where a user is redirected after successful SSO logout, defaults to Django base url.

Cache

oidc_cache_provider_metadata

Default: False

When this setting is enabled, we will cache the calls to the autoconfiguration endpoint of the OIDC identity provider.

oidc_cache_provider_metadata_ttl

Default: 120

This settings has no effect if oidc_cache_provider_metadata is disabled.

Otherwise, it configures the lifetime (in seconds) of cached response for the autoconfiguration of the identity provider.

cache_django_backend

This setting configures the cache backend that is used to store OIDC sessions details. It should be the name of a cache defined in the CACHES django setting. You can read more about Cache Management here.

Hooks

Each hook setting is a path to a python function that should be called in a specific context. We use a custom syntax to reference a function of a module.

The syntax is: <module path>:<function name>.

So for example, if you were to have a module named oidc.py next to your project settings with a function called logout_callback you should use the string <your application root module>.oidc:logout_callback in your settings.

Note

Hook settings work on a provider by provider basis, you can have different hook functions for each of your identity providers

Note

All of these settings are optional

hook_user_logout

Calls the provided function on user logout. The function is called if the logout is successful, but before redirecting the user.

This function takes two named parameters:

a request instance django.http.HttpRequest
the request args sent to the sso server (missing the id_token_hint element)

If the user was logged in, you can get the user using request.user.

hook_user_login

Calls the provided function on user login. The function is called if the login is successful.

This function takes two parameters:

a request instance django.http.HttpRequest
a user instance django.contrib.auth.models.User

Since the user wasn’t logged in, it is not yet attached to the request instance at this stage. As such trying to access request.user will return an unauthenticated user.

hook_get_user

Calls the provided function on user login. It takes two parameters:

client: an instance of OIDCClient that can be used to fetch the provider which authenticated the user
tokens: a dict with four keys:
- info_token_claims: the userinfo token (if available) as a dict
- access_token_jwt: the access token in it’s raw form, undecoded (jwt)
- access_token_claims: the access token decoded, as a dict
- id_token_claims: the id token as a dict

It is expected to return a django.contrib.auth.models.User instance.

hook_validate_access_token

This function is called :

by the drf integration when authenticating a user
by OIDCCallbackView to provide more claims to hook_get_user

When implementing this hook, you only have access to the access_token in its JWT encoded format. You can decide to try an extraction on your own with a jwt library, or keep it as a JWT. If your SSO provider provides enough claims in the userinfo token you do not need to extract content from the access_token. That’s why we do not extract the access_token claims by default.

hook_session_logout

This function is called by OIDCBackChannelLogoutView after validation of the logout request. It receives an instance of OIDCSession.

The default implementation is available in django_pyoidc.backchannel_logout_session.

About settings

Identity provider configuration

provider_class

provider_discovery_uri

client_secret

client_id

use_introspection_on_access_tokens

scopes

oidc_paths_prefix

oidc_callback_path

callback_uri_name

Advanced identity provider configuration

oidc_logout_query_string_redirect_parameter

oidc_logout_query_string_extra_parameters_dict

client_authn_method

use_introspection_audience_check

Login/Logout redirections

post_login_uri_failure

post_login_uri_success

post_logout_redirect_uri

login_redirection_requires_https

login_uris_redirect_allowed_hosts

Cache

oidc_cache_provider_metadata

oidc_cache_provider_metadata_ttl

cache_django_backend

Hooks

hook_user_logout

hook_user_login

hook_get_user

hook_validate_access_token

hook_session_logout