Skip to content

Low level client

Jump to bottom
Justin "J.R." Hill edited this page Dec 20, 2023 · 3 revisions

Low-level client

Configuration

BaseConfiguration

All *Configuration types should provide the following:

  • String apiUrl
    • A URL for calling an OpenFGA server.
  • String userAgent
    • A value for a User-Agent HTTP header.
  • Temporal readTimeout
    • The time before an HTTP read will timeout.
  • Temporal connectTimeout
    • The time before an HTTP connection will timeout.
  • Integer maxRetries
    • For HTTP 4XX and 529 response codes, the maximum number retries that can be performed. See also: Retry
  • Temporal minimumRetryDelay
    • For HTTP 4XX and 529 retries, the minimum amount of time between retries. See also: Retry

BaseConfiguration can be implemented with language features like interfaces, abstract classes, or traits where appropriate.

Follow your language's conventions for how these should be presented. For example in Java, these are implemented as "getter" methods of an interface (like getApiUrl()), and classes that implement the interface implement these as private fields exposed by the public "getter" methods.

Configuration

In addition to the fields of BaseConfiguration, Configuration should contain:

  • Credentials credentials
  • Map or associative array defaultHeaders
    • Keys and values should be a String type
    • Any headers to apply by default (i.e. not overridden) to all requests of an OpenFGA client.

The Configuration should provide the following default values:

Attribute Value Mustache source
apiUrl "http://localhost:8080" N/A
userAgent "{{{userAgent}}}" config/common/config.base.json
readTimeout 10 seconds N/A
connectTimeout 10 seconds N/A

Configuration should also have an assertValid() function that evaluates the validity of Configuration. This should require that:

  • apiUrl is unset or is a valid URL. A valid URL has a scheme and hostname, and any optional URL components should be valid. In some languages this check can be accomplished simply by constructing some URL type from the language's standard library.
    • Note: It is not an error for the apiUrl to be unset. If it is null, nil, None, etc then the apiUrl should resolve to the default value above.
  • credentials is unset or is a valid credential as described in the Credentials assertValid() specification.

ClientConfiguration

In addition to the fields of Configuration and BaseConfiguration, ClientConfiguration should contain

  • String storeId
  • String authorizationModelId

Credentials

In most languages, Credentials should contain the following:

Credentials should also provide an isValid() function with the following check:

  • When credentialsMethod is NONE, the credentials are valid.
  • When credentialsMethod is API_TOKEN, the apiToken must be set.
  • When credentialsMethod is CLIENT_CREDENTIALS, the clientCredentials must be set.

Note: In languages that support tagged unions or algebraic data types, Credentials should be implemented as a mutually exclusive set of:

  • NONE
  • ApiToken apiToken
  • ClientCredentials clientCredentials

These languages do not need to implement the isValid() function, as there is nothing to validate.

CredentialsMethod

CredentialsMethod should be modeled as a set of mutually-exclusive values. In most languages this will be an "Enum" type. It should have the following values:

  • NONE, which corresponds to credential-less HTTP requests
  • API_TOKEN, which corresponds to an ApiToken
  • CLIENT_CREDENTIALS, which corresponds to a ClientCredentials

ApiToken

ApiToken is a static API token. In [OAuth 2.0][oauth2] terms, this indicates an "access token" that will be used to authenticate a request. In OpenFGA this can correspond to Pre-shared Key Authentication.

ApiToken should contain:

  • String token

ClientCredentials

ClientCredentials is a Client ID and Client Secret that can be exchanged with an [OAuth 2.0][oauth2] server. This corresponds to a Client Credentials Flow to authenticate and authorize a call to an OpenFGA server.

ClientCredentials should contain:

  • String clientId
  • String clientSecret
  • String apiTokenIssuer
  • String apiAudience

ClientCredentials should be only static data, and will not be concerned with performing network calls or retrieving an access token. ClientCredentials will be resolved as part of Authentication.

Function signature format

TODO: Expected low-level client function signatures. Mention storeId first (where applicable), then params, then configurations

Per-request override

TODO

Clone this wiki locally