Skip to content

About

About TeskaLabs SeaCat Auth

TeskaLabs SeaCat Auth is a microservice that provides authentication, authorization, identity management, session management, and other features. It is designed to be used as an access control and/or single sign-on (SSO) solution for other microservices and applications.

Seacat Auth implements OAuth 2.0, a widely supported authorization protocol, which makes it compatible with many applications. Seacat Auth also provides tools that make integrating non-OAuth applications into an OAuth ecosystem easy.

Seacat Auth also functions as OpenID Connect provider, offering useful features such as single sign-on (SSO) and authentication using JSON web tokens (JWTs).

TeskaLabs SeaCat Auth is an open source project.

Source code is available on GitHub.
SeaCat Auth is built on TeskaLabs ASAB framework.

If you want to install, configure, or integrate SeaCat Auth, or manage user access, visit the Administration guide.

If you need help with your user account in SeaCat Auth, visit the User guide.

SeaCat Auth user interface

SeaCat Auth includes an intuitve, complete UI.

Login screen

SeaCat Auth login screen SeaCat Auth login screen

Access control screens

SeaCat Auth resources screen SeaCat Auth resources screen

SeaCat Auth tenants screen SeaCat Auth tenants screen

User account settings screen

SeaCat Auth account settings SeaCat Auth account settings

Made with by TeskaLabs

SeaCat Auth is a product of TeskaLabs.

Main features of TeskaLabs SeaCat Auth

Authentication

  • Second-factor Authentication (2FA) / Multi-factor Authentication (MFA)
  • Supported factors:
  • Machine-to-Machine Authentication
    • API keys (ROADMAP 🗺️)
  • End-to-End encryption in login sessions

Authorization

Identity management

General

User interface

  • Full localization / internationalization

Web User Interface for users

  • Login
  • Registration of new users
  • Self-care portal

Web User Interface for administrators

  • Credentials administrations
  • Tenant management
  • RBAC management
  • Session management

Administration guide

Administration guide

What's in the Administration guide?

Use the Administration guide if you want to:

  • Install SeaCat Auth and integrate it into another app as an authentication and authorization component
  • Configure SeaCat Auth
  • Manage access control (credentials, tenants, roles, etc.) within the SeaCat Auth app (web UI)
  • Learn more about SeaCat Auth

Access control

Access control

You can manage credentials (users), resources, roles, tenants, sessions, and clients in the SeaCat Auth web UI. For more information about these concepts and their function, visit Key terms.

Key terms

Credentials

Credentials are users. Credentials are represented by user names and can include an email address and phone number as supplemental information. You can assign tenants and roles to credentials, as well as manage credentials' sessions.

Tenant

A tenant is one entity with its own set of data. Each tenant is an isolated space, like tenants in an apartment building or block of flats. Every tenant's data is completely separated from all other tenants' data in the UI.

One tenant can be accessible by multiple users, and users can have access to multiple tenants. You can control which users can access which tenants by assigning credentials to tentants or vice-versa.

Resource

Resources are the most basic unit of authorization. They are single and specific access permissions.

Examples:

  • Permission to access a specifc page
  • Permission to delete a specific type of item
  • Permission to make changes to a group of files

Role

A role is a container for resources. Since resources are single permissions, a role is a set of permissions. You can add any number and combination of resources to a role.

Client

Clients are additional applications and services that are accessing the app.

Session

A session is an active login period.

Credentials

Credentials are users. Credentials are represented by user names and can include an email address and phone number as supplemental information. You can assign tenants and roles to credentials, as well as manage credentials' sessions.

Credentials page

On the Credentials screen, you can see information for each set of credentials:

  • Name: The username that the user logs in with
  • Provider: The type of credentials, which can be ext (human), or machine.
  • Tenants: Which tenants are assigned to the credentials
  • Roles: Which roles are assigned to the credentials

Create new credentials

  1. To create a new user, click Create new credentials on the Credentials page.
  2. Choose a provider from the dropdown: human or machine.
  3. Enter a username.
  4. Enter an email address and phone number (optional).
  5. To email the user instructions for setting their password, select Send instructions to set password.
  6. Click Create credentials.

Create new credentials Create new credentails

Bulk actions

Bulk actions allow you to assign multiple roles and tenants to multiple users at the same time. To enter bulk actions mode, click Bulk actions at the top of the screen.

Tenants

A tenant is one entity with its own set of data. Each tenant is an isolated space, like tenants in an apartment building or block of flats. Every tenant's data is completely separated from all other tenants' data in the UI. One tenant can be accessible by multiple users, and users can have access to multiple tenants.

You can control which users can access which tenants by assigning credentials to tentants or vice-versa.

On the Tenants screen, you can see:

  • Tenant names
  • Date the tenant was created

Creating a tenant

  1. Click New tenant on the Tenants page.
  2. Enter the name of the tenant.
  3. Click Create a tenant.

Adding credentials to a tenant

  1. From the Tenants page, click on the tenant.
  2. Click Assign credentials, and select credentials from the dropdown list.

Resources

Resources are the most basic unit of authorization. They are single and specific access permissions.

How to use resources

  • To grant credentials access to resources, group resources into a role, then assign the role to credentials. In other words, you cannot assign resources directly to credentials; credentials can have access to a resource only through a role.
  • You can assign the same resource to several roles.
  • A role can have multiple resources. A role can be assigned to multiple credentials.

On the Resources screen, you can see:

  • Resource ID: The name of the resource
  • Description: A user-created and human-readable description of what permission the resource grants
  • Created at: Date and time the resource was created

Creating a resource

  1. From the Resources screen, click New resource.
  2. Name the resource, enter a short description, and click Create resource.

Deleted resources

  1. To view deleted resources, click Deleted resources on the Resources screen.
  2. To renew a resource (make it active again), click the circular arrow at the end of the resource's line.

Included resources

The following resources are automatically available in an installation of SeaCat Auth:

  • seacat:tenant:create: Grants right to create a new tenant
  • seacat:role:assign: Assign and unassign tenant roles.
  • seacat:role:edit: Create, edit and delete tenant roles. This does not enable the bearer to assign SeaCat system resources.
  • seacat:role:access: Search tenant roles, view role detail and list role bearers.
  • seacat:tenant:assign: Assign and unassign tenant members, invite new users to tenant.
  • seacat:tenant:delete: Delete tenant.
  • seacat:tenant:edit: Edit tenant data.
  • seacat:tenant:access: List tenants, view tenant detail and see tenant members.
  • seacat:client:edit: Edit and delete clients.
  • seacat:client:access: List clients and view client details.
  • seacat:resource:edit: Edit and delete resources.
  • seacat:resource:access: List resources and view resource details.
  • seacat:session:terminate: Terminate sessions.
  • seacat:session:access: List sessions and view session details.
  • seacat:credentials:edit: Edit and suspend credentials.
  • seacat:credentials:access: List credentials and view credentials details.

Roles

A role is a container for resources. Since resources are single permissions, a role is a set of permissions. You can add any number and combination of resources to a role.

How to use roles

  • Add resources to a role to create a set of permissions
  • Assign roles to credentials (users) to grant users that set of permissions
  • A role can have multiple resources
  • The same resource can be present in multiple roles
  • Multiple credentials can be assigned the same role

Creating a role

  1. From the Roles page, click Create role.
  2. Name the role, and select or deslect Global role.
  3. Click Create role.

Editing roles

  1. From the Roles page, click on the role you'd like to edit.
  2. To edit resources in a role, click Edit in the Resources section.
  3. To assign the role to credentials, click Assign credentials and choose users from the dropdown list.

Clients

A client is an entity that uses authentication and authorization services provided by the authorization server. This authorization enables the client to access protected resources. In other words, clients are additional apps connected to SeaCat Auth.

See the Clients reference page for more technical details.

Clients page

On the clients page, you can see:

  • Client name: The name of the client
  • Client ID: A non-editable, unique, automatically generated ID. (More here.)
  • Created at: Creation date and time
  • Client URI: URL of the home page of the client

Sessions

A session is an active login period.

Ending a session

You have multiple options for ending sessions. Ending a session logs the user out.

From the Sessions page:

  • Click on the red icon on the session's line
  • Click on the session's name, then click Terminate session
  • To terminate all sessions (logging all users out), click Terminate all on the Sessions page

Installation

Quick start

This is a quick start guide for TeskaLabs SeaCat Auth, it should get you up to speed swiftly.

