NAV
http

Tigrosa 2.0.12

Tigrosa is an authentication proxy, originally written for Isoxya web crawler. Tigrosa is like a guard-spider, protecting a backend REST API using JSON, and abstracting away the notions of users and organisations from the upstream. This decreases the logic necessary in the upstream API, decreasing time-til-market and increasing security. The design is somewhat opinionated and the functionality fairly minimal, but what is there is well-tested and performance-optimised.

Installation

PostgreSQL

create user and database

CREATE USER tgr;

CREATE DATABASE tgr OWNER tgr;

PostgreSQL 13 is required as the main datastore. Other recent versions may also work.

For high-availability, a number of options are possible, such as active-passive with automatic failover, or multi-master where available. Depending on the strategy used, a minimum or either 2 or 3 nodes is recommended.

Redis

Redis 6 is required as a cache. Other recent versions will also likely work.

For high-availability, an active-passive setup with automatic failover is possible. Depending on the strategy used, a minimum or either 2 or 3 nodes is recommended.

Containers

Podman, Docker, Docker Swarm, Kubernetes, or an alternative are recommended for running the main programs. Alternatively, it is possible to run binaries with few dependencies instead, but these are not currently supplied separately, meaning it would be necessary to extract the binaries from the container images.

For high-availability, it is possible to either let the container orchestrator handle this, or alternatively set up multiple instances behind an HTTP load-balancer. Depending on the strategy used, a minimum or either 2 or 3 nodes is recommended.

Configuration

tgr-pe-api

tgr-pe-api is the Tigrosa Pro Edition API, handling authentication and authorisation. It is typically installed on the Containers servers.

Environment Variables

Variable Default Description
LICENSE_FILE license.yml licence file
POSTGRESQL_URL postgres://postgres:postgres@pg:5432 PostgreSQL URL
REDIS_URL redis://rds:6379 Redis URL
UPSTREAM_URL http://test_upstream upstream URL

Initialisation

Use the Tigrosa x Bin Scripts to complete setup, either directly or by using the scripts as reference.

Endpoint

tgr-init

Configure the endpoint, pointing to the API (potentially through a load-balancer terminating SSL).

RSA keypair

tgr-init-key

Generate an RSA keypair, used for admin control.

Database

tgr-init-db

Generate SQL queries to initialise the database, running them on the PostgreSQL servers.

Usage

Log in via key

tgr-login-key

Log in using a UsrKey, generating a UsrSesn. The token can be used for subsequent requests.

Log in via password

tgr-login-pwd

Log in using a UsrPwd, generating a UsrSesn. The token can be used for subsequent requests.

Create an organisation

tgr-create-org

Create an Org, proxied to the upstream.

Read resources

tgr-read

Read an Org or other resources.

References

Tigrosa x Bin Scripts

Tigrosa x Bin Scripts is an open-source (BSD 3-Clause) collection of scripts for Tigrosa authentication proxy. With these, it's possible to create organisations and users, login and create session tokens, and perform other operations using the Tigrosa API. These are useful not only in development, but also as a demo of Tigrosa's main capabilities, a quick way of performing actions even in production, and also in providing a functional reference for those wishing to develop their own programs on top of Tigrosa.

Apex

/ GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "tigrosa": {
    "t_now": "2021-02-23T18:27:35.959822683Z",
    "version": "0.0.0"
  }
}

Read the apex, returning metadata about the API and its status. This route is suitable for use as a healthcheck, indicating whether the API is available and healthy. Calling the route usually operates as a shallow healthcheck; periodically, however, a deep healthcheck is performed, the time of which is exposed as t_now.

Response Parameters

Parameter Type Description
tigrosa.t_now string time of last deep healthcheck
tigrosa.version string version of API
(might be extended by upstream)

Org

Organisation: The business, organisation, or human entity registered with the system, and responsible for paying any bills. Does not log in directly.

/org POST

Request

POST /org HTTP/1.1
content-type: application/json
{}

Response 201

