python-social-auth/social-core: the backend layer behind Python social login

What social-core actually solves

Adding social login to a Python web application means implementing OAuth 1, OAuth 2, OpenID and SAML handshakes, mapping each provider's user payload onto your own user model, and then doing it again for the next provider. social-core exists so that work is written once. The README describes it as the core component of the python-social-auth ecosystem, implementing "the common interface to define new authentication backends to third parties services, implement integrations with web frameworks and storage solutions".

The audience is narrower than the name suggests. This is a library for people who are wiring authentication into a framework, or who need one of the backends it ships. If you want a working login button in a Django project, you install the Django package, not this one. The README is explicit that "only the core and Django modules are currently in development. All others are in maintenance only mode", which tells you where maintainer attention goes and where it does not.

How the core/backend split works in practice

The repository layout shows the shape of the design. There is a single social_core/ package at the top level, and pyproject.toml declares the runtime dependencies: cryptography, defusedxml, oauthlib, PyJWT with the crypto extra, python3-openid, requests-oauthlib and requests. That dependency list is the mechanism in miniature. OAuth handshakes go through oauthlib and requests-oauthlib, JWT validation through PyJWT, XML-based assertions through defusedxml, and OpenID through python3-openid.

Backends live under social_core.backends, which is why search queries about this project are shaped like "social_core.backends.azure ad.azure ad oauth2". A backend is the unit of provider support: it knows the provider's endpoints, scopes and token exchange, and returns a normalised user payload. Framework packages sit above that and handle request routing, session state and persistence. The split means a backend fix benefits every framework, and it also means a bug in the core can surface in integrations you did not touch.

Optional dependency groups in pyproject.toml gate the heavier providers. The file shows an "all" group that pulls in social-auth-core[azuread], social-auth-core[google-onetap] and social-auth-core[saml], among others. SAML in particular is not in the base install, so a project that needs it must opt in explicitly.

Installing social-auth-core and reading a backend

The README gives one install command and no configuration walkthrough, because configuration belongs to the framework package:

pip install social-auth-core

After that, the library is importable as social_core. The README does not document an inspection API, and pyproject.toml does not expose a command line entry point, so the practical first step is to look at what the repository actually contains. The top-level entries list a social_core/ directory, and the search queries about this project point at social_core.backends, which is where provider modules live. Reading that directory tells you which providers are implemented before you write any integration code.

If you need a provider that is not in the base install, add the matching extra. The pyproject.toml optional-dependencies section shows the naming convention used by the "all" group:

pip install "social-auth-core[azuread]"

What you should not expect from these commands is a login flow. There is no view, no URL route and no session handling in the core. The README points to https://python-social-auth.readthedocs.io/ for documentation, and that is where framework-specific setup lives.

The maintenance boundary is the real constraint

The most consequential sentence in the README is the one about module status: only core and Django are in development, everything else is maintenance only, and maintainers are "especially welcome" there. That is a candid statement about capacity, and it should shape adoption decisions. If your stack is Django, you are on the path that receives work. If you are on another framework integration, you are depending on code that receives fixes rather than features.

The second constraint is the dependency surface. A base install brings in cryptography, PyJWT with the crypto extra, oauthlib, requests-oauthlib, python3-openid, defusedxml and requests. For an application that only needs one OAuth 2 provider, that is a lot of transitive code, including a cryptography build. There is no documented slimming path in the README beyond the optional extras, which add more rather than less.

The third is version coupling. pyproject.toml sets requires-python to >= 3.10 and the classifiers name 3.10 through 3.14, so older interpreters are out. The project follows Semantic Versioning 2.0.0 per the README, and the 5.x line has moved quickly, with 5.0.1, 5.0.2 and 5.1.0 all released within roughly six weeks. Semver is a promise about interface stability, not about the absence of behavioural change in provider handshakes, and providers change their endpoints without asking.

When a direct provider SDK is the better call

The alternative is not another social auth library so much as going direct: use the provider's own SDK, or the underlying libraries this project already depends on, and write the flow yourself. Google publishes a Python auth library, and the pyproject.toml even lists google-auth-stubs in the dev group, which shows the overlap is understood upstream.

The difference in approach is where the abstraction sits. social-core abstracts across providers: one interface, many backends, normalised user data, and framework packages on top. A direct SDK abstracts nothing across providers. You get first-party support for one provider, updated on that provider's schedule, with no normalisation layer to fight when the payload changes shape. If you support exactly one provider and never plan a second, the cross-provider interface is cost without benefit, and you inherit the core's dependency tree for nothing.

The trade-off flips as soon as you add a second provider. Two direct SDKs mean two payload shapes, two token refresh implementations and two sets of error semantics in your codebase. That is the problem social-core was built to remove, and it remains a reasonable answer to it.

Licence, upgrades and what a 5.x bump costs

The licence is BSD-3-Clause, declared in pyproject.toml as license = "BSD-3-Clause" with license-files = ["LICENSE"]. That is a permissive licence, and it is the same licence the README refers to when it says the project "follows the BSD license". For most commercial use the practical question is not the licence text but the dependency licences underneath it, and this is not legal advice: check cryptography, PyJWT, oauthlib and the rest against your own policy.

Upgrade cost is dominated by two things. First, the version pinning in your own project. Because the core is a library rather than a service, nothing upgrades itself, and the 5.x releases arrived close together, so a lagging pin can mean several minor versions of accumulated change. Second, the optional extras. If you installed social-auth-core[saml] or social-auth-core[azuread], an upgrade has to be validated against those provider paths, not just the base import. The CHANGELOG.md at the repository root is the file to read before bumping, and the dev dependency group in pyproject.toml shows the project runs pytest, mypy, pyright and pylint against its own code, which is a signal about internal discipline rather than a guarantee about your integration.

Editorial conclusion

Adopt social-auth-core if you are building or maintaining a framework integration and want the backend layer handled, or if you need a backend such as social_core.backends.azuread.AzureADOAuth2 without writing the OAuth flow yourself. Do not adopt it as a standalone login system: the README describes it as the core component of an ecosystem, and the framework packages supply the views and storage. Before committing, check the optional dependency groups in pyproject.toml for the providers you need, confirm your Python version against requires-python >= 3.10, and read the social_core/backends directory to see whether the provider you want is already implemented or has to be written.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes