SeaCat Auth is a microservice that provides authentication, authorization, identity management, session management and other access control features. It is designed to be used as an access control app for other microservices.
📖 Documentation is available at docs.teskalabs.com.
SeaCat Auth provides a rich REST API documented in a Postman collection.
SeaCat Auth uses uv for dependency management. Requires Python 3.11+.
-
Install uv (see uv installation).
-
Clone this repository and enter it:
git clone https://github.com/TeskaLabs/seacat-auth.git
cd seacat-auth- Install project dependencies into a local virtual environment:
uv syncOptional LDAP support (needs system LDAP development headers):
uv sync --extra ldap- Start SeaCat Auth with a config file (for example
etc/seacatauth.conf):
uv run python seacatauth.py -c etc/seacatauth.confBy default, ASAB is installed from GitHub. For local ASAB development, use an editable checkout so changes apply without reinstalling.
- Clone ASAB next to this repository (sibling directories):
# from the parent directory that contains seacat-auth/
git clone https://github.com/TeskaLabs/asab.gitLayout:
├── asab/
└── seacat-auth/
- From the
seacat-authdirectory, point theasabdependency at the local path:
cd seacat-auth
uv add --editable ../asabThis updates pyproject.toml with a [tool.uv.sources] entry similar to:
[tool.uv.sources]
asab = { path = "../asab", editable = true }- Sync and run:
uv sync
uv run python seacatauth.py -c etc/seacatauth.confDo not commit the local [tool.uv.sources] override. Before committing, restore the git source (for example git checkout -- pyproject.toml uv.lock) so CI and Docker keep installing ASAB from GitHub.
- Authentication
- Second-factor Authentication (2FA) / Multi-factor Authentication (MFA)
- Supported factors:
- Password
- FIDO2 / Webauthn
- Time-based One-Time Password (TOTP)
- SMS code
- Subnet (ROADMAP)
- Request header (X-Header)
- Machine-to-Machine
- API keys (ROADMAP)
- Authorization
- Roles
- Role-based access control (RBAC)
- Policies (ROADMAP)
- Attribute-based access control (ABAC) (ROADMAP)
- Identity management
- Federation of identities
- Supported providers:
- File (htpasswd)
- In-memory dictionary
- MongoDB
- ElasticSearch
- LDAP and Active Directory
- Custom provider
- Multitenancy including tenant management for other services and applications
- Session management
- Single-sign on
- OpenId Connect / OAuth2
- Proof Key for Code Exchange aka PKCE for OAuth 2.0 public clients
- Authorization/authentication introspection backend for NGINX
- Authorization/authentication interceptor for 3rd party applications (aka Batman)
- Kibana & ElasticSearch
- Grafana
- Docker registry / NGINX (ROADMAP)
- HTTP Basic Authentication
- Audit trail
- Provisioning mode
- Structured logging (Syslog) and telemetry
- Authentication Service
- Authorization Service
- API Service
- Tenant Service
- Credentials Service
- Session Service
- Notification Service
- Audit Service
- OpenIDConnect Service
- Provisioning Service
- Batman Service
- Cookie Service
This section clarifies role of various components in the SeaCat Auth ecosystem.
There are two separate Web UIs (user interfaces):
- SeaCat WebUI provides a graphical interface for Seacat Auth administration.
- SeaCat Auth WebUI provides a login form, a password reset screen, and self-care user portal.
The whole site installation can be dockerized and deployed using docker-compose, see the documentation.
Docker image is available from DockerHub
Nginx is used to forward requests coming from outside of the environment to protected locations. These requests are first forwarded to SeaCat Auth, where their authentication state is evaluated. If already authenticated, the request is allowed into the protected space.
Is employed by SeaCat Auth for storage of known users and other related persistent data.
uv sync --only-group test
uv run --no-sync python -m unittest test