Skip to main content
An external attribute source is an HTTPS endpoint you host. When a policy condition reads one of its attributes, Runlayer sends the endpoint a signed request that describes the tool call, and uses the reply as condition values. Runlayer keeps the decision. Your endpoint returns facts, such as an agent’s kind or a ticket’s status, and your policies decide what those facts allow.

When to use one

Policies can already match on the user, their groups, the agent, the connector, the tool, and the tool’s arguments. Add an external attribute source when a condition needs a fact that only your systems hold:
  • Classify agents without one account per kind. Return kind: "migration" for an agent your platform registered as a migration agent, and write one policy per kind.
  • Tie access to a ticket. Return whether the change ticket for a session is approved, and require approval when it isn’t.
  • Reuse a risk or data classification. Return the repositories a user may not touch, and deny tool calls whose repo argument is on the list.
To allow or deny on content, use a custom scanner instead. A scanner returns a verdict. A source returns attributes.

Add a source

  1. Go to Settings → Policies, click External attributes, then click Add source.
  2. Enter:
    • Key: the name policies use, as in meta.external.<key>.<attribute>. Lowercase letters, digits, and underscores. It can’t be changed later.
    • Name: how the source appears in settings and in the condition builder.
    • Endpoint URL: the https URL Runlayer posts to, exactly as entered.
    • Send with each request: which facts about the call your endpoint receives. Subject and Acting agent are on by default. See Request.
    • Tool arguments (optional): up to 8 argument paths, such as repo or issue.project. Runlayer sends the value of each one. It never sends the whole tool input.
    • Attributes: the attributes your endpoint returns. Each has a name, a type (Text, True/false, or List of text), and an optional description. A source has 1 to 32 attributes.
    • Timeout (ms): 200 to 2000. The default is 500.
    • Cache answers for (seconds): 0 to 300. The default is 30, and 0 turns caching off.
    • Custom headers (optional): static headers sent on every request, for example an API key for your gateway. They are stored encrypted and never shown again.
  3. Copy the signing secret. Runlayer shows it once. Your endpoint uses it to verify requests.
  4. Open the source’s menu and click Test connection. Runlayer sends a test request with the fields the source selects: your own identity as the subject, and placeholder values for the client, session, connector, and tool. Listed arguments are sent as null. It shows the status code, the latency, and whether each attribute came back, never the values.
A workspace can have up to 10 sources.

Use an attribute in a policy

In the condition builder, attributes appear under External for conditions on connector tool calls. In the API, the field is meta.external.<key>.<attribute>.
Put the attribute in field, not in value: External attributes are read only when a tool is called. When a client lists tools, a tool whose access depends on an external attribute is listed, and the call decides. Only the sources a call needs are contacted. A tool call whose policies read no external attribute sends no request.

When a source fails

If a source times out, returns an error, or returns a reply Runlayer can’t use, every condition that depends on it fails closed: There is no setting that lets a call through when a lookup fails. A failure applies only to conditions that depend on the source. If another condition in the same group is already false, the group stays false. Two cases are not failures, so they don’t fail closed:
  • A null attribute. A 200 reply with null for an attribute is an answer. The condition reads it as a missing field: equals and the other positive operators don’t match, and the negated operators (not_* and list_not_*) do. See Negated operators and null.
  • A cached answer. While a reply is cached, Runlayer doesn’t contact the source, so an outage or a changed answer goes unseen until the cache time ends. See Caching.

Negated operators and null

An allow policy with meta.external.agents.kind not_equals migration grants access when your endpoint returns null for kind. A deny policy with the same condition denies.
To keep an allow policy from granting on null:
  • Use a positive operator. Write meta.external.tickets.approved equals false instead of not_equals true.
  • For a text attribute, add a regex .+ condition on the same attribute, which matches only when a value is present.
  • Return a value such as "unknown" instead of null, or leave the attribute out of the reply so that it counts as a failure.
