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 authentication, if the request is forwarded, 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

Examples

Path-based AC

If your app's path schema naturally distinguishes public and private parts by their path prefixes, then this may be a suitable approach. You just have to define the default access and the paths that should be private/public.

Consider an app named myapp which has the path section in the app.json configured like this:

"paths": {
  "": {
    "access": "private",
    "headers": {
      "X-Ptl-Client-Id": "{{ auth.client_id }}",
      "X-Ptl-Client-Name": "{{ auth.client_name }}",
      "X-Ptl-Client-Type": "{{ auth.client_type }}"
    }
  },
  "/public/": {
    "access": "public"
  }
}

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:<br>X-Ptl-Client-Type=terminal<br>X-Ptl-Client-Name=My Notebook<br>X-Ptl-Client-Id=eie767w];
  pre -->|/public| forward[forward to app container];
  head_auth --> forward

App-specific AC

If your AC needs are more complex, you might want to implement the required logic yourself.

By choosing app-specific AC, you instruct the Portal to let all incoming requests reach your app but still populate the http headers with IDs and names of clients. This allows you to know for each request from which kind of client it originated and if applicable from which specific terminal or peer. Based on that information, you can make arbitrarily complex access control decisions.

Consider an app named myapp which has the path section in the app.json configured like this:

"paths": {
  "": {
    "access": "public",
    "headers": {
      "X-Ptl-Client-Id": "{{ auth.client_id }}",
      "X-Ptl-Client-Name": "{{ auth.client_name }}",
      "X-Ptl-Client-Type": "{{ auth.client_type }}"
    }
  }
}

This would lead to the access control behavior visualized below.

graph TD
  Request --> sub{subdomain?};
  sub -->|myapp| auth{authentication?};
  sub -->|anything else| away[route another way];
  auth -->|fail| head_no_auth[apply headers:<br>X-Ptl-Client-Type=public<br>X-Ptl-Client-Name=<br>X-Ptl-Client-Id=];
  head_no_auth --> forward[forward to app container];
  auth -->|success| head_auth[apply headers:<br>X-Ptl-Client-Type=terminal<br>X-Ptl-Client-Name=My Notebook<br>X-Ptl-Client-Id=eie767w];
  head_auth --> forward;