Prerequisites

Following list contains all prerequisities for a successful deployment of the SeaCat Auth:

Note: This guide is designed for Windows (using WSL2 and Docker), Mac OS (using Docker Desktop) and Linux.

Step 1: Create the deployment directory

We assume in this guide that SeaCat Auth will be deployed into the /opt/site-auth.

Note: We also call the deployment directory a "site".

The structure of a deployment directory:

/opt/site-auth
  seacatauth-conf/
    seacatauth.conf
  mongodb-data/
  nginx-conf/
    nginx.conf
  nginx-root/
    index.html
  seacat-auth-webui/
  seacat-webui/
  log/
  docker-compose.yml

The SeaCat Auth GitHub repository contains a template of the deployment directory in the ./doc/docker directory. This template of the deployment directory can be also downloaded here.

Step 2: Adjust SeaCat Auth configuration

Step 3: Install Web User Interfaces

  • Install SeaCat Auth Web UI into ./seacat-auth-webui/ from https://asabwebui.z16.web.core.windows.net/seacat-auth/master/seacat-auth-webui.tar.lzma

  • Install SeaCat Web UI into ./seacat-webui/ from https://asabwebui.z16.web.core.windows.net/seacat-auth/master/seacat-auth-webui.tar.lzma

Step 4: Launch SeaCat Auth

Execute docker-compose up -d in the /opt/site-auth directory.

Now SeaCat Auth runs in the so-called provisioning mode. You can use SeaCat Web UI to finish the setup by creating users etc. For that step, please proceed to setting up SeaCat Auth in provisioning mode.

Next steps

Deploying SeaCat Auth with custom hostname and HTTPS

This part of the guide assumes that your server has a proper public domain name.

Custom hostname on localhost

To run SeaCat Auth locally with custom hostname, just add the hostname to /etc/hosts on your machine, for example

127.0.0.1  auth.test.loc

Since you can't obtain a trusted SSL certificate via ACME challenge for internal hostnames, you need to generate a self-signed SSL certificate:

openssl req -x509 -newkey rsa:4096 -keyout nginx-conf/key.pem -out nginx-conf/cert.pem -days 365 -nodes

Note that self-signed certificates are not trusted, and produce warnings on most devices. They should be only used for development purposes in local environments.

Provisioning mode

Next, move on to provisioning mode.

Provisioning mode

When you install a new clean instance of SeaCat Auth, there is no conventional of logging in since there are no user accounts. Provisioning mode creates temporary superuser credentials which can be used to log in and create an ordinary account for yourself.

Running SeaCat Auth in provisioning mode

There are two ways to activate providioning mode: - The first option is to execute seacatauth.py with --provisioning argument

python3 seacatauth.py -c /conf/seacatauth.conf --provisioning
  • The other option is to set the SEACAT_AUTH_PROVISIONING environment variable to 1 or TRUE, export it and run SeaCat Auth. This is easily done in docker-compose.yml:
seacat-auth-svc:
  ...
  environment:
    - SEACAT_AUTH_PROVISIONING=1

Logging in

When you start the provisioning mode, the following text will be printed into the SeaCat Auth log:

SeaCat Auth is running in provisioning mode.

Use the following credentials to log in:

    USERNAME:   superuser
    PASSWORD:   **************

Use those credentials to log in.

In the WebUI you will see that a provisioning tenant and a provisioning role have been created. These are temporary and will be automatically deleted when the app is stopped.

NOTE The superuser credentials are deleted and recreated with a new password everytime the app is restarted.

Setting up the environment

  • Create a tenant. Any user must have at least one tenant assigned to them to be allowed into SeaCat WebUI.
  • Create a user account. The password will be sent via email or SMS, depending on what contact info you fill in. Make sure that your SMTP or SMS provider is set up properly in SeaCat Auth config.
  • Open the user detail and assign the tenant that you created earlier and the */superuser role.
  • You can now log out of the provisioning superuser session.
  • Check if you have received the reset password link for your new credentials. Proceed to reset the password and then log in!

NOTE Do not assign the provisioning tenant or the provisioning superuser role to any other user, as it is temporary and will be deleted when the app is restarted and provisioning ends.

Disable provisioning mode

To disable provisioning mode, simply run the app without the --provisioning flag and with SEACAT_AUTH_PROVISIONING set to 0 or unset completely (deleted from docker-compose.yml).

Configuration

Minimum required configuration

SeaCat Auth is primarily configured via a .conf file. For general info about configuration (syntax etc.), refer to the respective page in ASAB docs.

Config file example

This is how a SeaCat Auth config file can look like:

[general]
public_api_base_url=http://localhost/seacat_auth/api
auth_webui_base_url=http://localhost/auth
include=/conf/secret.conf

[logging:file]
path=/log/seacat-auth.log

[web]
listen=0.0.0.0 8082

[web:public]
listen=0.0.0.0 8081

[asab:storage]
type=mongodb
mongodb_uri=mongodb://mongo:27017/
mongodb_database=auth

[seacatauth:credentials]
policy_file=/conf/credentials-policy.json
ident_fields=username:ignorecase email:ignorecase

[seacatauth:credentials:mongodb:default]
mongodb_uri=mongodb://mongo:27017
mongodb_database=auth
tenants=yes
register=no

[seacatauth:credentials:htpasswd:file]
path=/conf/htpasswd

[seacatauth:google]
; client_id in secret.conf
; client_secret in secret.conf

[seacatauth:cookie]
name=SeaCatSCI
domain=localhost

[seacatauth:session]
expiration=1h
touch_extension=0.5
maximum_age=30d
; aes_key in secret.conf

[seacatauth:communication:email:smtp]
sender_email_address=info@teskalabs.com
host=smtp.sendgrid.net
ssl=no
starttls=yes
; user in secret.conf
; password in secret.conf

Credentials

Credentials

SeaCat Auth requires at least one credentials provider to function properly. By default, it uses a provider with MongoDB backend.

Credentials policy

It is possible to configure which credentials fields are required for creating or registering new credentials. You can also specify which credentials fields can be edited by whom.

Configuration

To enable custom configuration, add the policy_file option to the service config file and specify the path to your policy file:

[seacatauth:credentials]
policy_file=/path/to/credentials-policy.json

Policy options

The structure of the policy file follows a simple schema:

{
    "<field_name>": {
        "<context>": "<policy>"
    }
}

It is possible to configure the following fields: - username - email - phone

For all those fields there are two configurable contexts: credentials creation and registration. Their policy options are: - disabled: The field is not allowed in this context. - allowed: The field is allowed, but not required in this context. - required: The field is required in this context (and must not be empty).

The fields email and phone have an additional context: editable_by. Its policy options are: - nobody: The field is not editable, not even by a superuser. - admin_only: The field is editable only by a superuser. - anybody: The field is editable by anyone. This also makes it possible to update the field in one's own credentials.

Policy file example

The following is the default policy configuration:

{
    "username": {
        "creation": "required",
        "registration": "required"
    },
    "email": {
        "creation": "required",
        "registration": "required",
        "editable_by": "anybody"
    },
    "phone": {
        "creation": "allowed",
        "registration": "allowed",
        "editable_by": "anybody"
    }
}

Credentials providers

MongoDB

  • MongoDB is the default storage backend for SeaCat Auth.
  • Credentials follow a predefined schema:
credential:
    _id: unique ID (bson.ObjectId),
    _c: creation time (UTC timestamp),
    _m: last modification time (UTC timestamp),
    _v: version (int),
    username: (str),
    email: (str),
    phone: (str),
    __password: password hash (str),
    suspended: (bool),
    data: additional custom data (object),
  • To add a MongoDB provider, add a [seacatauth:credentials:mongodb:<provider_name>] section in the config.

Example config

[seacatauth:credentials:mongodb:default]
mongodb_uri=mongodb://mongo:27017
mongodb_database=auth
tenants=yes
register=no

External MongoDB (xmongodb)

  • Suitable for external Mongo databases with credentials that do not follow the schema expected by the default MongoDB provider.
  • Read-only.
  • To add a XMongoDB provider, add a [seacatauth:credentials:xmongodb:<provider_name>] section in the config.
  • You must specify the list, get and locate aggregation pipelines/queries.
  • The output of the aggregation query should match the credential schema of the default MongoDB provider, i.e. the credentials object should contain a unique _id, email, __password and optionally username and the other fields. Use the $project operation to map your database fields to these aliases. Additional fields in the output are considered to be part of custom_data.