HTTP/1.1 201 Created
location: /org/1151e7b8-e651-4136-a0fa-2cae7e67335b
content-type: application/json
{
  "href": "/org/1151e7b8-e651-4136-a0fa-2cae7e67335b",
  "locked": false
}

Create an Org.

Request Parameters

Parameter Type Description
locked boolean? locked, blocking access

Response Parameters

Response Parameters are as for /org/:org_id GET.

/org GET

Response 200

HTTP/1.1 200 OK
link: </org>; rel="first", </org?_next=2021-02-23T18:27:36.332805Z>; rel="next", </org?_prev=2021-02-23T18:27:36.337639Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/org/876c15eb-97cd-4665-84e5-3f050d4e6955",
    "locked": false
  },
  {
    "href": "/org/f13ef838-73af-430f-b498-e3936648bf32",
    "locked": false
  }
]

List Orgs.

Response Parameters

Response Parameters are as for /org/:org_id GET.

/org/:org_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/org/65da783e-88c8-47eb-94d7-16ea26e6644d",
  "locked": false
}

Read an Org.

Response Parameters

Parameter Type Description
href string Href
locked boolean locked, blocking access
(might be extended by upstream)

/org/:org_id PATCH

Request

Response 200

Update an Org.

Request Parameters

Request Parameters are as for /org POST.

Response Parameters

Response Parameters are as for /org/:org_id GET.

/org/:org_id DELETE

Response 204

HTTP/1.1 204 No Content
content-type: text/plain; charset=utf-8

Delete an Org.

OrgUsr

Organisation-User: An association between an Org and a Usr. Many-to-many associations are supported; e.g. a human could use their login to access two business accounts, each of which might also allow access to a number of other humans and robots.

/org/:org_id/usr/:usr_id PUT

Request

PUT /org/c40573a2-7dc9-4e57-b1d3-5a84077026b0/usr/c20bb6d2-55f8-435a-b213-7441a942b9ed HTTP/1.1
content-type: application/json
{}

Response 201

HTTP/1.1 201 Created
location: /org/c40573a2-7dc9-4e57-b1d3-5a84077026b0/usr/c20bb6d2-55f8-435a-b213-7441a942b9ed
content-type: application/json
{
  "href": "/org/c40573a2-7dc9-4e57-b1d3-5a84077026b0/usr/c20bb6d2-55f8-435a-b213-7441a942b9ed",
  "level": "member",
  "org": {
    "href": "/org/c40573a2-7dc9-4e57-b1d3-5a84077026b0",
    "locked": false
  },
  "usr": {
    "href": "/usr/c20bb6d2-55f8-435a-b213-7441a942b9ed",
    "locked": false,
    "realm": "private"
  }
}

Create an association between an Org and a Usr.

Request Parameters

There are no Request Parameters.

Response Parameters

Response Parameters are as for /org/:org_id/usr/:usr_id GET.

/org/:org_id/usr/:usr_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/org/a45538a3-5e11-48ec-be94-082c23376191/usr/c634dc33-700d-43df-a243-987fbac522eb",
  "level": "member",
  "org": {
    "href": "/org/a45538a3-5e11-48ec-be94-082c23376191",
    "locked": false
  },
  "usr": {
    "href": "/usr/c634dc33-700d-43df-a243-987fbac522eb",
    "locked": false,
    "realm": "private"
  }
}

Read an association between an Org and a Usr.

Response Parameters

Parameter Type Description
href string Href
level string resource membership level, for X-Tigrosa-Resource
org object Org
usr object Usr

/org/:org_id/usr/:usr_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete an association between an Org and a Usr.

Usr

User: The human or robotic entity logging into and interacting with the system, responsible mostly for keeping their password safe. Does not control any data directly.

/usr POST

Request

POST /usr HTTP/1.1
content-type: application/json
{}

Response 201

HTTP/1.1 201 Created
location: /usr/c3635848-6d4c-4aca-a9e3-8e40247e623c
content-type: application/json
{
  "href": "/usr/c3635848-6d4c-4aca-a9e3-8e40247e623c",
  "locked": false,
  "realm": "private"
}

