Tigrosa 2.0.5

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_dev;

CREATE DATABASE tgr_dev OWNER tgr_dev;

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 via password

tgr-login-pwd

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.

Realm: public

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)

This route calls upstream / GET, merges the response body, and sets the response status to be that of the upstream. Thus, Response Parameters might be extended by the upstream response body, and Response 200 in fact depends on the upstream.

Although t_now shows only the time of the last deep healthcheck, it is expected that this time is recent. If the time reported is vastly different to your own clock, this could be an indication that there are time-synchronisation issues. Such will likely prevent proper authentication.

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.

Realm: admin

Request Parameters

Parameter	Type	Description
`locked`	boolean?	locked, blocking access

Response Parameters

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

This route calls upstream /org/:org_id PUT. This is to allow the upstream to maintain referential integrity, storing the Href if desired. The body itself is not proxied.

/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.

Realm: private

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.

Realm: private

Response Parameters

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

This route calls upstream /org/:org_id GET. This is to allow the upstream to extend the Response Parameters.

/org/:org_id PATCH

Request

Response 200

Update an Org.

Realm: admin

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.

Realm: admin

This route calls upstream /org/:org_id DELETE. This is to allow the upstream to maintain referential integrity.

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.

Realm: private

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.

Realm: private

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.

Realm: private

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.

Realm: admin

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.

Realm: private

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.

Realm: private

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.

Realm: admin

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.

Realm: admin

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.

Realm: private

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.

Realm: private

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.

Realm: private

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.

Realm: private

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.

Realm: private

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.

Realm: private

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.

Realm: private

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.

Realm: private

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.

Realm: private

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:

Authentication via UsrPwd: This is the standard authentication method for most users. To create a UsrSesn, no signed body is required.
Authentication via UsrKey: This provides a stronger authentication method for some users. To create a UsrSesn, a body containing the current time, signed with a RSA private key, is required.

Realm: private

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.

Realm: private

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.

Realm: private

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)