External resources

The externalResources block lists third-party services, outside your trust domain, that Defakto gets access tokens for on behalf of your workloads. A workload asks Defakto for a token, naming the service, and Defakto requests one from the service's authorization server with its own client registration. Defakto returns the service's token to the workload unchanged.

For a step-by-step guide, see Get tokens for external services.

Example

externalResources:
  - name: vendor-api
    resource: https://api.example.net
    authorizationServer:
      issuer: https://auth.example.net
    grant:
      clientCredentials:
        clientID: <client-id-at-the-service>
        clientAuth:
          method: client_secret_basic
          secretRef:
            name: vendor-api
            key: clientSecret
        scopes: [records.read, records.write]

Fields

Field	Required	Description	Example
name	Yes	A name for the entry. A DNS label, unique across all named entries in the section.	vendor-api
resource	Yes	A logical name for the service, which workloads send as the audience when they ask for a token for it, and which token policy rules name in match.audience. It doesn't need to be the service's real address, so you can give separate entries for the same service different names. An absolute URI, with no fragment and no *, unique across entries. Once an entry exists, a request for this value always gets the service's token, never a token Defakto issues.	https://api.example.net
authorizationServer.issuer	Yes	The issuer URL of the service's authorization server. Defakto finds the authorization server's token endpoint in the OAuth or OpenID Connect discovery metadata published at this issuer, so the authorization server must publish that metadata.	https://auth.example.net
grant.clientCredentials.clientID	Yes	Defakto's client ID at the service's authorization server.	<client-id-at-the-service>
grant.clientCredentials.clientAuth	Yes	How Defakto authenticates to the service's authorization server, with a signed JWT or a client secret. See clientAuth.	method: client_secret_basic
grant.clientCredentials.scopes	Yes	The scopes Defakto requests from the service. A workload can request fewer, and gets all of them if it requests none. Token policy rules can narrow them further with allowedScopes.	[records.read, records.write]

Defakto gets the token with the OAuth client credentials grant, acting as itself.

What applies to external service tokens

A request for an entry's tokens is refused unless an allow or external authorizer rule matches it, and that rule's match.audience names the entry's resource, even without an authorization block. See Token policy.

Defakto doesn't issue external service tokens, so some token policy settings don't apply to them:

• Only allowedScopes narrows them. maxTTL and customClaims don't apply, because the service's authorization server sets the token's lifetime and contents.
• External service tokens are issued only to workloads acting as themselves, never on behalf of a user. Rules for an external service can't name a user.
• Defakto never accepts an external service token back as a token to exchange.

See the protocol reference for the request a workload sends.

Validation

When you apply the configuration, Defakto also rejects:

• Two entries with the same resource
• A resource that's also the trust domain's OAuth issuer, or that appears in any identity provider's audiences
• Removing an entry while a token policy rule names its resource
• Adding an entry whose resource a token policy rule already names as an audience for tokens that Defakto issues
• A token policy rule for an external service that names a user, sets maxTTL or customClaims, or requests anything other than an access token
• allowedScopes outside the entry's grant.clientCredentials.scopes