Create a Usr.

Request Parameters

Parameter Type Description
locked boolean? locked, blocking access

Response Parameters

Response Parameters are as for /usr/:usr_id GET.

/usr GET

Response 200

HTTP/1.1 200 OK
link: </usr>; rel="first", </usr?_next=2021-02-23T18:27:54.311341Z>; rel="next", </usr?_prev=2021-02-23T18:27:54.317247Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/usr/06b172e7-aa28-40a8-9231-93da752d29df",
    "locked": false,
    "realm": "private"
  },
  {
    "href": "/usr/1d244392-533b-4162-a6ce-e312165f8815",
    "locked": false,
    "realm": "private"
  }
]

List Usrs.

Response Parameters

Response Parameters are as for /usr/:usr_id GET.

/usr/:usr_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/usr/e5b6cd90-7c76-4f2a-9b0e-1e92c6885ff5",
  "locked": false,
  "realm": "private"
}

Read a Usr.

Response Parameters

Parameter Type Description
href string Href
locked boolean locked, blocking access
realm string global access realm, for X-Tigrosa-Realm

/usr/:usr_id PATCH

Request

Response 200

Update a Usr.

Request Parameters

Request Parameters are as for /usr POST.

Response Parameters

Response Parameters are as for /usr/:usr_id GET.

/usr/:usr_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete a Usr.

UsrKey

User-Key: An RSA keypair, belonging to a Usr. Used in particular for admin or robotic access.

/usr/:usr_id/usr_key POST

Request

POST /usr/4feb2ec6-cbe2-440e-8e2f-2c5836fecc58/usr_key HTTP/1.1
content-type: application/json
{
  "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApz0lQbAD30Wp7GiJo6b4\nYczFJpxP/Bdhye8ExTpOU/MltXoaWuyUQodnAzgyEO8Ahsvh2oyLJ7mGK36x18LN\nEQ1+oXqzV1sOokyzJTxCt/xF2+cJU1uA7Glx4CFrH9tRKALjgSQKP1cd9Ch86enn\nTW/82KD3UF89uNPiO4NTOVbOazHTLFm5nPbtPbqrd0sqIb6+mSW86w11Oa+e5QyB\nQvXuM/Aj8uSKATz3CYIb3nVN2oF+CfLdOo17eAJkVj2YFy3HZDST+Qmdhd63gChL\npaYcrJa4L248gB6vEJIE9Hqy7yA1MGA7wQCQToevBq2KwFoiy+2q7LIbLtJ98b8c\nMwIDAQAB\n-----END PUBLIC KEY-----\n"
}

Response 201

HTTP/1.1 201 Created
location: /usr_key/94dd6a0e-5164-4d02-850f-98a7fe94d07b
content-type: application/json
{
  "href": "/usr_key/94dd6a0e-5164-4d02-850f-98a7fe94d07b",
  "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApz0lQbAD30Wp7GiJo6b4\nYczFJpxP/Bdhye8ExTpOU/MltXoaWuyUQodnAzgyEO8Ahsvh2oyLJ7mGK36x18LN\nEQ1+oXqzV1sOokyzJTxCt/xF2+cJU1uA7Glx4CFrH9tRKALjgSQKP1cd9Ch86enn\nTW/82KD3UF89uNPiO4NTOVbOazHTLFm5nPbtPbqrd0sqIb6+mSW86w11Oa+e5QyB\nQvXuM/Aj8uSKATz3CYIb3nVN2oF+CfLdOo17eAJkVj2YFy3HZDST+Qmdhd63gChL\npaYcrJa4L248gB6vEJIE9Hqy7yA1MGA7wQCQToevBq2KwFoiy+2q7LIbLtJ98b8c\nMwIDAQAB\n-----END PUBLIC KEY-----\n",
  "usr": {
    "href": "/usr/4feb2ec6-cbe2-440e-8e2f-2c5836fecc58",
    "locked": false,
    "realm": "private"
  }
}

Generating a key using OpenSSL

