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 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:
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.
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 404
s 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) |