NOTE: The $ sign in the queries must be doubled as $$ (escape necessary in the configparser format).

List query

  • Used for iterating through credentials, for example in credentials list API (GET /credentials).
  • Query result is expected to contain _id, username, email, optionally phone and suspended.

Get query

  • Used for accessing spectific credentials, for example in credentials detail API (GET /credentials/<credentials_id>).
  • Query result is expected to contain _id, username, email, __password, optionally phone and suspended.
  • Use the $match operation with the bind parameter %(_id)s in place of the credential ID.

NOTE: Use {"$$oid": %(_id)s} instead of ObjectId(%(_id)s).

Locate query

  • Used for locating login candidates by username, email, phone or other fields.
  • Query result is expected to contain _id, optionally username and email.
  • Use the $match operation with the bind parameter %(ident)s to match credentials by ident (the string that the user entered in the login form).

Example config

[seacatauth:credentials:xmongodb:users]
mongodb_uri=mongodb://localhost:27017
database=test
collection=users
list=
    [
        {"$$project": {
            "_id": true,
            "username": true,
            "email": true,
            "phone": true,
            "suspended": true
        }}
    ]
get=
    [
        {"$$match": {
            "_id": {"$$oid": %(_id)s}
        }},
        {"$$project": {
            "_id": true,
            "username": true,
            "email": true,
            "phone": true,
            "suspended": true,
            "likes": true,
            "__password": true
        }}
    ]
locate=
    [
        {"$$match": {
            "$$or": [
                {
                    "username": %(ident)s
                },
                {
                    "email": %(ident)s
                }
            ]
        }},
        {"$$project": {
            "_id": true,
            "username": true,
            "email": true,
            "phone": true,
            "suspended": true
        }}
    ]

LDAP / ActiveDirectory

  • Read-only
  • Declared by [seacatauth:credentials:ldap:<provider_name>] config section

Example config

[seacatauth:credentials:ldap:external]
uri=ldaps://localhost:636
base=OU=Users,OU=Employees,DC=ThisCompany,DC=local
filter=(cn=*)
attrusername=sAMAccountName
tls_cafile=/conf/secret/local-ldap-cert.pem
tls_require_cert=allow

MySQL

  • To add a MySQL provider, add a [seacatauth:credentials:mysql:<provider_id>] section in the config.
  • It can be configured to be either editable or read-only.

Read-only provider

  • MySQL provider is read-only by default.
  • list, get and locate queries must be specified.
  • Use AS clauses to map the result fields to expected SeaCat Auth fields _id, username, email, phone, suspended and __password.
  • Where needed, use pyformat-style named bind variables.

List query

  • Used for iterating through credentials, for example in credentials list API (GET /credentials).
  • Query result is expected to contain _id, username, email, optionally phone and suspended. Use AS clauses to add these aliases to the database fields.
  • Use ORDER BY clause to ensure constant ordering.

Get query

  • Used for accessing spectific credentials, for example in credentials detail API (GET /credentials/<credentials_id>).
  • Query result is expected to contain _id, username, email, __password, optionally phone and suspended. Use AS clauses to add these aliases to the database fields.
  • Use WHERE clause with the bind parameter %(_id)s to match the database object by its id.
  • Additional data fields which should be included in the credentials object must be also listed in configuration as data_fields.

Locate query

  • Used for locating login candidates by username, email, phone or other fields.
  • Query result is expected to contain _id, optionally username and email.
  • Use WHERE clause with the bind parameter %(ident)s to match credentials by ident (the string that the user entered in the login form).

Example config

[seacatauth:credentials:mysql:external]
host=localhost
port=3306
user=root
password=rootpassword
database=auth
data_fields=firstName lastName
list=
    SELECT `id` AS '_id', `userName` AS 'username', `userEmail` AS 'email', `userPhone` AS 'phone'
    FROM `users` 
    ORDER BY `id` ASC;
get=
    SELECT `id` AS '_id', `userName` AS 'username', `userEmail` AS 'email', `userPhone` AS 'phone', `userPwd` AS '__password', `userSuspened` AS 'suspended', firstName, lastName
    FROM `users` 
    WHERE `id` = %(_id)s;
locate=
    SELECT `id` AS '_id', `userName`, `userEmail`
    FROM `users` 
    WHERE (LOWER(`userName`) = %(ident)s) OR (LOWER(`userEmail`) = %(ident)s);

Editable provider

  • To enable creating, updating and deleting users, specify editable=yes in config.
  • This requires specifying the create, update and delete queries.

Example config

[seacatauth:credentials:mysql:external]
editable=yes
user=root
password=rootpassword
database=auth
data_fields=firstName lastName
list=
    SELECT `id` AS '_id', `userName` AS 'username', `userEmail` AS 'email', `userPhone` AS 'phone'
    FROM `users` 
    ORDER BY `id` ASC;
get=
    SELECT `id` AS '_id', `userName` AS 'username', `userEmail` AS 'email', `userPhone` AS 'phone', `userPwd` AS '__password',  `userSuspened` AS 'suspended', firstName, lastName
    FROM `users` 
    WHERE `id` = %(_id)s;
locate=
    SELECT `id` AS '_id', `userName`, `userEmail`
    FROM `users` 
    WHERE (LOWER(`userName`) = %(ident)s) OR (LOWER(`userEmail`) = %(ident)s);
create=
    INSERT INTO `users` 
    (`userName`, `userEmail`, `userPhone`) 
    VALUES (%(username)s, %(email)s, %(phone)s);
update=
    UPDATE `users` 
    SET `userEmail` = %(email)s, `userPhone` = %(phone)s, `userSuspened` = %(suspended)s, `userPwd` = %(__password)s
    WHERE `id` = %(_id)s;
delete=
    DELETE FROM `users` 
    WHERE `id` = %(_id)s;

Htpasswd

  • Read-only
  • To create a htpasswd provider, add a [seacatauth:credentials:htpasswd:<provider_name>] section in the config and specify a path to your htpasswd file.
  • You can create a new htpasswd file using the htpasswd command, for example 
    htpasswd /opt/site/seacatauth-conf/htpasswd john-smith

Example config

[seacatauth:credentials:htpasswd:local]
path=/conf/htpasswd

In-memory (Dictionary)

  • Non-persistent editable provider
  • Declared by [seacatauth:credentials:dict:<provider_name>] config section

Example config

[seacatauth:credentials:dict:inmemory]

Authentication and login

External login

SeaCat Auth supports login via third party authentication providers. This allows users to use their Google or Github account to log into SeaCat Auth.

SeaCat Auth currently supports these login providers:

  • Google
  • Office 365
  • Github
  • MojeID
  • Facebook
  • AppleID

Usage

Once configured, external login options are available on the login screen as an alternative to the standard SeaCat Auth login.

Login screen with external login

Any user can enable or disable their external login options on their My account screen.

My account screen with external login

Setting up external login providers

Setting up external login requires registering and configuring your SeaCat Auth site at the respective provider and configuring the SeaCat Auth service itself.

Register your SeaCat Auth application

Once you select which login provider you want to set up, proceed to their website to register your SeaCat Auth application. You will receive Client ID and Client secret which you will use in SeaCat Auth configuration.

Provide redirect URIs

Most OAuth2 providers will require you to specify a list of exact authorized redirect URIs. If that is the case, you need to provide two URIs in the following format:

<SEACAT_PUBLIC_API_BASE_URL>/public/ext-login/<LOGIN_PROVIDER_ID>
<SEACAT_PUBLIC_API_BASE_URL>/public/ext-login-add/<LOGIN_PROVIDER_ID>

For example, if your public SeaCat Auth API is running at https://auth.example.xyz/auth/api/seacat_auth/ and you want to configure login with google, add these addresses to the list of authorized redirect URIs in Google API Credentials.

https://auth.example.xyz/auth/api/seacat_auth/public/ext-login/google
https://auth.example.xyz/auth/api/seacat_auth/public/ext-login-add/google

Other providers (e.g. Github) do not require a list of exact URIs but rather a single path that all of your redirect URIs will start with. In such cases just provide the base URL of your SeaCat Auth public API, for example

https://auth.example.xyz/auth/api/seacat_auth/public/

Configure SeaCat Auth

Finally, you can add a section defining your external login provider in the SeaCat Auth config file. You will need at least the Client ID and the Client secret that you received at your login provider.