Each failure is written to the audit log as an external attribute lookup failure, with the source, the cause, the status code, and the latency. Deleting a source, or removing an attribute from it, has the same effect on policies that still read it. Change those policies first.

Build the endpoint

Request

Runlayer sends one POST per lookup with a JSON body:
A selected field with no value is null. Ignore fields you don’t recognize. New optional ones may be added. Your endpoint can tell calls apart only by the fields it receives. A source that doesn’t send Subject returns the same attributes for every user, so a policy can’t use it to treat users differently. Select every field your answer depends on. Runlayer never sends credentials, request headers, IP addresses, roles, or groups.

Response

Return HTTP 200 with every attribute the source declares:
  • A text value is at most 256 characters. A list has at most 64 text values.
  • Return null for an attribute that has no value for this call. A condition then treats it like any missing field: equals doesn’t match and not_equals does. This is not a failure and does not fail closed. See Negated operators and null.
  • A missing attribute, or one of the wrong type, counts as a failure for that attribute.
  • Extra attributes are ignored.
Anything else counts as a failure of the whole source: another status code (including redirects, which Runlayer doesn’t follow), a body that isn’t a JSON object with attributes, a body over 16 KiB, a timeout, or a connection error. If the connection can’t be opened, Runlayer retries once after 100 ms within the same timeout. Nothing else is retried. Connection tests have a request_id starting with test_.

Caching

Runlayer keeps a reply for the source’s cache time and reuses it for requests with the same body, apart from request_id. A source that receives only Subject is asked about once per user per cache time on each Runlayer server. Each field you add to the request makes cached answers match fewer calls. Failures are not cached. Editing a source or rotating its secret discards its cached answers. A cached reply is used until its cache time ends, whatever happens to the source in between:
  • During an outage, calls that match a cached reply are decided on it. Calls that don’t match one fail closed. Each server has its own cache, so the same call can be allowed on one server and denied on another until the cached replies expire.
  • After your endpoint changes its answer, for example when a ticket is revoked, Runlayer keeps using the old answer for up to the cache time.
Set Cache answers for (seconds) to the longest delay you accept for a revocation. Set it to 0 to ask on every call.

Verify requests

Requests are signed with the Standard Webhooks scheme, so any Standard Webhooks library can verify them. Each request carries webhook-id, webhook-timestamp, and webhook-signature headers. To verify by hand:
  1. Base64-decode the part of the secret after whsec_. That is the HMAC key.
  2. Compute base64(HMAC-SHA256(key, "{webhook-id}.{webhook-timestamp}.{raw body}")) over the exact bytes received.
  3. Accept the request if any v1,<signature> entry in webhook-signature matches, using a constant-time comparison.
  4. Reject requests whose webhook-timestamp is more than 5 minutes from your clock.
Replies are not signed. Runlayer trusts the reply because it connects to your endpoint over TLS.

Rotate the secret

Open the source’s menu and click Rotate secret. For 5 minutes after rotation, Runlayer signs every request with both the new and the old secret, so you can switch your verifier over without rejecting traffic.

Network requirements

  • The endpoint must use https. Credentials in the URL aren’t accepted. Use a header instead.
  • Private-network addresses are allowed, so the endpoint can run next to a self-hosted Runlayer. Loopback, link-local, and cloud metadata addresses are refused.
  • Don’t compress responses. Runlayer sends Accept-Encoding: identity.
Your endpoint is on the request path of every tool call whose policies read it, so keep it fast. Sources for one call are contacted at the same time, so a call waits for the slowest one. Each Runlayer server runs at most 20 lookups at a time for your organization. A lookup that is still waiting for its turn when the source’s timeout ends counts as a timeout, without a request to your endpoint. Cached answers don’t wait.

Test policies

The policy simulator does not contact your endpoint. A simulated call whose result depends on an external attribute is reported as conditional, with the attribute named.