Quickstart: the API
This continues the Quickstart. You have ianua running and the hello test app is started. Everything the dashboard does goes through this same API, so anything you can click you can also script.
1. Sign in
Section titled “1. Sign in”Sign in to the API and keep the session token:
API=https://api.ianua.localhost/api/v1TOKEN=$(curl -sk -X POST $API/login \ -H 'Content-Type: application/json' \ -d '{"email":"you@example.com","password":"Violet otters juggle 42 brass lanterns at dusk"}' | jq -r .refresh_token)T=$API/organizations/acme/tenants/mainauth=(-sk -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json')T is your tenant: organization acme, tenant main. Every call below goes to it.
A sign-in from a device ianua has not seen, by someone with no second factor, waits for a confirmation by email: the answer has "email_confirmation_required": true, and the token works only once you confirm. Send the token from the mailed link with the waiting sign-in’s token:
curl -sk -X POST $API/login/confirm \ -H 'Content-Type: application/json' \ -d "{\"token\":\"<token from the link>\",\"refresh_token\":\"$TOKEN\"}"If your address has an account in more than one organization, the answer has "status": "choose_organization" and a list of them instead of a token. Sign in again with "organization": "acme" added to the body.
2. Create a pipeline
Section titled “2. Create a pipeline”Create a pipeline and switch it on. A new pipeline always contains the two checks that can never be removed: who is calling and are they allowed.
PIPELINE=$(curl "${auth[@]}" -X POST $T/pipelines -d '{"name":"Default"}' | jq -r .id)curl "${auth[@]}" -X POST $T/pipelines/$PIPELINE/activate3. Add a service
Section titled “3. Add a service”Tell ianua where the app lives:
SERVICE=$(curl "${auth[@]}" -X POST $T/services -d '{ "name": "hello", "upstream": { "url": "http://hello:80", "timeout_secs": 30, "preserve_host": false, "expected_audience": {"pinned": "hello"}, "identity": "token" }}' | jq -r .id)expected_audience says which tokens the service accepts: {"pinned": "hello"} takes only tokens made for hello, and "no_token_accepted" takes none. Any route that is not public refuses to save on a service with no pinned audience. identity is "token", or "client_certificate" for a service only callers with a client certificate may reach.
4. Add two routes
Section titled “4. Add two routes”Everything under /public/ is open to anyone. Everything under /private/ needs a signed-in caller.
curl "${auth[@]}" -X POST $T/routes -d "{ \"name\": \"public\", \"path_pattern\": \"/public/*\", \"methods\": [\"Get\"], \"service_id\": \"$SERVICE\", \"pipeline_id\": \"$PIPELINE\", \"policy\": \"Public\"}"
curl "${auth[@]}" -X POST $T/routes -d "{ \"name\": \"private\", \"path_pattern\": \"/private/*\", \"methods\": [\"Get\"], \"service_id\": \"$SERVICE\", \"pipeline_id\": \"$PIPELINE\", \"policy\": \"Authenticated\"}"Each call answers with the new route’s id.
5. See it work
Section titled “5. See it work”Your tenant’s apps are served at acme-main.apps.localhost: the organization, a dash, the tenant, then your apps domain. The gateway picks up each change within a moment, so there is nothing to restart.
A public request goes through. This one also tries to claim to be someone else, by setting identity headers itself:
curl -sk https://acme-main.apps.localhost/public/hello \ -H "X-Forwarded-User: admin" \ -H "X-Ianua-Assertion: forged"The app answers with what it received:
Host: hello:80User-Agent: curl/8.7.1Accept: */*X-Forwarded-For: …X-Forwarded-Host: acme-main.apps.localhostX-Forwarded-Proto: httpsThe request arrived, but neither of the headers you sent is there. The gateway removes identity headers a caller sets, because only the gateway may say who a caller is.
A private request without a login is refused:
curl -sk https://acme-main.apps.localhost/private/hello{"correlation_id":"…","error":"denied: missing bearer token"}The status is 401, and the app never saw the request.
A path no route covers is refused too:
curl -sk -o /dev/null -w "%{http_code}\n" https://acme-main.apps.localhost/adminThat prints 404. Nothing reaches an app unless a route says it may.
Every one of these decisions, allowed or refused, is recorded. The gateway writes one line per request, with the decision and the reason for it:
docker compose logs zero | grep path=/private/helloWARN … request denied … method=GET path=/private/hello … decision="denied" deny_status=401 deny_reason=denied: missing bearer tokenThe same records feed the traffic figures on your tenant’s overview in the dashboard.
And the gateway will not be pointed at the wrong place. Try to make the cloud metadata service, where cloud servers keep their credentials, the address of a service:
curl "${auth[@]}" -X POST $T/services -d '{ "name": "sneaky", "upstream": { "url": "http://169.254.169.254/", "timeout_secs": 30, "preserve_host": false, "expected_audience": "no_token_accepted", "identity": "token" }}'It is refused with status 422, whatever networks you allow:
{"error":"domain_error","message":"Upstreams may not target an internal address outside the networks this deployment allows."}Clean up
docker rm -f hellodocker compose down # stop, keeping your datadocker compose down -v # stop and delete all dataWhat’s next
- How it works explains what happened to each of those requests, stage by stage.
- Install on Kubernetes sets ianua up for real use with two Helm commands: one for ianua, one for the dashboard.
- To let people sign in to a private route, connect your app to ianua over OpenID Connect. The OAuth page under Domain contexts explains how an app is registered and signs people in.