The config section name is always in the format [seacatauth:<LOGIN_PROVIDER_ID>]. See below for config examples of the individual login providers.

Supported providers

SeaCat Auth currently supports the following external login providers:

  • Google
  • Office 365
  • Github
  • Moje ID

Google

Provider ID: google

Register your SeaCat Auth app in Google API Credentials.

[seacatauth:google]
client_id=a2c4e6...
client_secret=1b3d5f...

Office 365

Provider ID: office365

Register your SeaCat Auth app in Azure Active Directory.

In addition to client ID and client secret, Office 365 login also requires you to fill in your tenant ID.

[seacatauth:office365]
tenant_id=def123...
client_id=a2c4e6...
client_secret=1b3d5f...

Github

Provider ID: github

Register your SeaCat Auth app in your Github developer settings.

[seacatauth:github]
client_id=a2c4e6...
client_secret=1b3d5f...

MojeID

Provider ID: mojeid

Sign up for a MojeID provider account. Follow their documentation to obtain client ID and secret.

[seacatauth:mojeid]
client_id=a2c4e6...
client_secret=1b3d5f...

AppleID

Provider ID: appleid

Register your app in Apple Developer program Service ID settings to obtain client ID. Apple returns e-mail and username in the response right after OAuth2 /authorize call, so we do not need client_secret, because we do not need to hit the /token endpoint at all.

Sign in with Apple documentation 

[seacatauth:appleid]
client_id=a2c4e6...

Registering unknown users via webhook

When an unknown user logs in via external identity provider, it is possible to trigger a webhook to an external service. This service can register the user and send back their credential ID. If the response contains a valid credential_id, the login proceeds as successful.

To enable the webhook, specify the webhook URL in the configuration file: 

[seacatauth:external_login]
registration_webhook_uri=http://localhost:8089/external-registration

The webhook is a POST request with JSON payload containing the following properties:

  • provider_type - the type of the identity provider (e.g. google or appleid),
  • authorization_response - response query parameters without the authorization code,
  • user_info - OpenID UserInfo-like claims about the logged-in user (mandatory sub, optional email, preferred_username etc.). The actual claims differ from provider to provider and also depend on your client's scope and configuration.

A successful webhook response must contain a valid credential_id of the created credentials. Otherwise, the response is considered error and the login results in failure.

Example

Request: 

POST /webhook_url
{
  "provider_type": "google",
  "authorization_response": {
    "scope": "email profile openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
    "authuser": "0",
    "prompt": "consent"
  },
  "user_info": {
    "iss": "accounts.google.com",
    "sub": "01234567890123456789",
    "email": "abcdefgh@gmail.com",
    "email_verified": true
  }
}

Response: 

{
  "credential_id": "mongodb:custom:abcd123456789"
}

Configuring SeaCat Auth to send emails

SeaCat Auth can send mails respective emails to users, eg. when they forget password and so on. For this, outbound mailing server aka SMTP has to be configured.

Generic SMTP configuration

[seacatauth:communication:email:smtp]
sender_email_address=<user@email.info>
host=<hostname.example.com>
port=<25|if missing, default is guessed>
user=<username>
password=<password>
ssl=<yes|no>
starttls=<yes|no>

SMTP configuration form SendGrid

Based on: https://sendgrid.com/docs/for-developers/sending-email/getting-started-smtp/

[seacatauth:communication:email:smtp]
sender_email_address=<user@email.info>
host=smtp.sendgrid.net
ssl=yes
starttls=no

# Username is always `apikey`
user=apikey

# SendGrid API key from the SendGrid API Keys page.
password=XX.xxxxxxxxxxxxxxxxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Integrating apps

Integrating apps with SeaCat Auth

TeskaLabs SeaCat Auth can be used as a Single Sign-On solution for various applications. Thanks to such integration, you may use your Active Directory, LDAP or social logins (such as Google, GitHub, Microsoft Office, ...) for user authentication.

NGINX

The application gateway for TeskaLabs SeaCat Auth is NGINX. NGINX isolates the public network (Internet) from the internal private network and serves as so-called "interception point" for Authentication. Multiple NGINX instances can be operated at once.

The browser respective web applications and mobile applications uses Access tokens or Cookies for authentication purposes.

NXING intercepts incoming requests from the public network and in cooperation with TeskaLabs SeaCat Auth, it exchanges the Access tokens / Cookies by ID tokens and other configured authentication information. ID Token is added by NGINX to the HTTP header of incoming requests.

ID Token is then used internally by microservices and authentication and authorization resource.

Architecture

Authorization token architecture

Seacat Auth provides cookie-based authorization for older websites and apps that do not support OAuth 2.0. Its PUT /nginx/introspect/cookie endpoint is designed to work with Nginx reverse proxy and its auth_request directive.

Cookie authorization flow

(1) The user wants to access client content, for example Kibana web application, which is protected by cookie introspection. Seacat Auth inspects the request to see if it is authenticated and authorized with a valid client cookie. If it is, the user is served back the client content (7). If it is not, the user is lead through the authorization process (2).

(2) OAuth 2.0 authorize endpoint checks that the user is authenticated. If not, they are taken through the login process (3). If authenticated, they are redirected to the client cookie entrypoint (4).

(3) Seacat Auth leads the user through the login process to establish a single sign-on session and a client (Kibana) subsession.

(4) The user is redirected to the cookie entry point.

(5) Cookie entry point sends the user a client cookie, which serves as the identificator of the new client session.

(6) The user sends an authorized request to access the client site.

(7) The server responds with requested client content.

Connecting OAuth apps

Set up OAuth2 introspection for a web application

First, register your web application in the Client section of SeaCat UI. You will obtain client_id necessary for the introspection request.

Set up a location for your application in the Nginx configuration:

location <APPLICATION_PATH> {
    proxy_pass <INTERNAL_APPLICATION_URL>;

    auth_request        /_oauth2_introspect;
    auth_request_set    $authorization $upstream_http_authorization;
    proxy_set_header    Authorization $authorization;

    error_page 401 /auth/api/openidconnect/authorize?<CLIENT_PARAMETERS>&redirect_uri=$request_uri;
}
  • <APPLICATION_PATH> is the path where your application will be accessible to users.
  • <INTERNAL_APPLICATION_URL> is the internal URL of your application server.
  • <CLIENT_PARAMETERS> is a query string of your registered client parameters, usually including client_id, response_type, scope. Note that more parameters, such as client_secret, may be required depending on the type and configuration of your client. Example path with minimal parameters: /auth/api/openidconnect/authorize?client_id=abc1230ZM3n37BmbtKrqqw&response_type=code&scope=openid&redirect_uri=$request_uri

Connecting other apps

HTTP Cookies 🍪

SeaCat Auth provides cookie-based authentication for applications that do not implement OAuth2. Different configuration is needed for single-domain and for multi-domain settings.

Single-domain setting

If all the applications that you want to protect run on the same domain as your SeaCat Auth service (or its subdomains), you only need to configure the root cookie. This cookie is sent to the user automatically after successfully logging in.

Service configuration

Root cookie is configured in section [seacatauth:cookie]. The available config options are - name: Cookie name, defaults to SeaCatSCI - domain: Cookie domain. It has no default and must be explicitly configured.

NOTE: To fully work in all major browsers, cookie domain must contain at least two dots (requirement by Firefox). For example, localhost or .xyz may not work properly, but .app.localhost or .example.xyz should work fine.

Example

[seacatauth:cookie]
domain=.service.xyz

Such cookie is valid on the service.xyz domain and all of its subdomains and subpaths, such as auth.service.xyz or myapp.test.service.xyz/example.

Cookie introspection is a way of authenticating and authorizing requests to a protected location. Any user request to such a location is checked for whether it has a valid SeaCat Auth cookie in the header. When it does, the request continues to the protected location. When it does not have a valid cookie, a HTTP 401 Not Authorized response is sent back to the user. Or the user can be directly forwarded to an authorization endpoint.

The cookie introspection endpoint is found at path /nginx/introspect/cookie and uses POST requests. Furthermore, it has the capability to add certain information about the user into HTTP X-headers, such as username, roles or tenants. This is done using add= query parameters in the introspection call. See the SeaCat Auth Postman collection for more details about this endpoint.

Introspection endpoint configuration:

location = /_cookie_introspect {
    internal;
    proxy_method          POST;
    proxy_set_body        "$http_authorization";
    proxy_pass            <SEACAT_AUTH_SERVICE_URL>/nginx/introspect/cookie;
    proxy_ignore_headers  Cache-Control Expires Set-Cookie;
}

Example of a cookie-protected location configuration:

location / {
    proxy_pass <PROTECTED_LOCATION_URL>;

    auth_request        /_cookie_introspect;
    auth_request_set    $authorization $upstream_http_authorization;
    proxy_set_header    Authorization $authorization;
}

Multi-domain setting

If some of your applications run on a different domains than SeaCat Auth service, you need to set up an application cookie and a cookie entry endpoint for each of those domains. Unlike the root cookie, these cookies are not handed out automatically after login. To obtain them, it is necessary to make a cookie request call.

❓ TODO: Unauthenticated user flowchart ❓

  • User tries to access a protected location without required application cookie
  • NGINX cookie introspection fails and the user is redirected to OIDC authorize endpoint
  • Authorize endpoint redirects the user to login screen
  • The user logs in
  • The user is redirected to application-cookie request endpoint with an authentication code in the query string
  • The cookie request endpoint exchanges the authentication code for a cookie and redirects the user to a pre-configured URL

Configuration

Each cookie is configured in its own section called [seacatauth:cookie:<APP_DOMAIN_ID>]. The <DOMAIN_ID> is used in cookie request URL for its corresponding domain.

[seacatauth:cookie]
; This is the root cookie, it is required both in single- and multi-domain setting
domain=auth.service.xyz

[seacatauth:cookie:myservice]
domain=my.service.xyz
redirect_uri=http://my.service.xyz/home

[seacatauth:cookie:anotherservice]
domain=service.elsewhere.xyz
redirect_uri=http://service.elsewhere.xyz/discover

redirect_uri specifies where the user is redirected after successful cookie request.

Cookie entry endpoint

GET /cookie/entry/<APP_DOMAIN_ID>

Exchanges authorization code for application cookie. It's necessary to provide grant_type=authorization_code and code=...... query parameters in the request.

E.g.:

GET http://my.service.xyz/auth/cookie/entry/myservice?grant_type=authorization_code&code=4x0fDvBTuSM3dWlp7t2560A4wtCB199dcbLU5pphe8AagCpM

NGINX configuration

Each of the configured domains must have a proxy to the cookie introspection and cookie request endpoints. The introspection endpoint is configured exactly the same as in the single-domain case:

location = /_cookie_introspect {
    internal;
    proxy_method          POST;
    proxy_set_body        "$http_authorization";
    proxy_pass            <SEACAT_AUTH_PUBLIC_API_INTERNAL_URL>/nginx/introspect/cookie;
    proxy_ignore_headers  Cache-Control Expires Set-Cookie;
}
  • <SEACAT_AUTH_PUBLIC_API_INTERNAL_URL> is the internal base URL of your SeaCat Auth public API.

Locations which use cookie introspection should set their error page to OIDC authorize endpoint with scope=openid&response_type=code for automatic login prompt. The redirect URL should point to the cookie request endpoint with grant_type=authorization_code:

server_name <APP_DOMAIN>

...

location /auth/cookie_entry {
    proxy_pass <SEACAT_AUTH_PUBLIC_API_INTERNAL_URL>/cookie/entry/<APP_DOMAIN_ID>;
}
  • <APP_DOMAIN> is your application domain, different from SeaCat Auth domain.
  • <APP_DOMAIN_ID> is the ID of your application domain, as you configured it in SeaCat Auth service configuration.
  • <SEACAT_AUTH_PUBLIC_API_INTERNAL_URL> is the internal base URL of your SeaCat Auth public API.
location / {
    proxy_pass <PROTECTED_LOCATION_URL>;

    auth_request        /_cookie_introspect;
    auth_request_set    $authorization $upstream_http_authorization;
    proxy_set_header    Authorization $authorization;

    error_page 401 403 <SEACAT_AUTH_PUBLIC_API_URL>/openidconnect/authorize?response_type=code&scope=openid&client_id=signin&redirect_uri=<APP_DOMAIN>/auth/cookie_entry?grant_type=authorization_code;
}
  • <PROTECTED_LOCATION_URL> is the internal URL of your protected location.
  • <SEACAT_AUTH_PUBLIC_API_URL> is the public base URL of your SeaCat Auth public API.

Connecting to Elasticsearch and Kibana

This is a guide to configuring SeaCat Auth as a proxy to Kibana users and roles. As Kibana is not OAuth-compatible and supports only Basic Authentication, integrating it into a Single Sign-On environment requires a special approach. The SeaCat Auth Batman component (Basic Auth Token MANager) is designed exactly for this task - it "translates" Seacat session cookies into Basic Auth headers and synchronizes Kibana/Elasticsearch users with Seacat Auth credentials and their access rights.

How does it work?

The flow for using Batman auth is almost the same as the cookie auth flow, the only difference being in the type of introspection used. Instead of the PUT /nginx/introspect/cookie endpoint (which exchanges Seacat client cookie for ID token), Batman auth uses PUT /nginx/introspect/batman (which exchanges Seacat client cookie for Basic auth header).

Configuration example

Let's set up Seacat Batman authorization for our Kibana app. We need to have Elasticsearch and Kibana applications up and running, as well as a working instance of Seacat Auth with Nginx reverse proxy. We will need to configure these three components:

  • Update Seacat Auth configuration with [batman:elk] section to allow it to use Elasticsearch API to synchronize users and manage their authorization.
  • Create and configure a Kibana client. This client object represents and identifies Kibana in communication with Seacat Auth.
  • Prepare the necessary server locations in Nginx config.

Seacat Auth configuration

Create the ELK Batman section and provide Elasticsearch base URL and API credentials, e.g.

[batman:elk]
url=http://localhost:9200
username=admin
password=elasticpassword

Client configuration

Use Seacat Auth client API (or Seacat Admin UI) to register Kibana as a client. The request body must include a human-readable client_name, redirect_uris array containing the URL of Kibana web UI and cookie_entry_uri for your hostname (we define this location in the Nginx configuration below.). We also recommend to set redirect_uri_validation_method to prefix_match if you want to allow immediate redirections to Kibana subpaths. In our case, we can send the following request (Remember to use your actual hostnames instead of example.com!):

POST /client
{
    "client_name": "Kibana",
    "redirect_uri_validation_method": "prefix_match",
    "redirect_uris": [
        "https://example.com/kibana"
    ],
    "cookie_entry_uri": "https://example.com/seacat_auth/cookie"
}

The server will respond with our client's assigned ID and other attributes:

{
    "client_id": "RZhlE-D4yuJxoKitYVL4dg",
    "client_id_issued_at": 1687170414,
    "application_type": "web",
    ...,
    "cookie_name": "SeaCatSCI_QLFLEAU4D726UPA3"
}

We will use the client_id and client_cookie in the next step.

Nginx configuration

The minimal configuration requires the following three locations to be defined in nginx:

  • Client site location: Protected public location with Kibana web app.
  • Client introspection: Internal endpoint used by the nginx auth_request directive.
  • Client cookie entry point: Public endpoint which dispenses the Seacat client cookie at the end of a successful authorization flow.

Client site location

location /kibana/ {
    # Kibana upstream
    proxy_pass http://kibana_api;

    # Auth introspection endpoint
    auth_request /_kibana_introspection;

    # Pass the Batman header obtained from Seacat Auth introspection to Kibana
    auth_request_set $auth_header $upstream_http_authorization;
    proxy_set_header Authorization $auth_header;

    # In the case when introspection detects invalid authorization, redirect to OAuth authorize endpoint
    # !! Use your client's actual client_id and your site's actual hostname !!
    error_page 401 https://example.com/auth/api/openidconnect/authorize?response_type=code&scope=cookie%20batman&client_id=RZhlE-D4yuJxoKitYVL4dg&redirect_uri=https://example.com$request_uri;

    # Headers required by Kibana
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}

Client introspection

location = /_kibana_introspection {
    internal;

    # Seacat Auth Batman introspection upstream
    # !! Use your client's actual client_id !!
    proxy_method          POST;
    proxy_pass            http://seacat_auth_api/nginx/introspect/batman?client_id=RZhlE-D4yuJxoKitYVL4dg;

    proxy_set_header      X-Request-URI "$request_uri";
    proxy_ignore_headers  Cache-Control Expires Set-Cookie;

    # Introspection response caching
    proxy_buffer_size     128k;
    proxy_buffers         4 256k;
    proxy_busy_buffers_size  256k;
    proxy_cache           kibana_auth;
    # !! Fill in your client's actual cookie_name !!
    proxy_cache_key       $cookie_SeaCatSCI_QLFLEAU4D726UPA3;
    proxy_cache_lock      on;
    proxy_cache_valid     200 10s;
}

