{"id":2290,"library":"social-auth-core","title":"Python Social Auth Core","description":"social-auth-core is the foundational library for Python Social Auth, providing a flexible, decoupled mechanism for social authentication. It abstracts away the complexities of integrating OAuth, OpenID Connect, and SAML providers, enabling developers to add various social logins easily. The current version is 4.8.5, and it maintains a regular release cadence with frequent patch and minor updates to support new backends and fix issues.","status":"active","version":"4.8.5","language":"en","source_language":"en","source_url":"https://github.com/python-social-auth/social-core","tags":["authentication","oauth","openid","saml","social login","security"],"install":[{"cmd":"pip install social-auth-core","lang":"bash","label":"Install core library"},{"cmd":"pip install social-auth-core[sso]","lang":"bash","label":"Install with SAML support"}],"dependencies":[{"reason":"Required for JSON Web Token handling, especially for OpenID Connect and some OAuth2 backends.","package":"PyJWT","optional":false},{"reason":"Essential for making HTTP requests to OAuth/OpenID providers.","package":"requests","optional":false},{"reason":"Used for SAML backend to parse XML securely.","package":"defusedxml","optional":true},{"reason":"Used for SAML backend for XML processing.","package":"lxml","optional":true},{"reason":"Required for integration with Django projects.","package":"social-auth-django","optional":true},{"reason":"Required for integration with Flask projects.","package":"social-auth-flask","optional":true}],"imports":[{"note":"Backends are located under the 'backends' submodule.","wrong":"from social_core.oauth import BaseOAuth2","symbol":"BaseOAuth2","correct":"from social_core.backends.oauth import BaseOAuth2"},{"symbol":"BaseStrategy","correct":"from social_core.strategy import BaseStrategy"},{"symbol":"AuthException","correct":"from social_core.exceptions import AuthException"}],"quickstart":{"code":"import os\nfrom social_core.backends.oauth import BaseOAuth2\n\n# This example demonstrates how to define a custom OAuth2 backend using social-auth-core.\n# To use this in a web application, you would also need a framework-specific integration\n# (e.g., social-auth-django) and configure it in your project's settings.\n\nclass MyCustomOAuth2Backend(BaseOAuth2):\n    name = 'my-custom-oauth2'\n    AUTHORIZATION_URL = os.environ.get('MY_CUSTOM_OAUTH2_AUTHORIZATION_URL', 'https://example.com/oauth/authorize')\n    ACCESS_TOKEN_URL = os.environ.get('MY_CUSTOM_OAUTH2_ACCESS_TOKEN_URL', 'https://example.com/oauth/token')\n    SCOPE_SEPARATOR = ','\n    DEFAULT_SCOPE = ['email', 'profile']\n    EXTRA_DATA = [\n        ('id', 'id'),\n        ('expires_in', 'expires'),\n        ('token_type', 'token_type'),\n    ]\n\n    def get_user_details(self, response):\n        \"\"\"Return user details from example.com account.\"\"\"\n        return {\n            'username': response.get('email') or response.get('name'),\n            'email': response.get('email'),\n            'fullname': response.get('name')\n        }\n\n    def user_data(self, access_token, *args, **kwargs):\n        \"\"\"Loads user data from the custom service using the access_token.\"\"\"\n        # In a real backend, you'd make an API call to fetch user info.\n        # For this quickstart, we return mock data.\n        # Example of a real call:\n        # url = 'https://api.example.com/userinfo'\n        # headers = {'Authorization': f'Bearer {access_token}'}\n        # response = self.get_json(url, headers=headers)\n        # return response\n        return {'id': 'user123', 'email': 'user@example.com', 'name': 'Test User'}\n\n# To integrate this, you would typically add 'my_app.backends.MyCustomOAuth2Backend'\n# to your framework's SOCIAL_AUTH_AUTHENTICATION_BACKENDS setting.","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or newer.","message":"Python 3.9 support was dropped in version 4.8.0. Users on Python 3.9 or older must upgrade to Python 3.10+.","severity":"breaking","affected_versions":"4.8.0+"},{"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.","message":"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.","severity":"breaking","affected_versions":"4.6.0, 4.7.0, 4.8.2+"},{"fix":"Ensure that all attributes expected by your SAML configuration are correctly provided by the Identity Provider (IdP). Implement robust error handling for `AuthMissingParameter`.","message":"For the SAML backend, missing configured attributes now cause an `AuthMissingParameter` error. Previously, these might have been silently ignored.","severity":"breaking","affected_versions":"4.8.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.","message":"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.","severity":"breaking","affected_versions":"4.6.0+"},{"fix":"Install the appropriate `social-auth-*` package for your web framework in addition to `social-auth-core`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If customizing user identification, ensure your logic accounts for the configurable `ID_KEY` (e.g., `SOCIAL_AUTH_UID_KEY`).","message":"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.","severity":"gotcha","affected_versions":"4.8.2+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}