Python Social Auth Core

Warnings

• breaking Python 3.9 support was dropped in version 4.8.0. Users on Python 3.9 or older must upgrade to Python 3.10+.
  Fix: Upgrade your Python environment to version 3.10 or newer.
• breaking Numerous social authentication backends have been removed across recent versions (e.g., itembase, nk, AOL OpenID, BitBucket OAuth 1.0, khanacademy). Users relying on these backends will find them unavailable.
  Fix: Consult the changelog for specific backend removals. If your backend was removed, you may need to implement a custom backend or find an alternative authentication method.
• breaking For the SAML backend, missing configured attributes now cause an `AuthMissingParameter` error. Previously, these might have been silently ignored.
  Fix: Ensure that all attributes expected by your SAML configuration are correctly provided by the Identity Provider (IdP). Implement robust error handling for `AuthMissingParameter`.
• breaking OAuth2 backends now default to using the POST method for token exchange (e.g., getting access tokens). This change occurred in version 4.6.0.
  Fix: Review existing custom OAuth2 backend implementations to ensure they are compatible with POST requests for token exchange. Most standard compliant providers will support POST, but older or non-standard ones might break.
• gotcha `social-auth-core` is a core library and requires a framework-specific integration package (e.g., `social-auth-django`, `social-auth-flask`, `social-auth-pyramid`) to be used in a web application context.
  Fix: Install the appropriate `social-auth-*` package for your web framework in addition to `social-auth-core`.
• gotcha The `ID_KEY` used for identifying users, which defaults to `id`, became configurable in version 4.8.2. If you have custom logic relying on the fixed 'id' key or are extending backends, this might impact your code.
  Fix: If customizing user identification, ensure your logic accounts for the configurable `ID_KEY` (e.g., `SOCIAL_AUTH_UID_KEY`).

Install

• pip install social-auth-core Install core library
• pip install social-auth-core[sso] Install with SAML support

Imports

• BaseOAuth2

  from social_core.backends.oauth import BaseOAuth2

  Backends are located under the 'backends' submodule.
• BaseStrategy

  from social_core.strategy import BaseStrategy

• AuthException

  from social_core.exceptions import AuthException

Quickstart

This quickstart demonstrates how to define a custom OAuth2 backend using `social-auth-core`. This core component abstracts provider specifics. For actual usage in a web application, this backend definition must be integrated with a framework-specific package (e.g., `social-auth-django`) and configured in your project's settings to provide the necessary client ID, secret, and URLs.

import os
from social_core.backends.oauth import BaseOAuth2

# This example demonstrates how to define a custom OAuth2 backend using social-auth-core.
# To use this in a web application, you would also need a framework-specific integration
# (e.g., social-auth-django) and configure it in your project's settings.

class MyCustomOAuth2Backend(BaseOAuth2):
    name = 'my-custom-oauth2'
    AUTHORIZATION_URL = os.environ.get('MY_CUSTOM_OAUTH2_AUTHORIZATION_URL', 'https://example.com/oauth/authorize')
    ACCESS_TOKEN_URL = os.environ.get('MY_CUSTOM_OAUTH2_ACCESS_TOKEN_URL', 'https://example.com/oauth/token')
    SCOPE_SEPARATOR = ','
    DEFAULT_SCOPE = ['email', 'profile']
    EXTRA_DATA = [
        ('id', 'id'),
        ('expires_in', 'expires'),
        ('token_type', 'token_type'),
    ]

    def get_user_details(self, response):
        """Return user details from example.com account."""
        return {
            'username': response.get('email') or response.get('name'),
            'email': response.get('email'),
            'fullname': response.get('name')
        }

    def user_data(self, access_token, *args, **kwargs):
        """Loads user data from the custom service using the access_token."""
        # In a real backend, you'd make an API call to fetch user info.
        # For this quickstart, we return mock data.
        # Example of a real call:
        # url = 'https://api.example.com/userinfo'
        # headers = {'Authorization': f'Bearer {access_token}'}
        # response = self.get_json(url, headers=headers)
        # return response
        return {'id': 'user123', 'email': 'user@example.com', 'name': 'Test User'}

# To integrate this, you would typically add 'my_app.backends.MyCustomOAuth2Backend'
# to your framework's SOCIAL_AUTH_AUTHENTICATION_BACKENDS setting.