Cookie entry point

Must be located on the same hostname as the protected client location. There should be one cookie entry point exposed per hostname, shared by all cookie-based clients on that hostname.

location = /seacat_auth/cookie {
    # Seacat Auth cookie entry upstream
    proxy_method          POST;
    proxy_pass            http://seacat_auth_api/cookie/entry;

    # Transfer the OAuth authorization code from query to request body
    # !! Use your client's actual client_id !!
    proxy_set_header      Content-Type "application/x-www-form-urlencoded";
    proxy_set_body        $args;
}

Connecting to TheHive

This is a guide to configuring TheHive to use SeaCat Auth as its Single Sign-on (SSO) OAuth2 provider.

Prerequisites

Configuration

auth {
    providers: [
        {name: session}
        {name: basic, realm: thehive}
        {name: local}
        {name: key}
        {
            name: oauth2
            clientId: "<CLIENT_ID>"
            clientSecret: "<CLIENT_SECRET>"
            redirectUri: "<THEHIVE_URL>/api/ssoLogin"
            responseType: "code"
            grantType: "authorization_code"
            authorizationUrl: "<PUBLIC_SEACAT_AUTH_API_URL>/openidconnect/authorize"
            authorizationHeader: "Bearer"
            tokenUrl: "<INTERNAL_SEACAT_AUTH_API_URL>/openidconnect/token"
            userUrl: "<INTERNAL_SEACAT_AUTH_API_URL>/openidconnect/userinfo"
            scope: ["openid"]
            userIdField: "email"
        }
    ]
}

user.autoCreateOnSso: true
  • <CLIENT_ID> and <CLIENT_SECRET> is the OAuth2 Client credentials issued to you by SeaCat Auth.
  • <THEHIVE_URL> is the public URL where The Hive is available.
  • <PUBLIC_SEACAT_AUTH_API_URL> is the public (accessible from the user browser) URL of SeaCat Auth public container.
  • <INTERNAL_SEACAT_AUTH_API_URL> is the internal (accessible from the Hive instance) URL of SeaCat Auth public container.

Further relevant configuration options can be found in The Hive documentation.

Using Seacat authorization in Grafana

This guide will show you how to set up Grafana so you can use Seacat Auth for logging in and access control. Grafana has native support for OAuth authorization flow, so connecting it to Seacat Auth is quite straightforward.

  1. Register a new client for your Grafana application in the Clients section of Seacat Admin UI. Note down the client ID.
  2. Create the following resource IDs in the Resources section of the Seacat Admin UI (or choose different names, but remember to change them in Grafana role_attribute_path configuration below):
    • grafana:access: Will be mapped to Grafana's Viewer role, which allows the user to browse dashboards and other data, but not to create or change anything.
    • grafana:edit: Will be mapped to Grafana's Editor role, which allows the user to browse and edit dashboards and other data.
  3. Configure Grafana to use your Seacat Auth instance as a Generic OAuth provider. This can be either done in Grafana config file, or perhaps more conveniently using environment variables in your docker-compose.yaml file as following:
services:
  grafana:
    image: grafana/grafana:10.3.1
    network_mode: host
    (...)
    environment:
      ## Required configuration options
      # URL where Grafana is accessible in the browser
      GF_SERVER_ROOT_URL: ${PUBLIC_URL}/grafana/
      # Enable OAuth login
      GF_AUTH_GENERIC_OAUTH_ENABLED: true
      # Client ID issued by Seacat Auth
      GF_AUTH_GENERIC_OAUTH_CLIENT_ID: ${GRAFANA_CLIENT_ID}
      # Client secret issued by Seacat Auth (not supported yet)
      GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: ""
      # OAuth scopes that Grafana will request from Seacat Auth
      GF_AUTH_GENERIC_OAUTH_SCOPES: openid email profile
      # Public URL of Seacat Auth OAuth Authorization endpoint
      GF_AUTH_GENERIC_OAUTH_AUTH_URL: ${PUBLIC_URL}/api/openidconnect/authorize
      # Internal URL of Seacat Auth OAuth Token endpoint
      GF_AUTH_GENERIC_OAUTH_TOKEN_URL: ${INTERNAL_SEACAT_AUTH_URL}/openidconnect/token
      # Internal URL of Seacat Auth OAuth Userinfo endpoint
      GF_AUTH_GENERIC_OAUTH_API_URL: ${INTERNAL_SEACAT_AUTH_URL}/openidconnect/userinfo

      ## Additional useful configuration options
      # Where the user is redirected after pressing the "Sign out" button
      GF_AUTH_SIGNOUT_REDIRECT_URL: ${PUBLIC_URL}
      # Skip Grafana login screen and sign the user in automatically
      GF_AUTH_GENERIC_OAUTH_AUTO_LOGIN: true
      # Disable PKCE
      GF_AUTH_GENERIC_OAUTH_USE_PKCE: false
      # Disable refresh tokens (not supported yet)
      GF_AUTH_GENERIC_OAUTH_USE_REFRESH_TOKEN: false
      # OAuth provider name displayed on the "Sign in with ..." button on the Grafana login screen
      GF_AUTH_GENERIC_OAUTH_NAME: Seacat Auth
      # Get the user login name and screen name primarily from OpenID Connect standard field "preferred_username", with fallback to "username" and "sub" fields
      GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH: preferred_username || username || sub
      GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH: preferred_username || username || sub
      # Control user permissions using Seacat Auth authorized resources:
      #   The following JMESPath expression assigns the user a Grafana role depending on the authorized resources in their ID token or Userinfo
      GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH: >
        contains(resources."*"[*], 'authz:superuser') && 'Admin' 
        || contains(resources."*"[*], 'grafana:edit') && 'Editor' 
        || contains(resources."*"[*], 'grafana:access') && 'Viewer'
      # Deny login if the user is not authorized for any of the resources in the expression above
      GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_STRICT: true
  • PUBLIC_URL is the base URL from which Seacat Auth is accessed from the browser, for example https://example.com.
  • INTERNAL_SEACAT_AUTH_URL is the internal URL of Seacat Auth's private web container, typically http://localhost:8900.
  • GRAFANA_CLIENT_ID is the client ID issued by Seacat Auth.

NOTE: The above configuration assumes that Grafana backend communicates with Seacat Auth server via secure internal network (usually a VPN). If this is not the case and the two services have no shared internal network, configure GF_AUTH_GENERIC_OAUTH_TOKEN_URL and GF_AUTH_GENERIC_OAUTH_API_URL using public URLs.

If this is your testing environment and you are using a self-signed SSL certificate, you will need to add the following switch as well: 

GF_AUTH_GENERIC_OAUTH_TLS_SKIP_VERIFY_INSECURE: true

For more details about Grafana OAuth configuration, refer to its documentation.

Development

REST API

REST API

The ASAB framework that Seacat Auth is built on provides an OpenAPI specs endpoint with Swagger UI (read more in ASAB documentation).

Swagger UI is available at the /doc path.

OpenAPI specs are available at /asab/v1/openapi.

Postman

To explore the Seacat API with Postman, you can download the OpenAPI specs from /asab/v1/openapi as a file and import it into Postman as a new collection.

Using SeaCat Auth with Postman

Postman is a useful development tool for debugging apps that interact with SeaCat Auth. The major advantage is that Postman natively handles OAuth2.0 authentication and provides tools for auth token management.

Prerequisites

  • Running instance of SeaCat Auth
  • Check the [general] section in the config to make sure auth_webui_base_url and public_api_base_url variables point to the actual URLs of your SeaCat Auth WebUI
  • Running instance of SeaCat Auth WebUI
  • Auth WebUI is required for authenticating in SeaCat Auth
  • Check the proxy routing (in Nginx) to make sure it points to you SeaCat Auth backend correctly

Configure your Postman environment

  • Import the OpenAPI specs from /asab/v1/openapi in the SeaCat Auth API.
  • Set up a SeaCat Auth Postman environment. The following variables need to be defined:
  • BASE_URL should contain the base URL of your SeaCat API, for example https://my-domain.int/seacat/api/seacat_auth
  • AUTH_URL should contain the base URL of your SeaCat Auth, for example https://my-domain.int/auth. It is used for authenticating your session.