openssl genrsa -out pri.pem 2048
openssl rsa -in pri.pem -outform PEM -pubout -out pub.pem

Create a UsrKey.

Request Parameters

Parameter Type Description
rsa_key_pub string RSA public key (PEM)

Response Parameters

Response Parameters are as for /usr_key/:usr_key_id GET.

/usr/:usr_id/usr_key GET

Response 200

HTTP/1.1 200 OK
link: </usr/e183cee9-3182-4028-a172-f5899bd958c7/usr_key>; rel="first", </usr/e183cee9-3182-4028-a172-f5899bd958c7/usr_key?_next=2021-02-23T18:27:43.388364Z>; rel="next", </usr/e183cee9-3182-4028-a172-f5899bd958c7/usr_key?_prev=2021-02-23T18:27:43.394695Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/usr_key/10564db6-63a4-4add-8410-12662c37cdce",
    "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8MKxN6eHJwdLYwT0KwvD\nN20kY9Ahw5esmC0ZwYJ1aLnxVvgG2xSqWCrGyV75sMVzdpFvyl9EizpFuV2MWDwu\n/MfG0O++EI20VohofhSEbJOvpRAK3Dwmt0a8FfmHO+aoqoLem8NJk67dGAKyqqa1\ns+PBqs6hI20CFtUsPFOMgv7pa3+uGXhdSHpKzY7wxp6esLO9J1hwgHEIm9zwEEaM\n7yhmwIb/hjVmuTY3HP5vV0F56JdAIMX7zFm75nJGx88/Qfm/2FIGGjdoZHgQOhS0\nchBS7kMmVm+FqT4KcCEltSCgevfFEn+iaRXkew9KauTHEkdf5PW7uonwL4QD0GYl\nbQIDAQAB\n-----END PUBLIC KEY-----\n",
    "usr": {
      "href": "/usr/e183cee9-3182-4028-a172-f5899bd958c7",
      "locked": false,
      "realm": "private"
    }
  },
  {
    "href": "/usr_key/f3674b8e-e61b-475d-ae56-03edde3b1e9f",
    "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2LcpQRqWSL31zOl0b2rV\nvvLJumRYX4dilSUUF/kHKPIYa3FYfuZ9VGSelZrlng0bj8mBkn+XFhzjAjnO4wGa\nz7NrzMixxfMZumdCYiI7MlXpKG8wH/EgDCnJsG8YAl0Y/rhxMhwQwUXPHJbkkat0\nBjGGKOtPNHJrFhRD9o3rMdP8O2eVza2OGRf7yr5I41tWrxrjBDsn7jn7zFpjwBk1\n0lUaQZHZiT3OTiej73WHW9dHSVsew1PTWuPISynwIzbTCcl+JM0/Kqp+PU0MKzpD\nZAJukDWf+TUh/Fd2lkd7D4csMDlgDhKQnoGe1m2J14lJU6v1wSFOdumg20t36DHn\nvwIDAQAB\n-----END PUBLIC KEY-----\n",
    "usr": {
      "href": "/usr/e183cee9-3182-4028-a172-f5899bd958c7",
      "locked": false,
      "realm": "private"
    }
  }
]

List UsrKeys.

Response Parameters

Response Parameters are as for /usr_key/:usr_key_id GET.

/usr_key/:usr_key_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/usr_key/cedbc2d8-2d8d-4aab-a7e3-a5eab60d9b75",
  "rsa_key_pub": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAkXWI1f72IgjlQf/SfUqI\nL/9GIUgbr2OHiHCW2wmll00Mw03nLS6t0MtN2e6/uLGiVYNELLtAigWFF4N8pdbE\nz2K7DFbmFNEaTROnM3xTV6apKV1zeNHTCJX+QLnx0crsVwSd72EdNLwilCPe89if\nRIB8f+a+JcX5lO2HTmUDlsR6I3Bbwz/kNHGv/5KJfagn8XLIhJUi86106WZbjvVL\n71qseXoceuFDjhpqsbsG7ojK3JypT4xc6qgqKUrJwJh1af1oX76YHu39HeR22K9Q\ntn51LHdRj5z6Lj0GdbAnqcfwc9HZf7J9t/mlWr/DDX0SxbumtcFcapJRLbzz58GW\nqQIDAQAB\n-----END PUBLIC KEY-----\n",
  "usr": {
    "href": "/usr/c8986b51-e93a-4acd-8838-f89b3f207fe8",
    "locked": false,
    "realm": "private"
  }
}

