OIDC (OpenID Connect)
=====================

Backend class
-------------

For Django, add this class path to ``AUTHENTICATION_BACKENDS``. For other
integrations, use the same class path in the framework-specific backend
setting.

.. list-table::
   :header-rows: 1

   * - Backend name
     - Class path
   * - ``oidc``
     - ``social_core.backends.open_id_connect.OpenIdConnectAuth``

The OIDC_ backend allows authentication against a generic OIDC provider.
The backend class is `OpenIdConnectAuth` with name `oidc`.  A minimum
configuration is::

    SOCIAL_AUTH_OIDC_OIDC_ENDPOINT = 'https://.....'
    SOCIAL_AUTH_OIDC_KEY = '<client_id>'
    SOCIAL_AUTH_OIDC_SECRET = '<client_secret>'

The remaining configuration will be auto-detected, by fetching::

    <SOCIAL_AUTH_OIDC_OIDC_ENDPOINT>/.well-known/openid-configuration

This class can be used standalone, but is also the base class for some other
backends.

Nonce lifetime
--------------

Each login attempt stores a one-use nonce with its creation time and lifetime.
The nonce expires after 30 minutes by default. Configure a different positive
integer duration in seconds with::

    SOCIAL_AUTH_OIDC_NONCE_LIFETIME = 1800

For other backends inheriting from this class, replace ``OIDC`` with the backend's
settings prefix. This duration bounds the time from starting authentication to
validating the ID token; it is independent of ``ID_TOKEN_MAX_AGE``, which limits
the age of the ID token itself. An expired nonce rejects the login, so the user
must start again. Successful validation consumes the nonce. Refresh requests
and resumed partial pipelines do not reuse it.

LinkedIn OpenID Connect does not create or send nonces because its backend does
not validate them. Custom subclasses can set the class attribute ``USE_NONCE``
to ``False`` when their protocol-specific validation does not use server-created
nonces; this is not a deployment setting.

Failed and abandoned attempts can leave nonce records behind. Django deployments
should regularly run ``manage.py clearsocial``; see
:doc:`/configuration/django` for cleanup and upgrade guidance.

IdP Setup
---------

To configure your OIDC Identity Provider for use with this backend:

1. Create a new application/client in your IdP with type "Web Application"
2. Set the **Redirect URI** (also called Callback URL) to::

    https://your-domain.com/complete/oidc/

   Replace ``your-domain.com`` with your actual application domain.

3. Configure scopes to include at minimum: ``openid``, ``profile``, ``email``
4. Note the generated **Client ID** and **Client Secret** for use in your Django settings
5. Ensure your IdP exposes the OpenID Connect discovery endpoint at: ``https://your-idp-domain/.well-known/openid-configuration``

.. note::
   For development, you can use ``http://localhost:8000/complete/oidc/`` as the redirect URI.

Authentication Request Parameters
---------------------------------

All this parameters are optional and they might not be supported by the OIDC provider.

Prompt
^^^^^^

This informs the OIDC provider whether the OIDC provider prompts the user for reauthentication and consent. ::

    SOCIAL_AUTH_OIDC_PROMPT = '<prompt> ...'

Defined values are

- ``none``
- ``login``
- ``consent``
- ``select_account``

Username
--------

The OIDC_ backend will check for a ``preferred_username`` key in the values
returned by the server.  If the username is under a different key, this can
be overridden::

    SOCIAL_AUTH_OIDC_USERNAME_KEY = 'nickname'

This setting indicates that the username should be populated by the
``nickname`` claim instead.

First Name
----------

The OIDC_ backend will check for a ``given_name`` key in the values
returned by the server.  If the first name is under a different key, this can
be overridden::

    SOCIAL_AUTH_OIDC_FIRST_NAME_KEY = 'first_name'

This setting indicates that the first name should be populated by the
``first_name`` claim instead.

Last Name
---------

The OIDC_ backend will check for a ``family_name`` key in the values
returned by the server.  If the last name is under a different key, this can
be overridden::

    SOCIAL_AUTH_OIDC_LAST_NAME_KEY = 'last_name'

This setting indicates that the last name should be populated by the
``last_name`` claim instead.

Full Name
---------

The OIDC_ backend will check for a ``name`` key in the values
returned by the server.  If the full name is under a different key, this can
be overridden::

    SOCIAL_AUTH_OIDC_FULLNAME_KEY = 'full_name'

This setting indicates that the full name should be populated by the
``full_name`` claim instead.

Email
-----

The OIDC_ backend will check for a ``email`` key in the values
returned by the server.  If the email is under a different key, this can
be overridden::

    SOCIAL_AUTH_OIDC_EMAIL_KEY = 'mail'

This setting indicates that the email should be populated by the
``mail`` claim instead.

Scopes
------

The default set of scopes requested are "openid", "profile" and "email".
You can request additional claims, for example::

    SOCIAL_AUTH_OIDC_SCOPE = ['groups']

and you can prevent the inclusion of the default scopes using::

    SOCIAL_AUTH_OIDC_IGNORE_DEFAULT_SCOPE = True

.. _OIDC: https://openid.net/connect/

External memberships
--------------------

See :doc:`/groups` for opt-in extraction, group-based login restrictions, and
local group synchronization. No separate extraction pipeline step is needed.