Create an OAuth2 authorized session

  • In the Collections panel, open the context menu of your SeaCat Auth collection and choose Edit.
  • Navigate to Authorization tab.
  • For Authorization type choose OAuth 2.0
  • Request a new access token and log in to your SeaCat Auth WebUI
  • Your Postman session is now authenticated!

Postman access token details

  • Grant type: "Authorization Code"
  • Callback URL: http://localhost:8080/???? (???)
  • Auth URL: http://localhost:8080/openidconnect/authorize
  • Access Token URL: http://localhost:8080/openidconnect/token
  • Client Id: [any string]
  • Client Secret: [any string]
  • Scope: openid
  • State: [empty string]
  • Client Authentication: Send client credentials in the body

NOTE Some API requests will be fulfilled only if you have access to specific admin resources (authz:superuser or authz:tenant:admin). Check the description of those calls to see if there is any access restriction.

OAuth 2.0 in SeaCat Auth

The specification is available here: https://tools.ietf.org/html/rfc6749

Protocol Endpoints

    1. Protocol Endpoints (authorization service, authorization handler)
  • 3.1. Authorization Endpoint (authorization service, authorization handler)
  • 3.2. Token Endpoint (authorization service, token handler)
  • 3.2.1. Client Authentication (authorization service, authorization handler)

Authorization Code Grant flow

  • 4.1. Authorization Code Grant (authorization service, authorization handler)
  • 4.1.1. Authorization Request (authorization service, authorization handler)
  • 4.1.2. Authorization Response (authorization service, authorization handler)
  • 4.1.2.1. Error Response (authorization service, authorization handler)
  • 4.1.3. Access Token Request (authorization service, token handler)
  • 4.1.4. Access Token Response (authorization service, token handler)

Refreshing an Access Token

    1. Refreshing an Access Token (authorization service, token handler)

OAuth 2.0 Token Revocation

https://tools.ietf.org/html/rfc7009

OpenID Connect in SeaCat Auth

The specification is available here: https://openid.net/specs/openid-connect-core-1_0-23.html

Authentication using the Authorization Code Flow

  • 3.1. Authentication using the Authorization Code Flow (authorization service, authorization handler)
  • 3.1.1. Authorization Code Flow Steps (authorization service, authorization handler)
  • 3.1.2. Authorization Endpoint (authorization service, authorization handler)
  • 3.1.2.1. Authentication Request (authorization service, authorization handler)
  • 3.1.2.2. Authentication Request Validation (authorization service, authorization handler)
  • 3.1.2.3. Authorization Server Authenticates End-User (authorization service, authorization handler)

  • 3.1.2.4. Authorization Server Obtains End-User Consent/Authorization (authorization service, authorization handler)edentials policy url: /config/credentials/policy

    • title: Credentials providers url: /config/credentials/providers
    • title: Provisioning url: /config/provisioning
    • title: External login url: /config/external-login
    • title: Bouncer url: /config/bouncer
    • title: Cookies url: /config/cookies
    • title: LDAP url: /config/ldap
    • title: E-mail server url: /config/mail-server
    • title: Deployment with Docker url: /config/docker

  • title: Reference

  • 3.1.3.3. Successful Token Response (authorization service, token handler)
  • 3.1.3.4. Token Error Response (authorization service, token handler)
  • 3.1.3.5. Token Response Validation (authorization service, token handler)
  • 3.1.3.6. ID Token (authorization service, token handler)

UserInfo Endpoint

  • 5.3. UserInfo Endpoint (credentilasprovider service, credentilasprovider handler)
  • 5.3.1. UserInfo Request (credentilasprovider service, credentilasprovider handler)
  • 5.3.2. Successful UserInfo Response (credentilasprovider service, credentilasprovider handler)
  • 5.3.3. UserInfo Error Response (credentilasprovider service, credentilasprovider handler)

The proper structure with all information (such as validation of user info) must be implemented in the future.

Set OpenID Connect in WebUI

Default path for OpenID connect service is openidconnect. OpenID connect (oidc) can also hold an external OpenID connect URL. In that case, URL is rewritten with URL in oidc parameter. External OpenID connect URL must start with http:// or https://

For configuration details, please refer to TeskaLabs Wiki

JWT token

https://connect2id.com/learn/openid-connect

User guide

Account help

Need help making changes in your account?

You can manage your account in the SeaCat Auth app (UI).

Login

The SeaCat Auth login portal allows you to log in, start over, and retrieve password help.

Logging in

To log in, enter your login credentials: username, phone number, or email, and password.

You can add an OTP authenticator or a hardware key for additional login security.

Login portal Login portal

Resetting your password

If you forgot or lost your password:

  1. On the login screen, click Can't log in?
  2. Enter what you use to log in (username, email address, or phone number).
  3. SeaCat Auth will send you an email with a link to reset your password.

Logging out

You can log out multiple ways. If your connection to the app is timed out, you are logged out automatically.

Logout options:

  • Go to My account, and click Logout.
  • Go to My account > Manage, and click Logout.
  • To log out from all devices, go to My account > Manage, and click Logout from all devices.

Changing your account details

You can change your email or phone number at any time. If you use your email address or phone number for logging in, your login credentials will change accordingly.

Changing your email address

  1. Go to My account > Manage.
  2. Click Manage email address.
  3. Enter your new email address, and click Confirm.

Changing your phone number

  1. Go to My account > Manage.
  2. Click Manage phone number.
  3. Enter your new phone number, and click Confirm.

Resetting your password

You can reset your password at any time.

In your account

  1. Go to My account > Change password, or go to My account > Manage, and click Change the password.
  2. Enter your existing password, new password, and duplicate of the new password.
  3. Click Set password.

Changing a forgotten password:

If you forgot or lost your password:

  1. On the login screen, click Can't log in?
  2. Enter what you use to log in (username, email address, or phone number).
  3. SeaCat Auth will send you an email with a link to reset your password.

Adding an OTP (one-time PIN) authenticator

If you want an extra layer of security (multi-factor authentication), you can add a one-time PIN generator, such as an authenticator app, to your account. When you have an authenticator app active, you'll need to enter a one-time PIN and your password every time you log in (unless you also have a hardware key active, in which case you can choose upon logging in).

Adding an OTP authenticator

  1. Choose an OTP authenticator app.
  2. Go to My account > Manage.
  3. Click Manage One-Time PIN (OTP).
  4. Scan the QR code with your authenticator app.
  5. Enter the code that your authenticator app provides, and click OK to confirm.
  6. Click Activate OTP.
  7. As long as you have an OTP authenticator active, you need your password and a one-time PIN to log in.

Removing an OTP authenticator

  1. Go to My account > Manage.
  2. Click Manage One-Time PIN (OTP).
  3. Click Deactivate OTP, and click OK to confirm.
  4. Now, you no longer need an OTP to log in.

Setting up a hardware key

You can set up a hardware key as an authenticator for logging in. If you have a hardware key set up, you can use it to log in instead of your password.

Registering a hardware key authenticator

  1. Go to My account > Manage.
  2. Click Manage FIDO2/WebAuthn.
  3. Click Register new authenticator.

Register new authenticator Register new authenticator 4. Follow the instructions in your browser to confirm the registration of your new hardware key authenticator.
5. Now, you can use your hardware key to log in.

Renaming an authenticator

  1. Go to My account > Manage.
  2. Click Manage FIDO2/WebAuthn.
  3. Click the pencil edit beside the authenticator you want to rename.

Edit authenticator Edit authenticator 4. Rename the authenticator, and click Save.

Unregistering an authenticator

  1. Go to My account > Manage.
  2. Click Manage FIDO2/WebAuthn.
  3. Beside the authenticator you want to unregister, click Unregister authenticator.
  4. To confirm, click Ok. The hardware key is removed from your account.

Reference

Architecture of SeaCat Auth

  • Authentication Service
  • Authorization Service
  • API Service
  • Tenant Service
  • Credentials Service
  • Session Service
  • Notification Service
  • Audit Service
  • OpenIDConnect Service
  • Provisioning Service
  • Batman Service
  • Bouncer Service

Components of SeaCat Auth

This section clarifies the roles of various components in the SeaCat Auth ecosystem.

Web User Interfaces

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 other common-user-facing screens.