Read a UsrKey.

Response Parameters

Parameter Type Description
href string Href
rsa_key_pub string RSA public key (PEM)
usr object Usr

/usr_key/:usr_key_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete a UsrKey.

UsrPwd

User-Password: A traditional password, belonging to a Usr. Used in particular for logging in via UIs.

/usr/:usr_id/usr_pwd POST

Request

POST /usr/d329c621-03ab-4483-995f-99c4aef1c587/usr_pwd HTTP/1.1
content-type: application/json
{}

Response 201

HTTP/1.1 201 Created
location: /usr_pwd/44b549fd-ac97-40be-9fff-559a51b086db
content-type: application/json
{
  "href": "/usr_pwd/44b549fd-ac97-40be-9fff-559a51b086db",
  "pass": "lE/pa+JhZaOEIjOnq6/EizUs",
  "usr": {
    "href": "/usr/d329c621-03ab-4483-995f-99c4aef1c587",
    "locked": false,
    "realm": "private"
  }
}

Create a UsrPwd.

Request Parameters

There are no Request Parameters.

Response Parameters

Response Parameters are as for /usr_pwd/:usr_pwd_id GET, with the following additions:

Parameter Type Description
pass string generated password

/usr/:usr_id/usr_pwd GET

Response 200

HTTP/1.1 200 OK
link: </usr/8e70cec0-ce06-4501-ae19-918410e8d84a/usr_pwd>; rel="first", </usr/8e70cec0-ce06-4501-ae19-918410e8d84a/usr_pwd?_next=2021-02-23T18:27:47.73271Z>; rel="next", </usr/8e70cec0-ce06-4501-ae19-918410e8d84a/usr_pwd?_prev=2021-02-23T18:27:47.746758Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/usr_pwd/c4c8a281-3877-465d-adc7-ac3fa7b47560",
    "usr": {
      "href": "/usr/8e70cec0-ce06-4501-ae19-918410e8d84a",
      "locked": false,
      "realm": "private"
    }
  },
  {
    "href": "/usr_pwd/ad676743-217b-46ee-af6b-cea284c568e6",
    "usr": {
      "href": "/usr/8e70cec0-ce06-4501-ae19-918410e8d84a",
      "locked": false,
      "realm": "private"
    }
  }
]

List UsrPwds.

Response Parameters

Response Parameters are as for /usr_pwd/:usr_pwd_id GET.

/usr_pwd/:usr_pwd_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/usr_pwd/94eae6b4-416b-4198-88e1-77b5b06d205a",
  "usr": {
    "href": "/usr/439d803e-e286-4b24-a503-55d48af30aec",
    "locked": false,
    "realm": "private"
  }
}

Read a UsrPwd.

Response Parameters

Parameter Type Description
href string Href
usr object Usr

/usr_pwd/:usr_pwd_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete a UsrPwd.

UsrSes

User-Session: An authenticated session, belonging to a Usr. This is generated from a UsrKey or a UsrPwd.

/usr/:usr_id/usr_ses GET

Response 200

