Skip to content

Add Auth0 OAuth2 backend documentation #359

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 10, 2025
Merged

Add Auth0 OAuth2 backend documentation #359

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9ea3826
Initial plan
Copilot Nov 10, 2025
8e96de1
Add Auth0 backend documentation
Copilot Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/backends/auth0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
Auth0
=====

Auth0 OAuth2
------------

Auth0 provides OAuth2 authentication. This is the original ``Auth0OAuth2`` backend.

For a newer OpenID Connect implementation, see :doc:`auth0_openidconnect`.

Setup
*****

To enable Auth0 OAuth2 support:

1. Register your application at `Auth0 Dashboard`_ to get your Auth0 domain,
Client ID, and Client Secret.

2. Fill in the settings with your Auth0 domain, Client ID, and Client Secret::

SOCIAL_AUTH_AUTH0_KEY = ''
SOCIAL_AUTH_AUTH0_SECRET = ''
SOCIAL_AUTH_AUTH0_DOMAIN = 'yourdomain.auth0.com'

Replace ``yourdomain`` with your Auth0 tenant domain.

3. Add the backend to your authentication backends::

AUTHENTICATION_BACKENDS = (
...
'social_core.backends.auth0.Auth0OAuth2',
...
)
Comment on lines +29 to +33
Copy link

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The setting name should be AUTHENTICATION_BACKENDS not SOCIAL_AUTH_AUTHENTICATION_BACKENDS. However, looking at other backend documentation files (e.g., apple.rst uses SOCIAL_AUTH_AUTHENTICATION_BACKENDS, azuread.rst uses AUTHENTICATION_BACKENDS, github.rst uses AUTHENTICATION_BACKENDS), there's inconsistency across the documentation. This file uses AUTHENTICATION_BACKENDS which matches github.rst and azuread.rst, so this is acceptable given the existing patterns.

Copilot uses AI. Check for mistakes.

Scopes
******

You can define custom scopes using the ``SOCIAL_AUTH_AUTH0_SCOPE`` setting::

SOCIAL_AUTH_AUTH0_SCOPE = ['openid', 'profile', 'email']

Comment on lines +40 to +41
Copy link

Copilot AI Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The scopes documentation shows a Python list format ['openid', 'profile', 'email'], but the auth0_openidconnect.rst documentation shows scopes as a space-separated string: 'openid profile email offline_access'. For consistency and to avoid user confusion, consider clarifying which format is expected by the Auth0OAuth2 backend, or align the format with the auth0_openidconnect backend if both accept the same format.

Suggested change
SOCIAL_AUTH_AUTH0_SCOPE = ['openid', 'profile', 'email']
SOCIAL_AUTH_AUTH0_SCOPE = 'openid profile email'
You may also use a Python list (e.g., ``['openid', 'profile', 'email']``), but for consistency with other backends, a space-separated string is recommended.

Copilot uses AI. Check for mistakes.
The backend will handle JWT token validation and extract user details including
username, email, full name, and profile picture.

.. _Auth0 Dashboard: https://manage.auth0.com/
1 change: 1 addition & 0 deletions docs/backends/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ Social backends
apple
appsfuel
arcgis
auth0
auth0_openidconnect
azuread
battlenet
Expand Down