{"id":2947,"library":"fastapi-sso","title":"FastAPI SSO Integration","description":"fastapi-sso is a FastAPI plugin designed to simplify integration of Single Sign-On (SSO) with common providers like Google, Facebook, Microsoft, and many others. It streamlines the OAuth2/OpenID Connect flow for authentication. The library is actively maintained with frequent minor and patch releases, currently at version 0.21.0.","status":"active","version":"0.21.0","language":"python","source_language":"en","source_url":"https://github.com/tomasvotava/fastapi-sso","tags":["fastapi","sso","oauth","openid-connect","authentication","google","facebook","microsoft"],"install":[{"cmd":"pip install fastapi-sso","lang":"bash","label":"Install core library"},{"cmd":"pip install 'fastapi-sso[google]' # for Google provider","lang":"bash","label":"Install with specific provider dependencies"}],"dependencies":[{"reason":"Required for FastAPI form data handling, often used in callback routes.","package":"python-multipart","optional":true},{"reason":"Underlying HTTP client used by SSO providers.","package":"httpx","optional":false},{"reason":"Used for JWT handling, especially in OpenID Connect flows.","package":"python-jose","optional":true}],"imports":[{"symbol":"GoogleSSO","correct":"from fastapi_sso.sso.google import GoogleSSO"},{"symbol":"FacebookSSO","correct":"from fastapi_sso.sso.facebook import FacebookSSO"},{"note":"The OpenID class is directly under `fastapi_sso.sso` for generic OpenID Connect.","wrong":"from fastapi_sso.openid import OpenID","symbol":"OpenID","correct":"from fastapi_sso.sso import OpenID"}],"quickstart":{"code":"import os\nfrom fastapi import FastAPI\nfrom fastapi_sso.sso.google import GoogleSSO\n\napp = FastAPI()\n\nGOOGLE_CLIENT_ID = os.environ.get('GOOGLE_CLIENT_ID', 'YOUR_GOOGLE_CLIENT_ID')\nGOOGLE_CLIENT_SECRET = os.environ.get('GOOGLE_CLIENT_SECRET', 'YOUR_GOOGLE_CLIENT_SECRET')\nREDIRECT_URI = os.environ.get('GOOGLE_REDIRECT_URI', 'http://localhost:8000/auth/google/callback')\n\ngoogle_sso = GoogleSSO(\n    GOOGLE_CLIENT_ID,\n    GOOGLE_CLIENT_SECRET,\n    REDIRECT_URI,\n    allow_insecure_http=True # For localhost development\n)\n\n@app.get(\"/auth/google/login\")\nasync def google_login():\n    return await google_sso.get_login_redirect()\n\n@app.get(\"/auth/google/callback\")\nasync def google_callback():\n    try:\n        user = await google_sso.verify_and_process_token(request=app.request)\n        return {\"email\": user.email, \"display_name\": user.display_name, \"provider\": user.provider}\n    except Exception as e:\n        return {\"error\": str(e)}\n\n# To run:\n# 1. Set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI in your environment\n# 2. Configure Google OAuth credentials with Redirect URI: http://localhost:8000/auth/google/callback\n# 3. uvicorn your_module:app --reload\n# 4. Access http://localhost:8000/auth/google/login in your browser","lang":"python","description":"This quickstart demonstrates setting up Google SSO. Ensure you register your application with Google Cloud Console to obtain a client ID and secret, and configure the authorized redirect URI to match `http://localhost:8000/auth/google/callback`. For production, ensure `allow_insecure_http` is `False` and `REDIRECT_URI` uses HTTPS. Environment variables are the recommended way to manage credentials."},"warnings":[{"fix":"Ensure your project uses Python 3.10 or higher. For version 0.21.0+, Python 3.10+ is required.","message":"Python 3.9 support was removed in version 0.21.0. Python 3.8 support was removed in version 0.18.0.","severity":"breaking","affected_versions":">=0.18.0, >=0.21.0"},{"fix":"Upgrade to `fastapi-sso==0.19.0` or higher immediately. Note that future `1.0.0` versions plan to use a server-side state store.","message":"A critical OAuth login CSRF vulnerability due to missing `state` validation was fixed in version 0.19.0. This is a security-critical update.","severity":"breaking","affected_versions":"<0.19.0"},{"fix":"Double-check that the `REDIRECT_URI` passed to the SSO provider object (e.g., `GoogleSSO`) precisely matches the URI registered with the third-party OAuth provider, including scheme (http/https), host, port, and path.","message":"The `redirect_uri` configured in your FastAPI-SSO instance MUST exactly match the authorized redirect URI set in your OAuth provider's developer console (e.g., Google Cloud Console). Mismatches will cause authentication failures.","severity":"gotcha","affected_versions":"all"},{"fix":"Toggle `allow_insecure_http` based on your environment. Use HTTPS for all production deployments.","message":"When developing locally, ensure `allow_insecure_http=True` is set for providers if you are using `http://localhost`. Remember to set this to `False` in production environments for security.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.21.0':53 'activ':42 'authent':38,60 'common':22 'connect':35,59 'current':50 'design':11 'facebook':26,62 'fastapi':1,5,9,54 'fastapi-sso':4 'flow':36 'frequent':45 'googl':25,61 'integr':3,14 'librari':40 'like':24 'maintain':43 'mani':29 'microsoft':27,63 'minor':46 'oauth':56 'oauth2/openid':34 'openid':58 'openid-connect':57 'other':30 'patch':48 'plugin':10 'provid':23 'releas':49 'sign':18 'sign-on':17 'simplifi':13 'singl':16 'sso':2,6,20,55 'streamlin':32 'version':52","created_at":"2026-04-11T09:14:25.444075+00:00","updated_at":"2026-04-16T14:56:50.756680+00:00","problems":[{"fix":"Ensure the required scopes (e.g., 'openid', 'email', 'profile') are requested during SSO initialization. Check the raw `token` object received from the `authorize_access_token` call to understand its structure and adapt the code to correctly extract user information. For `Authlib` users (which `fastapi-sso` builds upon), consider using `userinfo` from the token if `parse_id_token` is problematic. For example: `user_info = token.get('userinfo')` or `user_info = await oauth.provider.userinfo(token=token)` if `id_token` itself is not directly in the top level of the token.","cause":"This error often occurs when the `id_token` is missing or not structured as expected in the OAuth provider's response, particularly when trying to parse user information after successful authentication. This can be due to incorrect `scope` settings or changes in the provider's response format.","error":"KeyError: 'id_token'"},{"fix":"Verify that the `redirect_uri` passed to `fastapi-sso` (both in initialization and `get_login_redirect` if provided) exactly matches the one registered with the OAuth provider. Ensure the `client_id` and `client_secret` are correct. Process the authorization code immediately after receiving it to avoid expiration. Also, verify that your server's clock is synchronized.","cause":"This error, returned by the OAuth provider, indicates an issue with the authorization code during the token exchange step. Common causes include an expired authorization code (they are usually short-lived), a mismatch between the `redirect_uri` used in the initial authorization request and the token exchange, or incorrect `client_id`/`client_secret` configuration.","error":"{\"error\":\"invalid_grant\", \"error_description\":\"The provided access grant is invalid, expired, or revoked...\"}"},{"fix":"Add `SessionMiddleware` to your FastAPI application with a secure `secret_key`. Example: `app.add_middleware(SessionMiddleware, secret_key='your-super-secret-key-at-least-32-bytes')`. The secret key should be a long, random string.","cause":"`fastapi-sso` relies on `Authlib`, which often uses FastAPI's `request.session` to store temporary state (like the OAuth state parameter). This error means that `starlette.middleware.sessions.SessionMiddleware` has not been added to your FastAPI application, or it's misconfigured.","error":"SessionMiddleware must be installed to access request.session"},{"fix":"Ensure that your `redirect_uri` in `fastapi-sso` initialization and the OAuth provider's settings explicitly match the *external* URL your users access. When behind a proxy, configure FastAPI to trust proxy headers (e.g., `app = FastAPI(root_path=\"/subpath\")`). You might need to adjust Nginx configurations (e.g., `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;`) and potentially use `allow_insecure_http=True` during local development if not using HTTPS.","cause":"This problem arises when FastAPI (or `Authlib`/`fastapi-sso`) perceives a different `redirect_uri` than what the OAuth provider sends or what the application is configured for, especially when deployed behind a reverse proxy like Nginx or Docker. The proxy might be rewriting headers or the application isn't correctly configured to trust `X-Forwarded-For` headers, leading to a URL mismatch.","error":"Error with Redirect URI When Defined in get_login_redirect Using HTTPS with Nginx / The response was received at https://containerip/ instead of https:myserverurl"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.21.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://tomasvotava.github.io/fastapi-sso/","github":"https://github.com/tomasvotava/fastapi-sso","docs":"https://tomasvotava.github.io/fastapi-sso/","changelog":null,"pypi":"https://pypi.org/project/fastapi-sso/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["auth-security","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}