HTTP/1.1 200 OK
link: </usr/826b1ee4-c1a4-48fd-829b-afac9c4c2193/usr_ses>; rel="first", </usr/826b1ee4-c1a4-48fd-829b-afac9c4c2193/usr_ses?_next=2021-02-23T18:27:50.071279Z>; rel="next", </usr/826b1ee4-c1a4-48fd-829b-afac9c4c2193/usr_ses?_prev=2021-02-23T18:27:50.085659Z>; rel="prev"
content-type: application/json
[
  {
    "href": "/usr_ses/1c6a804c-cda3-4a78-a8a2-d088baf6da6d",
    "t_exp": "2021-02-23T18:27:55.085659Z",
    "usr": {
      "href": "/usr/826b1ee4-c1a4-48fd-829b-afac9c4c2193",
      "locked": false,
      "realm": "private"
    }
  },
  {
    "href": "/usr_ses/0224174a-7cb4-4a82-8da6-28afd42b24ee",
    "t_exp": "2021-02-23T18:27:55.071279Z",
    "usr": {
      "href": "/usr/826b1ee4-c1a4-48fd-829b-afac9c4c2193",
      "locked": false,
      "realm": "private"
    }
  }
]

List UsrSesns.

Response Parameters

Response Parameters are as for /usr_ses/:usr_ses_id GET.

/usr_ses POST

UsrPwd approach: Request

POST /usr_ses HTTP/1.1
content-type: application/json
{
  "ttl": 60
}

UsrPwd approach: Response 201

HTTP/1.1 201 Created
location: /usr_ses/36169fbb-aa05-48ae-a35c-faee026872a5
content-type: application/json
{
  "href": "/usr_ses/36169fbb-aa05-48ae-a35c-faee026872a5",
  "t_exp": "2021-02-23T18:28:52.253908Z",
  "token": "ku0UAhDVnfJsA5503u4w9JEHjGKk5xjylJoimIZJJrIk",
  "usr": {
    "href": "/usr/b8d76aee-1e32-46e8-9e00-a89db2f8ee3b",
    "locked": false,
    "realm": "private"
  }
}

UsrKey approach: Request

POST /usr_ses HTTP/1.1
content-type: application/json
{
  "t_ins": "2021-02-23T18:27:50.459969631Z",
  "ttl": 60
}

UsrKey approach: Response 201

HTTP/1.1 201 Created
location: /usr_ses/6e4d2e11-3ff6-442e-9802-e58892ccf57a
content-type: application/json
{
  "href": "/usr_ses/6e4d2e11-3ff6-442e-9802-e58892ccf57a",
  "t_exp": "2021-02-23T18:28:50.481753Z",
  "token": "qIp0B54sv0549efw/ismDFFJh5QIYMJg/zUEicrrFdJx",
  "usr": {
    "href": "/usr/de7dfac5-b767-4c69-936b-731589c7abe2",
    "locked": false,
    "realm": "private"
  }
}

Create a UsrSesn. Note that this does not live under a different route namespace, since it exceptionally detects and verifies the Usr based on UsrKeys or UsrPwds.

There are two approaches:

Request Parameters

Parameter Type Description
t_ins string current time
ttl number TTL (s); min: 60 (1 m); max: 86400 (1 d)

Response Parameters

Response Parameters are as for /usr_ses/:usr_ses_id GET, with the following additions:

Parameter Type Description
token string token with which to perform other authenticated requests

UsrPwd approach: Logging in using a password

export ENDPOINT_URL=http://localhost:8000
export USR_HREF=/usr/62cdf0b3-e75d-41c2-be15-0c1d4aab28fd

export DIR=".tigrosa"

export ttl=60
export pass="xHsPGNpU0AbtNiSDUXyRO3og"

# generate create session payload
j=$(cat <<-EOT
    {
      "ttl": $ttl
    }
    EOT
    )
echo "$j" | jq

# POST payload to create session
t=$(
    curl -f -u "$USR_HREF:$pass" -X POST -d "$j" "$ENDPOINT_URL/usr_ses"
)
echo "$t" | jq

UsrKey approach: Signing a body using an RSA key

export ENDPOINT_URL=http://localhost:8000
export USR_KEY_HREF=/usr_key/2d5c7fc1-a9dd-4b94-a01a-909f083b1ccb

export DIR=".tigrosa"
export KEY_PRI_PEM="$DIR/pri.pem"
export SES_JSON="$DIR/ses.json"
export SES_JSON_SIG="$DIR/ses.json.sha256.sig.base64"

