pomerium/docs/docs/topics/programmatic-access.md

title	description
Programmatic access	This article describes how to configure pomerium to be used to enable machine-to-machine programmatic access.

Programmatic access

This page describes how to obtain Pomerium access credentials programmatically via a web-based oauth2 based authorization flow. If you have ever used Google's gcloud commandline app, the mechanism is very similar.

Components

Login API

The API returns a signed, sign-in url that can be used to complete a user-driven login process with Pomerium and your identity provider. The Login API endpoints takes a redirect_uri query param as an argument which points to the location of the callback server to be called following a successful login.

For example:

$ curl "https://httpbin.example.com/.pomerium/api/v1/login?redirect_uri=http://localhost:8000"

https://authenticate.example.com/.pomerium/sign_in?redirect_uri=http%3A%2F%2Flocalhost%3Fpomerium_callback_uri%3Dhttps%253A%252F%252Fhttpbin.corp.example%252F.pomerium%252Fapi%252Fv1%252Flogin%253Fredirect_uri%253Dhttp%253A%252F%252Flocalhost&sig=hsLuzJctmgsN4kbMeQL16fe_FahjDBEcX0_kPYfg8bs%3D&ts=1573262981

Callback handler

It is the script or application's responsibility to create a HTTP callback handler. Authenticated sessions are returned in the form of a callback from pomerium to a HTTP server. This is the redirect_uri value used to build Login API's URL, and represents the URL of a (usually local) http server responsible for receiving the resulting user session in the form of pomerium_jwt and pomerium_refresh_token query parameters.

See the python script below for example of how to start a callback server, and store the session payload.

Handling expiration and revocation

Your application should handle token expiration. If the session expires before work is done, the identity provider issued refresh_token can be used to create a new valid session.

Also, your script or application should anticipate the possibility that a granted refresh_token may stop working. For example, a refresh token might stop working if the underlying user changes passwords, revokes access, or if the administrator removes rotates or deletes the OAuth Client ID.

High level workflow

The application interacting with Pomerium must manage the following workflow. Consider the following example where a script or program desires delegated, programmatic access to the domain httpbin.corp.domain.example:

1. The script or application requests a new login url from the pomerium managed endpoint (e.g. https://httpbin.corp.domain.example/.pomerium/api/v1/login) and takes a redirect_uri as an argument.
2. The script or application opens a browser or redirects the user to the returned login page.
3. The user completes the identity providers login flow.
4. The identity provider makes a callback to pomerium's authenticate service (e.g. authenticate.corp.domain.example) .
5. Pomerium's authenticate service creates a user session and redirect token, then redirects back to the managed endpoint (e.g. httpbin.corp.domain.example)
6. Pomerium's proxy service and makes a callback request to the original redirect_uri with the user session and refresh token as arguments.
7. The script or application is responsible for handling that http callback request, and securely handling the callback session (pomerium_jwt) and refresh token (pomerium_refresh_token) queryparams.
8. The script or application can now make any requests as normal, by setting the Authorization: Pomerium ${pomerium_jwt} header.

Example Code

Please consider see the following minimal but complete python example.

python3 scripts/programmatic_access.py \
	--dst https://httpbin.example.com/headers

<<< @/scripts/programmatic_access.py