Open ID Connect Bearer Token

Endpoints can require an Open ID Connect Bearer Token authentication method. This validates a caller's JWT access token against an identity provider before the endpoint runs.

Use this when a host application (for example AireFrame) already has a user access token and needs to:

• Secure an AireGlu endpoint with that token
• Make the validated token available inside the endpoint execution pipeline
• Optionally, check the user holds specific permissions before the endpoint runs (see Permission Gating)

This authentication type is named Open ID Connect Bearer Token in the endpoint editor. It is separate from Client Credentials, which is for server to server application tokens obtained with a client ID and secret, not end user access tokens from a host application.

This is also separate from the JWT Task, which generates tokens inside an endpoint. Open ID Connect Bearer Token authentication validates inbound tokens from callers.

Configuring an endpoint

In the endpoint editor, open Authentication and add Open ID Connect Bearer Token.

Field	Required	Description
Authority	Yes	Issuer base URL for the identity provider (for example the AireIdentity authority at https://identity.aireinnovate.com). You must enter this value; it is not pre-filled. AireGlu loads signing keys from {authority}/.well-known/openid-configuration.
Audiences	Yes	Comma separated list of allowed aud claim values. The token must match any one value in the list.
Scopes	No	Comma separated list of scopes the token must include. When set, the token must contain all listed scopes. When left empty, no scope claim is required.

Authority, audiences, and scopes support variables using the same mapping syntax as other authentication fields.

To also require the user to hold specific permissions, tick Fetch and validate permissions for Target Scope(s) under Permission gating. Permissions can come from AireIdentity or from an AireGlu endpoint you build. See Permission Gating.

If multiple authentication methods are configured on an endpoint, all of them must pass.

How callers pass a token

AireGlu resolves the token in this order:

1. Authorization: Bearer <token> (preferred)
2. Form POST body, only when the request has a form content type (application/x-www-form-urlencoded or multipart/form-data). AireGlu reads the first non empty value from a field named jwt, or token if jwt is not present (case insensitive field names).

Query string tokens are not accepted. Passing ?jwt=... on the URL will not authenticate the request.

Bearer header (API and server to server calls)

POST https://glu-api.example.com/my-tenant/my-endpoint
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{ "example": "payload" }

Use this for direct API calls, background services, and follow up requests from page JavaScript after the initial load.

Form body (iframe handoff)

Browsers cannot set custom headers on an iframe's initial navigation. Host applications such as AireFrame can instead POST the access token in the form body so it does not appear in the URL, server access logs, or Referer headers.

<form id="aireglu-handoff" method="POST" action="https://glu-api.example.com/my-tenant/my-endpoint" target="aireglu-frame">
  <input type="hidden" name="jwt" value="ACCESS_TOKEN_HERE" />
</form>
<iframe name="aireglu-frame"></iframe>
<script>document.getElementById("aireglu-handoff").submit();</script>

The host page must submit the form to load the iframe. Setting src on the iframe directly will not send the token in the form body.

The field name may be jwt or token. Both are treated the same.

If both an Authorization header and a form field are present, the header is used. If the header value is invalid, AireGlu does not fall back to the form field.

AireFrame widgets that embed AireGlu endpoints should POST the user's access token in a jwt or token form field rather than putting it on the query string. This keeps long lived credentials out of URL based logging.

Token validation

After a token is resolved, AireGlu validates it against the configured identity provider:

1. Fetches Open ID Connect metadata from {authority}/.well-known/openid-configuration (cached per authority).
2. Resolves signing keys from the metadata document or JWKS endpoint.
3. Validates signature, issuer (must match the configured Authority), expiry, and audience.
4. When Scopes are configured on the endpoint, verifies the token's scope claim contains every required scope (case sensitive). Scope values may appear as multiple claims or as a single space separated string.
5. Applies tenant matching for AireIdentity tokens (see below).
6. When permission gating is enabled, looks up the user's permissions for each Target Scope and checks every required permission is held.

If validation fails, the endpoint returns 401 Unauthorized.

Identity providers

AireIdentity

When Authority is set to AireIdentity (for example https://identity.aireinnovate.com), AireGlu validates the token and checks that it was issued for the same tenant as the endpoint. You must enter the issuer URL yourself; it is not pre-filled.

Example audience values for AireIdentity tokens often look like api://my-application or another resource identifier registered with the identity provider.

Third party identity providers

When Authority points to an external provider (for example https://login.microsoftonline.com/{tenant}/v2.0), AireGlu validates issuer, signature, lifetime, audience, and optional scopes against that provider's metadata. Tenant matching is skipped. You must enter the correct issuer URL yourself; it is not pre-filled. The endpoint configuration defines which issuer and audiences are trusted.

Use this when an endpoint must accept tokens from a customer's own identity provider rather than AireIdentity.

Using the token inside an endpoint

After successful authentication, the validated access token is available in the execution pipeline as request.userToken.

In Liquid templates:

Authorization: Bearer {{ request.userToken }}

The token is not automatically added to outbound requests. Reference it explicitly where needed.

Calling downstream APIs as the user

To call another API on behalf of the same user, avoid forwarding the token. Instead, first create a Delegate Exchange connection. Use the connection as the auth for your HTTP request task, setting the connection’s subject_token parameter on the task to {{ request.userToken }}.

When the task runs, AireGlu will use the connection to swap the caller’s token for one issued for your downstream API. It will then use this token to call the downstream API. This means the token will be scoped to only what it needs, but will still identify the user.

Forward request.userToken unchanged only when the receiver expects exactly the same token, for example another AireGlu endpoint with the same Open ID Connect Bearer Token configuration.

See Delegate Exchange: why use it for the trade-offs.

If the endpoint uses permission gating, its Target Scope names are also available as authentication.targetScopes. See Using target scopes in Liquid.

request.userToken contains the full access token. Avoid logging it in usage data, audit output, or HTTP responses unless required.

Comparison with other authentication methods

Method	Typical use	Token / credential
Open ID Connect Bearer Token	User context calls from host apps and iframes	JWT access token from an identity provider
Client Credentials	Server to server, no user session	Application access token from AireIdentity
API Key	Simple shared secret	Static key in X-Api-Key header

Troubleshooting

Symptom	Things to check
401 with form POST	Request content type must be form encoded or multipart. JSON bodies with a jwt property are not read for authentication.
401 with ?jwt= on URL	Query parameters are intentionally ignored. Use Bearer header or form POST.
401, AireIdentity	Confirm Authority is set to your AireIdentity issuer URL (for example https://identity.aireinnovate.com). Check token aud matches one configured audience, the token tenant matches the endpoint tenant, and required scopes are present.
401, third party provider	Confirm the Authority URL matches the external provider's issuer (this is not pre-filled). Check the audience list and that the provider's signing keys are reachable from AireGlu runtime.
403, 500, 502 or 503 with permission gating on	See Permission Gating troubleshooting.
Token works in header but not iframe	Ensure the host submits a form POST (not an iframe src URL) before or when loading the iframe; verify the field name is jwt or token.