Docker and Docker Compose

The whole site installation can be dockerized and deployed using docker-compose, see the quick start quide.

Nginx

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.

MongoDB

Is employed by SeaCat Auth for storage of known users and other related persistent data.

Resources

Resource-based Access Control (RBAC)

rbac-diagram

Credentials

  • A set of credentials typically corresponds to a user account, but they can be also machine-to-machine credentials.

Tenant

  • Tenant is "a group of users who share a common access with specific privileges to a software instance".
  • It can be a company, a department, a team etc.
  • By definition, a tenant can have multiple users (sets of credentials).
  • A user can join several tenants.

Role

  • Role is a named set of resources, it is used to grant user access to those resources.
  • A user can have multiple roles.
  • A role can be assigned to multiple users.
  • Tenant roles are valid only for one specific tenant.
  • Global roles are valid across all tenants.

Resource

  • Resource is an identifier of an actual software resource or an action performed on that resource.
  • Having access to a resource means having rights to what it represents (blog:post:create, my-repository:write, my-app:access etc.)
  • Any resource can be assigned to several roles.
  • A role can have multiple resources.
  • Resources cannot be assigned directly to credentials; credentials can have access to a resource only through a role.

SeaCat Auth admin resources

authz:superuser

authz:tenant:access

authz:impersonate

Clients

A Client is an entity that uses authentication and authorization services provided by the Authorization Server. This authorization enables the Client to access protected resources. In a common scenario, the Client is a browser application and the Resource Owner is a backend application located on a remote server.

Before a Client can ask for authorization, it must get registered at the Authorization Server and obtain a unique ID. The registration can either be done in Admin UI or via the Admin API.

Client metadata

The actual list of client metadata supported by Seacat Auth can be obtained at GET /client/features API.

Canonical OAuth 2.0 and OpenID Connect metadata

Defined in OpenID Connect Dynamic Client Registration 1.0 and OAuth 2.0 Dynamic Client Registration Protocol.

client_id

NOT EDITABLE Unique ID of the Client. By default, it is an opaque string generated by the Authorization Server. It is possible to request a custom ID by supplying the non-canonical preferred_client_id parameter in the client registration request. The ID is not editable once the client is already registered.

client_name

REQUIRED Human-palatable name of the Client to be presented to the End-User.

client_secret

OAuth 2.0 client secret string. This value is used by confidential clients to authenticate to the token endpoint. It is generated by the Authorization Server and is not directly editable.

client_uri

URL of the home page of the Client.

redirect_uris

REQUIRED Array of Redirection URI values used by the Client.

application_type

Kind of the application. The default, if omitted, is web.

Supported options: web

response_types

JSON array containing a list of the OAuth 2.0 response_type values that the Client is declaring that it will restrict itself to using. If omitted, the default is that the Client will use only the code Response Type.

Supported options: code

grant_types

JSON array containing a list of the OAuth 2.0 Grant Types that the Client is declaring that it will restrict itself to using. If omitted, the default is that the Client will use only the authorization_code Grant Type.

Supported options: authorization_code

token_endpoint_auth_method

Requested Client Authentication method for the Token Endpoint. If omitted, the default is none.

Supported options: none

code_challenge_method

Code Challenge Method (used in Proof Key for Code Exchange (PKCE)) that the Client will restrict itself to use at the Authorize Endpoint. The default, if omitted, is none.

Supported options:

  • none: PKCE is disabled.
  • plain: Code challenge is the same as the code verifier.
  • S256: Code challenge is derived from the code verifier by using SHA-256 hashing algorithm.

Non-canonical metadata

These are Seacat-Auth-specific features.

preferred_client_id

REGISTRATION ONLY Requests a specific client_id instead of a randomly generated one at client registration.

redirect_uri_validation_method

Specifies the method how the redirect URI used in authorization requests is validated. The default and recommended value is full_match.

Supported options:

  • full_match: The only OAuth2.0 compliant option. Requested Redirect URI must exactly match one of the registered Redirect URIs.
  • prefix_match: Requested Redirect URI must start with one of the registered Redirect URIs and their hostname must exactly match.
  • none: There is no Redirect URI validation. Not secure.

NOT EDITABLE Unique cookie name derived from Client ID by the Authorization Server. Cookie with this name holds the information

Webhook URI for setting additional custom cookies at the cookie entrypoint. It must be a back-channel URI and must accept a JSON PUT request and respond with a JSON object of cookies to set.

cookie_entry_uri

Public URI of the client's cookie entrypoint. This field is required for cookie-based authorization (including batman authorization). One such entrypoint should be available on every hostname where there are Clients that use cookie-based authorization.

Domain of the client cookie. If not specified, the application's default cookie domain is used.

authorize_uri

URL of OAuth authorize endpoint. Useful when logging in from different than the default domain.

login_uri

URL of preferred login page. Useful when logging in from different than the default domain.

authorize_anonymous_users

Boolean value specifying whether to authorize requests with anonymous users.

anonymous_cid

ID of credentials that is used for authenticating anonymous sessions.

session_expiration

Client session expiration. The value can be either the number of seconds or a time-unit string such as 4 h or 3 d.

Session

  • Session object represents user or machine authentication and authorization.
  • The two basic session types are root and client. Client sessions can be either access-token-based or cookie-based. Furthermore, there are special session types: machine-to-machine and anonymous session.

Single Sign-On session (aka "root session")

  • Created at user login.
  • Used as a proof of user authentication (Single Sign-On) for OAuth authorization requests.
  • Uniquely identified by a browser cookie (called SeaCatSCI by default).

Client session (subsession)

  • Used as a proof of user and client authorization.
  • Created as a result of a successful OAuth authorization request at /openidconnect/authorize endpoint.
  • Descends from a root session; user root session is a prerequisite to creating a client session for that user.
  • Uniquely identified either by OAuth 2.0 tokens or by HTTP cookie.

Access-token-based client session

  • Created by authorization request at /openidconnect/authorize with openid in scope.
  • Suitable for clients that support the OAuth 2.0 protocol.
  • Uniquely identified by OAuth 2.0 Access Token.
  • Created by authorization request at /openidconnect/authorize with cookie in scope.
  • Suitable for clients that do not support the OAuth 2.0 protocol.
  • Uniquely identified by browser cookie.

Machine-to-machine (M2M) session

  • Special type of root session that includes client authentication and authorization.
  • Serves as a proof of authentication and authorization in machine-to-machine communication (no human user is involved).

Anonymous session

  • Special type of session that identifies an unauthenticated user.
  • Used for tracking visitors at client locations that can be accessed without authentication.
  • It is a client session that can exists without a root session. Anonymous root session is created only when multiple anonymous client sessions need to be linked together.

Session lifecycle

  • When an end-user successfully signs in, a Single Sign-On (root) session is created. It contains a user identifier and details of the user authentication process: when the authentication happened, what means of authentication were used etc. It is usually long-lived (several days to months). The user agent receives an HTTP cookie which identifies this SSO session.
  • When the user wants to access a client application, the application asks the Seacat Auth server for authorization to access the end-user data and other resources, which is usually done using the OAuth 2.0 authorization code flow. The first step of the flow is the authorization request, which, if successful, produces a short-lived (not longer than a few minutes) client session and an authorization code which serves as the session identifier. The session contains a reference to the end user's Single Sign-On session and details of the authorization, such as the client application identifier (client ID) and the requested authorization scope.
  • The client application then uses the authorization code to make a token request. If successful, this consumes the authorization code and produces a set of longer-lived tokens - an access token and an ID token, which are valid for a few hours, and a refresh token, which is valid for several days to weeks. The client session is extended to last as long as the refresh token and updated so that it contains up-to-date user info and their authorized tenant and resources.
  • The client application then continuously uses the access token as a proof of authorization to resource-owner applications. For example, a frontend Web UI application (client) sends the access token with every REST API request to the backend application (resource owner). The resource owner can ask the authorization server to verify the access token in a so-called introspection request.
  • When the access token expires, the client application can request a new one using the refresh token. This request results in a new set of tokens (access, refresh and ID) being issued and the client session being once again extended to match the new refresh token.
  • When the client session expires or when the client requests to terminate it, the session is deleted together with all its active tokens.
  • When the Single Sign-On session expires or when the end-user signs out, the session is invalidated and deleted together with its cookie, with all the client sessions that have been opened under this Single Sign-On session and their tokens.