{"id":19190183,"url":"https://github.com/macktireh/simplesocialauthlib","last_synced_at":"2025-08-18T11:47:05.482Z","repository":{"id":255987201,"uuid":"850395591","full_name":"Macktireh/SimpleSocialAuthLib","owner":"Macktireh","description":"SimpleSocialAuthLib is a Python library designed to simplify social authentication for various providers. It offers a straightforward interface for handling OAuth2 flows and retrieving user data from popular social platforms.","archived":false,"fork":false,"pushed_at":"2025-08-03T18:36:11.000Z","size":103,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-09T04:15:00.627Z","etag":null,"topics":["authentication","github","google","library","python","simplesocialauthlib","social-auth","social-login","twitter"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/SimpleSocialAuthLib/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Macktireh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-31T16:47:08.000Z","updated_at":"2025-08-04T06:04:26.000Z","dependencies_parsed_at":"2024-11-09T11:34:23.998Z","dependency_job_id":"d5c7ce23-66bb-4df2-b7a1-979c2e901a02","html_url":"https://github.com/Macktireh/SimpleSocialAuthLib","commit_stats":null,"previous_names":["macktireh/simplesocialauthlib"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Macktireh/SimpleSocialAuthLib","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macktireh%2FSimpleSocialAuthLib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macktireh%2FSimpleSocialAuthLib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macktireh%2FSimpleSocialAuthLib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macktireh%2FSimpleSocialAuthLib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Macktireh","download_url":"https://codeload.github.com/Macktireh/SimpleSocialAuthLib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Macktireh%2FSimpleSocialAuthLib/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270988131,"owners_count":24680669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","github","google","library","python","simplesocialauthlib","social-auth","social-login","twitter"],"created_at":"2024-11-09T11:33:13.229Z","updated_at":"2025-08-18T11:47:05.458Z","avatar_url":"https://github.com/Macktireh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eSimpleSocialAuthLib\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003c!-- row 1 — project metadata --\u003e\n    \u003ca href=\"https://pypi.org/project/SimpleSocialAuthLib\"\u003e\n      \u003cimg src=\"https://img.shields.io/pypi/v/SimpleSocialAuthLib.svg\" alt=\"PyPI Package Version\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/SimpleSocialAuthLib\"\u003e\n      \u003cimg src=\"https://img.shields.io/pypi/pyversions/SimpleSocialAuthLib.svg\" alt=\"Python Versions\"\u003e\n    \u003c/a\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\" /\u003e\n    \u003cbr\u003e\n    \u003c!-- row 2 — project status --\u003e\n    \u003ca href=\"https://github.com/Macktireh/SimpleSocialAuthLib/actions/workflows/ci.yml?query=branch%3Amain\"\u003e\n      \u003cimg src=\"https://github.com/Macktireh/SimpleSocialAuthLib/actions/workflows/ci.yml/badge.svg?branch=main\" alt=\"CI\"\u003e\n    \u003c/a\u003e\n    \u003cimg src=\"https://codecov.io/gh/Macktireh/SimpleSocialAuthLib/branch/main/graph/badge.svg?token=41GGNZR0PC\" alt=\"codecov\" /\u003e\n    \u003ca href=\"https://pdm-project.org\"\u003e\n      \u003cimg src=\"https://img.shields.io/endpoint?url=https%3A%2F%2Fcdn.jsdelivr.net%2Fgh%2Fpdm-project%2F.github%2Fbadge.json\" alt=\"PDM\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\n      \u003cimg src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\" alt=\"Ruff\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nSimpleSocialAuthLib is a Python library designed to simplify social authentication. It offers a secure and straightforward interface for handling OAuth2 flows and retrieving user data from popular social platforms.\n\n## Why use SimpleSocialAuthLib?\n\n- **Simplicity**: Offers a clean and intuitive API for a complex process.\n- **Flexibility**: Supports multiple social providers with a consistent interface.\n- **Type Safety**: Utilizes Python type hints for better code quality and IDE support.\n- **Extensibility**: Easily add new social providers by extending the base classes.\n- **Security**: Incorporates state parameter verification to protect against Cross-Site Request Forgery (CSRF) attacks during the OAuth2 flow.\n\n## Supported Social Providers\n\n- [x] Google\n- [x] GitHub\n- [ ] Twitter/X\n- [ ] LinkedIn\n\n## Installation\n\nYou can install SimpleSocialAuthLib using your preferred Python package manager:\n\n### Using pip\n\n```bash\n# Install the library with all providers and dependencies\npip install simplesocialauthlib[all]\n\n# Or install specific providers\npip install simplesocialauthlib[github]  # For GitHub\npip install simplesocialauthlib[google]  # For Google\npip install simplesocialauthlib[github,google]  # For both GitHub and Google\n```\n\n### Using PDM\n\n```bash\n# Install the library with all providers and dependencies\npdm add simplesocialauthlib[all]\n\n# Or install specific providers\npdm add simplesocialauthlib[github]  # For GitHub\npdm add simplesocialauthlib[google]  # For Google\npdm add simplesocialauthlib[github,google]  # For both GitHub and Google\n```\n\n### Using UV\n\n```bash\n# Install the library with all providers and dependencies\nuv add simplesocialauthlib[all]\n\n# Or install specific providers\nuv add simplesocialauthlib[github]  # For GitHub\nuv add simplesocialauthlib[google]  # For Google\nuv add simplesocialauthlib[github,google]  # For both GitHub and Google\n```\n\n## Configuration\n\nBefore using the library, you need to obtain OAuth2 credentials (a Client ID and a Client Secret) from your chosen provider.\n\n### Google\n\n1.  Go to the [Google Cloud Console](https://console.cloud.google.com/).\n2.  Create a new project or select an existing one.\n3.  In \"APIs \u0026 Services\" \u003e \"Credentials\", create \"OAuth 2.0 Client IDs\".\n4.  Select \"Web application\" as the application type.\n5.  Add your authorized redirect URI (e.g., `http://localhost:5000/login/google/callback`). This is the URL the user will be sent to after authenticating with Google.\n6.  Copy the **Client ID** and **Client Secret**.\n\n### GitHub\n\n1.  Go to your [GitHub Developer Settings](https://github.com/settings/developers) and select \"OAuth Apps\".\n2.  Click on \"New OAuth App\".\n3.  Fill in the application details. The \"Authorization callback URL\" is your redirect URI (e.g., `http://localhost:5000/login/github/callback`).\n4.  Once created, copy the **Client ID** and generate a **Client Secret**.\n\n## How It Works: The Secure OAuth2 Flow\n\nThis library enforces a secure authentication flow to protect your users:\n\n1.  **Authorization Request**: Your application calls `get_authorization_url()` on a provider instance. This generates a unique URL for the user to visit and a secret `state` token.\n2.  **Save the State**: Your application must save this `state` token in the user's session.\n3.  **User Authentication**: The user is redirected to the provider (e.g., Google), where they approve the access request.\n4.  **Callback**: The provider redirects the user back to your specified \"callback URL\" with an `authorization_code` and the `state` token.\n5.  **Verification and Sign-In**: Your application calls `sign_in()`, passing the `code`, the `state` received from the provider, and the `state` you saved in the session. The library first verifies that the states match (preventing CSRF attacks) and then exchanges the code for user data.\n\n## Usage\n\nHere is a full example using **Flask** to implement social login with Google and GitHub.\n\n```python\n# app.py\n\nimport os\n\nfrom flask import Flask, request, redirect, flash, render_template, session, url_for\nfrom dotenv import load_dotenv\n\nfrom simplesocialauthlib.providers import GithubSocialAuth, GoogleSocialAuth\n\n# Load environment variables from .env file\nload_dotenv()\n\napp = Flask(__name__)\napp.secret_key = os.environ.get(\"SECRET_KEY\", \"a-strong-default-secret-key-for-dev\")\n\n# --- Initialize Providers ---\ngoogle_auth = GoogleSocialAuth(\n    client_id=os.environ[\"GOOGLE_CLIENT_ID\"],\n    client_secret=os.environ[\"GOOGLE_CLIENT_SECRET\"],\n    redirect_uri=os.environ[\"GOOGLE_REDIRECT_URI\"],\n)\n\ngithub_auth = GithubSocialAuth(\n    client_id=os.environ[\"GITHUB_CLIENT_ID\"],\n    client_secret=os.environ[\"GITHUB_CLIENT_SECRET\"],\n)\n\n\n@app.route(\"/\")\ndef index():\n    return \"Welcome! You are not signed in. \u003ca href='/login'\u003eLogin\u003c/a\u003e\"\n\n@app.route(\"/login\")\ndef login():\n    return render_template(\"login.html\")\n\n\n# --- Google Authentication Flow ---\n@app.route(\"/login/google\", methods=[\"POST\"])\ndef login_redirect_google():\n    \"\"\"Redirect user to Google's authorization page.\"\"\"\n    if request.method != \"POST\":\n        flash(\"Invalid request method.\", \"danger\")\n        return redirect(\"/\")\n\n    authorization_url, state = google_auth.get_authorization_url()\n    session[\"oauth_state\"] = state\n    return redirect(authorization_url)\n\n\n@app.route(\"/login/google/callback\")\ndef callback_google():\n    \"\"\"Handle the callback from Google.\"\"\"\n    code = request.args.get(\"code\")\n    received_state = request.args.get(\"state\")\n    saved_state = session.pop(\"oauth_state\", None)\n\n    try:\n        # Verify state and sign in\n        user_data = google_auth.sign_in(\n            code=code, received_state=received_state, saved_state=saved_state\n        )\n        # At this point, you have the user's data.\n        # You can create a user account, log them in, etc.\n        flash(f\"Successfully signed in with Google as {user_data['full_name']}.\", \"success\")\n        return redirect(\"/\")\n\n    except Exception as e:\n        logging.error(f\"Google auth failed: {e}\")\n        flash(f\"Authentication failed: {e}\", \"danger\")\n        return redirect(url_for(\"login\"))\n\n\n# --- GitHub Authentication Flow ---\n@app.route(\"/login/github\", methods=[\"POST\"])\ndef login_redirect_github():\n    \"\"\"Redirect user to GitHub's authorization page.\"\"\"\n    if request.method != \"POST\":\n        flash(\"Invalid request method.\", \"danger\")\n        return redirect(\"/\")\n\n    authorization_url, state = github_auth.get_authorization_url()\n    session[\"oauth_state\"] = state\n    return redirect(authorization_url)\n\n\n@app.route(\"/login/github/callback\")\ndef callback_github():\n    \"\"\"Handle the callback from GitHub.\"\"\"\n    code = request.args.get(\"code\")\n    received_state = request.args.get(\"state\")\n    saved_state = session.pop(\"oauth_state\", None)\n\n    try:\n        # Verify state and sign in\n        user_data = github_auth.sign_in(\n            code=code, received_state=received_state, saved_state=saved_state\n        )\n        # At this point, you have the user's data.\n        # You can create a user account, log them in, etc.\n        flash(f\"Successfully signed in with GitHub as {user_data['username']}.\", \"success\")\n        return redirect(\"/\")\n\n    except Exception as e:\n        logging.error(f\"GitHub auth failed: {e}\")\n        flash(f\"Authentication failed: {e}\", \"danger\")\n        return redirect(url_for(\"login\"))\n\n\nif __name__ == \"__main__\":\n    app.run(debug=True, port=5000)\n```\n\n```html\n\u003c!-- templates/login.html --\u003e\n\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"utf-a\" /\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1\" /\u003e\n    \u003ctitle\u003eLogin\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eLogin with a social provider\u003c/h1\u003e\n\n    \u003cform method=\"POST\" action=\"{{ url_for('login_redirect_google') }}\"\u003e\n      \u003cbutton\n          type=\"submit\"\n          class=\"btn btn-outline-primary w-100 d-flex justify-content-center align-items-center gap-1 btn-hover-opacity\"\n      \u003e\n        Login with Google\n      \u003c/button\u003e\n    \u003c/form\u003e\n\n    \u003cform method=\"POST\" action=\"{{ url_for('login_redirect_github') }}\"\u003e\n      \u003cbutton\n          type=\"submit\"\n          class=\"btn btn-outline-primary w-100 d-flex justify-content-center align-items-center gap-1 btn-hover-opacity\"\n      \u003e\n        Login with Github\n      \u003c/button\u003e\n    \u003c/form\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Returned Data Structure\n\nThe `sign_in` method returns a `TypedDict` with a normalized structure.\n\n### Google `GoogleUserData`\n\n```python\nclass GoogleUserData(TypedDict):\n    first_name: str\n    last_name: str\n    full_name: str\n    email: str\n    email_verified: bool\n    picture: str | None\n```\n\n### GitHub `GithubUserData`\n\n```python\nclass GithubUserData(TypedDict):\n    username: str\n    full_name: str | None\n    email: str | None\n    picture: str | None\n    bio: str | None\n    location: str | None\n```\n\n## Contributing\n\nWe welcome contributions to SimpleSocialAuthLib\\! If you'd like to contribute, please follow these steps:\n\n1.  Fork the repository and install dependencies\n    ```bash\n    git clone https://github.com/Macktireh/SimpleSocialAuthLib.git\n    cd SimpleSocialAuthLib\n    ```\n    ```bash\n    pdm install\n    ```\n2.  Create a new branch for your feature or bug fix.\n    ```bash\n    git checkout -b feature/my-feature\n    ```\n3.  Implement your changes, ensuring they adhere to the existing code style and conventions.\n4.  Write comprehensive tests for your new features or bug fixes.\n5.  Update the documentation to reflect any changes in functionality or API.\n6.  Submit a pull request with a clear description of your changes.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacktireh%2Fsimplesocialauthlib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacktireh%2Fsimplesocialauthlib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacktireh%2Fsimplesocialauthlib/lists"}