Skip to main content

Pomerium Enterprise API

The Pomerium Enterprise Console supports programmatic interaction through a gRPC API. This page covers enabling and authenticating to the API.

Before you begin

This doc assumes:

Configure a new route

  1. We suggest configuring the route for API access in the open-source Pomerium Core. That way, changes made through the API that might break access to the Enterprise Console won't break access to the API route.

    - from: https://console-api.localhost.pomerium.io
    to: https://pomerium-console-domain-name:8702
    pass_identity_headers: true
    allow_any_authenticated_user: true
    tls_custom_ca_file: /path/to/rootCA.pem
    info

    See TLS Custom Certificate Authority for more information about the tls_custom_ca_file setting.

  2. In your Enterprise Console configuration file, update the audience key to include the new route's from value:

    audience: 'console.localhost.pomerium.io,console-api.localhost.pomerium.io'

    If you're running Pomerium Enterprise as a system service, restart the daemon.

Create a Service Account

  1. In the Enterprise Console under Configure > Service Accounts, select + Add Service Account. You can choose an existing user for the service account to impersonate, or create a new user. Note that a new user will not be synced to your IdP.

  2. The Enterprise Console will display the service account token. Be sure to store it securely now, as you cannot view it again after this point.

  3. Grant the service account the appropriate role on the Namespace(s) it will operate against.

tip

Service Accounts created in any Namespace other than Global will include a reference to that Namespace ID. A service account created in a non-global Namespace will generate a User ID that follows this format:

{user-id}@{namespace-id}.pomerium

You must specify the entire User ID when using the service account. For example:

design-api@bff1bea6-a3d6-232d-812c-b4fd8e26d72e.pomerium

Install the library

pip3 install git+https://git@github.com/pomerium/enterprise-client-python
info

Go to the gRPC API Reference to see all the endpoints available for both the Python and Go libraries.

Test the API connection

The repositories for our Python and Go implementations include example scripts:

#!/usr/bin/env python

import os
from pomerium.client import Client
from pomerium.pb.policy_pb2 import ListPoliciesRequest
from pomerium.pb.namespaces_pb2 import ListNamespacesRequest
from pomerium.pb.routes_pb2 import SetRouteRequest, Route

# get custom CA and service account credentials from environment
ca_cert = os.getenv('CA_CERT', '').encode('utf-8')
sa = os.getenv('SERVICE_ACCOUNT', '')
console_api = 'console-api.localhost.pomerium.io'

client = Client(console_api, sa, root_certificates=ca_cert)

# get id for namespace 'Production'
resp = client.NamespaceService.ListNamespaces(ListNamespacesRequest())
ns = [n for n in resp.namespaces if n.name == 'Production'][0]

# find policy named 'my policy' in namespace 'Production'
resp = client.PolicyService.ListPolicies(
ListPoliciesRequest(query='my policy', namespace=ns.id)
)
policy = resp.policies[0]

# set route in namespace 'Production', associated to 'my policy'
route = Route(**{
'namespace_id': ns.id,
'name': 'my route',
'from': 'https://test.localhost.pomerium.io',
'to': ['https://verify.pomerium.com'],
'policy_ids': [policy.id],
'pass_identity_headers': True,
})

resp = client.RouteService.SetRoute(SetRouteRequest(route=route))
print(resp)

Modify the example script to match your console API path, Namespace(s) and Policy names.

Pomerium Enterprise

See the following pages to learn more about how to use Pomerium Enterprise: