Skip to main content

sso general utility for services connected to sso

Project description

Stable Version tests Coverage Status

Awesome SSO

A library designed to host common components for a cluster of microservices sharing a single sign on.


  • A common exception class, supporting both status code and custom error code to map to more detailed error message or serve as i18n key.
  • A common FastAPI app for interaction with service, like login ,registration and unregistration.
  • a connector for minio object store.
  • a connector for beanie, a mongo odm compatible with pydantic.



  1. pip install awesome-sso


Using fast API as example, we may simply throw exception with a proper status code, and an optional error code. We may also supply arbitrary key value in args dict, to help frontend render better error message.

from awesome_sso.exceptions import NotFound
from fastapi import APIRouter

router = APIRouter()

def get(id: str):
        obj = find_by_id(id)
    except Exception as e:
        raise NotFound(message='transaction not found' % id, error_code='A0001', args={id: id})

And we may implement a common error handler to convert all these errors to proper response schema

from awesome_sso.exceptions import HTTPException
from fastapi.requests import Request
from fastapi.responses import JSONResponse

async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
            'detail': exc.detail,
            'error_code': exc.error_code,

This would result in a response with status code 404, and body

  "status_code": 404,
  "detail": {
    "message": "transaction not found",
    "id": "some_id"
  "error_code": "A0001"

With this response, frontend can decide to simply render detail, or map it to detailed message. If error_code "A0001" correspond to the following i18 n entry

"error.A0001": {"en-US": "transaction can not be found with supplied {id}: {message}"}

we may format message accordingly with

errorMessage = formatMessage({ id: `error.${}` },;

Note that error code is not supplied, is default to status code. So it is always safe to simply use error_code in frontend to decide what to render.

Data Store


refer to tests/


refer to tests/service/

from beanie import init_beanie
from motor.motor_asyncio import AsyncIOMotorClient
from awesome_sso.service.user.schema import AwesomeUser

def init_mongo():
    settings = YOUR_SETTINGS()
    models = [AwesomeUser]
    cli = AsyncIOMotorClient(settings.mongodb_dsn)
    await init_beanie(
    for model in models:
        await model.get_motor_collection().drop()
        await model.get_motor_collection().drop_indexes()


configure service settings

from awesome_sso.service.settings import Settings

settings = Settings()
    symmetric_key='YOUR_SYMMETRIC_KEY',  # to encode and decode service token
    public_key='YOUR_PUBLIC_KEY',  # to decode the token signed by sso
    user_model=USER_MODEL,  # user orm needs to inherit AwesomeUser from `awesome_sso.user.schema`
    service_name='YOUR_SERVICE_NAME',  # for service discovery, to recognize service
    sso_domain='YOUR_SSO_DOMAIN',  # for service registration and sync user

initial service and mount to your application

from awesome_sso.service import Service
from fastapi import FastAPI

app = FastAPI()
service = Service()

then open the api doc, you will see the apis in awesome_sso.service.user.route


Installing Poetry

  1. create your own environment for poetry, and simply run: pip install poetry
  2. alternatively, you can refer to poetry's official page
  3. to be able to use poe directly, pip install poethepoet


  1. project setup: poetry install
  2. create your own branch to start developing new feature.
  3. before creating pr, make sure you pass poe lint and ./
    • what happened inside ./ is that a minio server is setup for you temporarily, and teardown and unit test is finished.
    • notice that poe test would also work if you already have a minio up and running. You need the following env variable: MINIO_ACCESS_KEY, MINIO_SECRET_KEY, MINIO_ADDRESS upon running poe test.
  4. for a list of available poe command, poe
  5. after you submit a pr, you should check if pipeline is successful.


  1. poetry version [new_version]
  2. git commit -m"Bump version"
  3. git push origin develop
  4. create new release on github.
  5. Create release off develop branch, auto generate notes, and review release note.
  6. Publish release

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

awesome-sso-0.5.3.tar.gz (16.7 kB view hashes)

Uploaded source

Built Distribution

awesome_sso-0.5.3-py3-none-any.whl (25.6 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page