<a id="oidc-openid-connect"></a>

# OIDC (OpenID Connect)

<a id="backend-class"></a>

## 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.

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

The [OIDC](https://openid.net/connect/) backend allows authentication against a generic OIDC provider.
The backend class is OpenIdConnectAuth with name oidc.  A minimum
configuration is:

```default
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:

```default
<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.

<a id="nonce-lifetime"></a>

## 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:

```default
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
[Django Framework](../configuration/django.html.md) for cleanup and upgrade guidance.

<a id="idp-setup"></a>

## 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:
   ```default
   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.

<a id="authentication-request-parameters"></a>

## Authentication Request Parameters

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

<a id="prompt"></a>

### Prompt

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

```default
SOCIAL_AUTH_OIDC_PROMPT = '<prompt> ...'
```

Defined values are

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

<a id="username"></a>

## Username

The [OIDC](https://openid.net/connect/) 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:

```default
SOCIAL_AUTH_OIDC_USERNAME_KEY = 'nickname'
```

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

<a id="first-name"></a>

## First Name

The [OIDC](https://openid.net/connect/) 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:

```default
SOCIAL_AUTH_OIDC_FIRST_NAME_KEY = 'first_name'
```

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

<a id="last-name"></a>

## Last Name

The [OIDC](https://openid.net/connect/) 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:

```default
SOCIAL_AUTH_OIDC_LAST_NAME_KEY = 'last_name'
```

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

<a id="full-name"></a>

## Full Name

The [OIDC](https://openid.net/connect/) 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:

```default
SOCIAL_AUTH_OIDC_FULLNAME_KEY = 'full_name'
```

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

<a id="email"></a>

## Email

The [OIDC](https://openid.net/connect/) 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:

```default
SOCIAL_AUTH_OIDC_EMAIL_KEY = 'mail'
```

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

<a id="scopes"></a>

## Scopes

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

```default
SOCIAL_AUTH_OIDC_SCOPE = ['groups']
```

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

```default
SOCIAL_AUTH_OIDC_IGNORE_DEFAULT_SCOPE = True
```

<a id="external-memberships"></a>

## External memberships

See [External groups](../groups.html.md) for opt-in extraction, group-based login restrictions, and
local group synchronization. No separate extraction pipeline step is needed.