User API Reference

Django settings

Note

We provide a set of predefined settings for some identity providers. As such, you can avoid having to configure by yourself this library and it’s views. Take a look at the tutorial !

Providers settings

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.

DJANGO_PYOIDC = {
    'my_provider_name' : {
        'setting_1' : 'value',
        'setting_2' : 'value'
    }
}

POST_LOGIN_URI_FAILURE

This setting configures where a user is redirected on login failure, defaults to Django base url.

POST_LOGIN_URI_SUCCESS

This setting configures the default redirection URI on login success, defaults to Django base url.

POST_LOGOUT_REDIRECT_URI

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

URI_PROVIDER

This setting configures your provider root URI. TODO : rename to PROVIDER_HOST or something like that.

URI_CONFIG

This settings configures the path to your OIDC configuration. TODO : example.

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.

LOGIN_REDIRECTION_REQUIRES_HTTPS

This setting configures if dynamic login redirection URI must have the https scheme.

LOGIN_URIS_REDIRECT_ALLOWED_HOSTS

This setting configures the list of allowed host in dynamic URI redirections.

OIDC_CLIENT_SECRET

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

OIDC_CLIENT_ID

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

CACHE_DJANGO_BACKEND

This setting configures the cache backend that is used to store sessions details. You can read more about Cache Management here.

Hook settings

Hook settings are path to a python function that should be called in 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 those 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 arguments :

  1. a request instance django.http.HttpRequest

  2. TODO FIXME RLE

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 functions is called if the login is successful.

This function takes two arguments :

  1. a request instance django.http.HttpRequest

  2. 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 arguments :

  • the user info token (a dictionary) from the identity provider

  • the id token

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

Views

Note

When instantiating a view from this library (ie through django’s β€˜as_view()’) you must set the named argument op_name to point to a valid DJANGO_PYOIDC settings entry. If you use Providers then this behaviour is automatically implemented.

Here is an example :

from .oidc_providers import my_project_provider

urlpatterns = [
    path("auth/callback", OIDCCallbackView.as_view(op_name="keycloak"),),
]

Providers

Providers classes allows the final user to configure their project without having to understand how to map their Identity Provider configuration settings to this library settings.

Each provider implements the configuration logic and provides mostly two methods :

  • One to generate a configuration dict to be inserted in the DJANGO_PYOIDC value of your django settings : get_config()

  • One to generate urls to be included in your url configuration : get_urlpatterns()

class django_pyoidc.providers.KeycloakProvider(keycloak_base_uri: str, keycloak_realm: str, *args, **kwargs)

Provide django settings/urlconf based on keycloak behaviour (latest version).

For older Keycloak versions please check the other Keycloak_* providers.

class django_pyoidc.providers.base.Provider(op_name: str, provider_discovery_uri: str, logout_redirect: str, failure_redirect: str, success_redirect: str, redirect_requires_https: bool, client_secret: str, client_id: str)

This is the base Provider class that is used to implement common provider configuration patterns. You should not use this class directly. Instead, you should but subclass it to implement the configuration logic.

__init__(op_name: str, provider_discovery_uri: str, logout_redirect: str, failure_redirect: str, success_redirect: str, redirect_requires_https: bool, client_secret: str, client_id: str)
Parameters:

  • op_name (str) – the name of the sso provider that you are using

  • logout_redirect (str) – the URI where a user should be redirected to on logout success

  • failure_redirect (str) – the URI where a user should be redirected to on login failure

  • success_redirect (str) – the URI a user should be redirected to on login success if no redirection url where provided

  • redirect_requires_https (bool) – set to True to disallow redirecting user to non-https uri on login success

  • client_secret (str) – the OIDC client secret

  • client_id (str) – the OIDC client ID

property callback_uri_name

The callback viewname (use in django.urls.reverse() django directive for example) of this configuration

get_config(allowed_hosts, cache_backend: str = 'default') → Dict[str, Dict[str, Any]]
Parameters:

  • allowed_hosts (list) – A list of allowed domains that can be redirected to. A good idea is to this to ALLOWED_HOSTS. See Redirect the user after login for more details.

  • cache_backend (str, optional) – Defaults to β€˜default’. The cache backend that should be used to store this provider sessions. Take a look at Cache Management

Returns:

A dictionary with all the settings that django-pyoidc expects to work properly

Return type:

dict

get_urlpatterns() → List[Any]
Returns:

A list of urllpatterns to be included using django.urls.include() in your urllconfiguration

property login_uri_name

The login viewname (use in django.urls.reverse() django directive for example) of this configuration

property logout_uri_name

The logout viewname (use in django.urls.reverse() django directive for example) of this configuration