Routing and Access Control
Incoming requests for your app are routed and authenticated by the Portal software
according to your configuration in app.json
.
Routing
Each Portal has a unique URL containing its random six-digit identifier, e.g. xyz123.p.getportal.org
.
Each app is reachable at a subdomain of that URL, e.g. myapp.xyz123.p.getportal.org
.
Requests to this subdomain are forwarded to the running docker container of that app.
SSL
As an app developer, you do not need to concern yourself with SSL and certificates. Your app's interface only needs to be reachable via HTTP at some arbitrary port. Portal manages its own certificate that is valid for all of its subdomains which means it covers all of its installed apps as well.
Access Control
Portal not only authenticates itself against incoming requests.
It also authenticates the sources of those requests if configured to do so.
By using the paths
section in the app.json
, you can choose
which path prefixes should have which type of access
and what should be the default access type.
Path prefixes are evaluated against the path of the incoming request from longest to shortest.
The first matching prefix is chosen and its access is applied to the request.
You must include the empty string ""
as the default option that is evaluated last.
There are two types of access that you can use:
- public means no access control; anyone can access this path.
- private means that only paired terminals may access this path; these belong to the Portal's owner.
After successful authentication, Portal adds headers to the request that you defined for that path. You can use them inside your app for more fine-grained access control or other logic.
When defining the headers, you can use template variables contained in Jinja-like double curly braces. Available variables are:
variable | description | example |
---|---|---|
auth.client_type |
The type of client that sent the request | terminal or public |
auth.client_id |
The cryptographic ID of the connected Terminal | eie767w |
auth.client_name |
The user-assigned name of the connected Terminal | my notebook |
In addition, you can use all variables that describe the Portal itself.
variable | description | example |
---|---|---|
portal.domain |
The fully qualified domain name of the Portal | 8271dd.p.getportal.org |
portal.id |
The full-length hash-ID of the Portal | 8271ddlqxa5fcp7a5l0s61pbqqtglba31d65jg2fqhdwdw2kkr7l94b2q54hfdl2zfn5s5g1nkjy1z1a3f02tl8yln14050l8s598f2 |
Example
Consider an app named myapp with has the path
section in the app.json
configured like this:
JSON | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
This would lead to the access control behavior visualized below.
graph TD
Request --> sub{subdomain?};
sub -->|myapp| pre{prefix?};
sub -->|anything else| away[route another way];
pre -->|<default>| auth{authentication?};
auth -->|fail| deny[deny access];
auth -->|success| head_auth[apply headers];
pre -->|/public| head_pub[apply headers];
head_pub --> forward[forward to app container];
head_auth --> forward