export ttl=60

# generate create session payload; beware of clock-drift
cat > "$SES_JSON" <<-EOT
    {
      "t_ins": "$(date -Iseconds)",
      "ttl": "$ttl"
    }
    EOT
jq < "$SES_JSON"

# use RSA key to sign a SHA-256 hash of the payload
tr -d '\n' < "$SES_JSON" |
    openssl dgst -sha256 -sign "$KEY_PRI_PEM" |
    base64 -w0 \
    > "$SES_JSON_SIG"

# POST payload to create session
t=$(
    curl -f -u "$USR_KEY_HREF:$(cat "$SES_JSON_SIG")" \
        -X POST -d"@$SES_JSON" "$ENDPOINT_URL/usr_ses"
)
echo "$t" | jq

/usr_ses/:usr_ses_id GET

Response 200

HTTP/1.1 200 OK
content-type: application/json
{
  "href": "/usr_ses/56f30d8c-e106-4a37-ab75-ae402436cd72",
  "t_exp": "2021-02-23T18:27:57.876738Z",
  "usr": {
    "href": "/usr/a55985de-e033-49a3-b669-3155d4a22480",
    "locked": false,
    "realm": "private"
  }
}

Read a UsrSesn.

Response Parameters

Parameter Type Description
href string Href
t_exp string time of token expiry
usr object Usr

/usr_ses/:usr_ses_id DELETE

Response 204

HTTP/1.1 204 No Content

Delete a UsrSesn.

Proxy

Proxy: Since Tigrosa is an authentication proxy, unknown routes are proxied to the upstream, which decides what to respond or whether the route even exists. The full set of routes supported by an API using Tigrosa is the set of Tigrosa routes plus the upstream routes. The priority is Tigrosa then upstream; i.e. it is not possible to override a Tigrosa route within the upstream.

/* * (PROXY)

Upstream Proxy Request

GET /_xxx HTTP/1.1
Host: test_echo
Content-Length: 0
Accept-Encoding: gzip
X-Tigrosa-Realm: private
X-Tigrosa-Resource: </org/05cd79de-9f14-4c12-bb4d-0c336892b042>; rel="member", </org/c39b0399-cc1d-4074-be67-81e696451e0d>; rel="member"

There are usually no Response 404s returned directly by Tigrosa; rather, if a route or method is not matched, it is proxied to the upstream backend, which determines the response and any errors. This is an exceptional collection of routes, giving Tigrosa the flexibility to interface with significantly different upstream programs written in any programming language. As such, Tigrosa is a proxy with specific extra functionality layered in front.

If a route matches something listed for Tigrosa, usually the upstream backend receives no notification of the request. There are some exceptions to this, which are noted under the routes concerned. Similarly, if authentication or authorisation fails for some reason, no request is made to the upstream server. By doing so, Tigrosa can vigorously defend against a variety of attacks, as well as vastly simplifying the authentication and authorisation logic in the upstream backend.

The upstream body need not be JSON (although it usually is); it could be HTML, XML, or simply your favourite picture of a spider. In this regard, Tigrosa acts very similarly to a standard proxy. However, Tigrosa reserves some headers, transmitting them as part of the request; the upstream backend may trust these without verification, and act upon them accordingly. By design, Tigrosa also doesn’t transmit certain information about the original request, including the source IP; in this GDPR-friendly era, this is to discourage upstream applications from attempting to store PII separately to any analysis used for ingress.

Realm

The X-Tigrosa-Realm details the global access realm of your User.

Value Description
public unauthenticated
private authenticated; X-Tigrosa-Resource might contain further context
admin authenticated admin
x-maint system maintenance; used for proxying for upstream referential integrity
(might be extended)

Resource

The X-Tigrosa-Resource details the resource membership level of your User. This is supplied in the same format as a Link header; thus, the same libraries may be used to parse the information. As well as giving the resource HREF, the rel attribute is used to give further information about the access level for that resource.

Value Description
member member of the specified resource
admin admin of the specified resource
(might be extended)