Heplon

Create an HTTP access profile

An HTTP access profile holds one OAuth 2.0 client credential. Heplon uses it to get an access token and sends that token to a proxy in front of Loki or Prometheus. One profile can serve several connectors, so a stack behind a single gateway needs one credential, not one per system.

Use a profile when the endpoint sits behind a gateway that validates JWT bearer tokens, such as OAuth2 Proxy in front of Keycloak. For a fixed token, use the bearer-token option in the connector form instead.

1. Create the client in Keycloak

In the realm your gateway trusts:

  1. Create a client. Set Client authentication to on, which makes it a confidential client.
  2. Turn off Standard flow and turn on Service accounts roles. The service account is the machine identity Heplon acts as.
  3. Copy the client ID and, from the Credentials tab, the client secret.

Keep the default client authenticator, Client Id and Secret. Heplon authenticates with HTTP Basic (client_secret_basic).

2. Find the issuer URL

The issuer is the realm URL:

https://id.example.com/realms/acme

Heplon reads /.well-known/openid-configuration below that URL to find the token endpoint, so there is no endpoint to enter. The issuer must use HTTPS, and the metadata it returns must name the same issuer.

3. Configure the gateway to accept the token

Heplon sends Authorization: Bearer <access token> to the connector URL. The gateway must accept that token instead of starting a browser login. For OAuth2 Proxy:

  • Turn on bearer-token validation (--skip-jwt-bearer-tokens=true) so a request that carries a valid JWT is served without a redirect.
  • List the issuer as an accepted one (--extra-jwt-issuers=<issuer>=<audience>).

The token's aud claim must be an audience the gateway accepts. Keycloak sets aud through an Audience protocol mapper on the client or on a client scope. Add that mapper if the gateway rejects the token.

4. Save the profile in Heplon

Open Connectors, select Access profiles, then Add access profile.

FieldValue
Namean arbitrary name, unique in your tenant
Issuer URLthe realm URL from step 2
Client IDthe client ID from step 1
Client secretthe client secret from step 1
Scopesoptional, space separated

Leave Scopes empty to let the realm apply the client's default scopes. Fill it in only when your realm requires a specific scope.

The profile is now selectable in the Loki and Prometheus connector forms.

Rotate the client secret

  1. Generate a new secret in Keycloak.
  2. Open the profile in Access profiles, enter the new secret, and save.

Heplon replaces the cached token when a profile changes, so the next read uses the new secret. Every other field can be edited without touching the secret: a blank secret field keeps the stored one.

Troubleshoot with the connector health check

The health check of a connector that uses a profile runs the whole path: discovery, token exchange, then a read against the protected endpoint. The failure names the hop that failed.

Health resultWhere to look
Issuer discovery failedThe issuer URL, its TLS certificate, and whether the realm is reachable.
Token acquisition failedThe client ID and secret, and that the service account is enabled.
Protected resource rejected the tokenThe gateway: bearer-token validation, the accepted issuer, and the aud claim.
Upstream unreachableThe connector URL and the network path to it.
HealthyNothing. Both the token exchange and the protected read succeeded.

Heplon never logs or displays the client secret or the access token.

Delete a profile

Heplon refuses to delete a profile that a connector still uses. Point those connectors at another profile, or at a different authentication mode, and then delete it.