Quarkus OpenFGA Client

Overview

The Quarkus OpenFGA Client extension provides a reactive client for accessing OpenFGA instances. Additionally, it is the client that powers the Quarkus Zanzibar - OpenFGA Connector to provide Find Grained Authorization for Quarkus applications.

Installation

To use this extension, you need to add the io.quarkiverse.openfga:quarkus-openfga-client extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.openfga</groupId>
    <artifactId>quarkus-openfga-client</artifactId>
    <version>3.1.0</version>
</dependency>

Or with Gradle, add the dependency to your build.gradle or build.gradle.kts file:

implementation("io.quarkiverse.openfga:quarkus-openfga-client:3.1.0")

Configuration

The extension requires two configuration properties to be defined at startup to define what instance and store are targeted by the client. The url property selects the scheme, host and, optionally, the port of the OpenFGA instance. While store determines which authorization store is targeted; it can be referenced by store id or name.

quarkus.openfga.url=http://localhost:80
quarkus.openfga.store=my-app-authz
# Optional authorization model id
#quarkus.openfga.authorization-model-id=11G22H33I44J55K66L77M88N99

Credentials

The client supports configuring Pre-Shared Key and dynamic OIDC credentials for authentication, in addition to the default of providing no credentials.

To enable a specific credentials method, set the quarkus.openfga.credentials.method property to the desired method, either none, preshared, or oidc. If no credentials method is explicitly configured, the client will default to none and provide no credentials.

quarkus.openfga.credentials.method=preshared
The selected credentials method must be configured in the OpenFGA instance separately.

Pre-Shared Key

When using the pre-Shared Key method, the client requires the quarkus.openfga.credentials.preshared.key property to be set to a pre-shared key configured in the OpenFGA instance.

quarkus.openfga.credentials.method=preshared
quarkus.openfga.credentials.preshared.key=my-secret-key (1)
1 (required) A pre-shared key configured in the OpenFGA instance.

OIDC

When using the OIDC method, the client requires a number of properties to be set that are provided by the OIDC provider.

quarkus.openfga.credentials.method=oidc
quarkus.openfga.credentials.oidc.client-id=my-client-id (1)
quarkus.openfga.credentials.oidc.client-secret=my-client-secret (2)
quarkus.openfga.credentials.oidc.audience=https://my-audience (3)
quarkus.openfga.credentials.oidc.token-issuer=https://my-oidc-provider.com (4)
quarkus.openfga.credentials.oidc.token-issuer-path=/oauth2/token (5)
1 (required) Client ID provided by the OIDC provider.
2 (required) Client Secret provided by the OIDC provider.
3 (required) Audience provided by the OIDC provider.
4 (required) Token issuer URL provided by the OIDC provider, this can be a full URL to the token issuer endpoint or just the base URL of the OIDC provider.
5 (optional) The OIDC provider’s token issuer path, which is resolved against the token-issuer property to determine the full token issuer URL. This is only required if the token issuer URL does not include the token issuer path.

There are additional properties that can be provided to configure the OIDC client, these are detailed in the Extension Configuration Reference.

DevServices

The extension supports Quarkus’s DevServices and will start and configure a local OpenFGA in dev and test if no url configuration property is provided. Additionally it will automatically create and configure an authorization store in the server.

Configuration

To enable DevServices, set the quarkus.openfga.devservices.enabled property to true, which is enabled for the dev and test profiles by default. This will start a local OpenFGA instance to run unauthenticated, initialize an empty store and configure the client to connect to the local instance.

Startup Initialization

In addition to starting and creating an authorization store, an authorization model and/or tuples can be loaded into the store on startup by providing the appropriate configuration properties.

quarkus.openfga.devservices.enabled=true
quarkus.openfga.devservices.authorization-model-location=auth-model.json (1)
quarkus.openfga.devservices.authorization-tuples-location=auth-tuples.json (2)
1 (optional) The location of the authorization model JSON file to load into the store.
2 (optional) The location of the authorization tuples JSON file to load into the store.
The authorization model and tuples JSON files are loaded from the classpath by default, but can be loaded from a filesystem path by prefixing the location with filesystem:. As in, filesystem:/path/to/auth-model.json.
Authentication

For most development and test use cases an unauthenticated configuration is sufficient. However, for simulating a production environment, the DevServices instance can be configured to use a specific authorization method by setting the quarkus.openfga.devservices.authentication.method property to the desired method, either none, preshared, or oidc.

Here is an example configuration for using the pre-shared key method:

quarkus.openfga.devservices.authentication.method=preshared
quarkus.openfga.devservices.authentication.preshared.keys=my-secret-key (1)
1 (required) A pre-shared key to use for authentication. This can be a single key or a comma-separated list of keys.

This will configure the DevServices instance to use the pre-shared key method for authentication and pass the provided key(s) to the instance. Additionally, the client will be configured to use the same method and one of the provided keys to authenticate with the DevServices instance.

For OIDC, the OpenFGA requires you to use a separate OIDC provider to authenticate the DevServices instance. See the Extension Configuration Reference for the specific configuration properties available.

Basic Usage

Adding the quarkus-openfga-client extension to your project defines clients beans OpenFGAClient that are configured to access the OpenFGA instance configured in application.properties.

Clients

The extension provides three injectable clients for accessing the configured instance and store.

OpenFGAClient

Main client for accessing the OpenFGA instance.

StoreClient

Access authorization store configured via quarkus.openfga.store-id

AuthorizationModelsClient

Manage (list, create, delete) authorization models and create AuthorizationModelClient instances for accessing a specific model.

AuthorizationModelClient

Access authorization model configured via quarkus.openfga.authoriztion-model-id or the default model if none is configured.

Examples

Write a Relationship Tuple

class ExampleTupleWriter {

    @Inject
    StoreClient storeClient;

    void write() {
        var authModelClient = storeClient.authorizationModels().defaultModel();
        authModelClient.write(TupleKey.of("thing:1", "reader", "user:me"));
    }
}

Check Access for a Relationship Tuple

class Example {

    @Inject
    AuthorizationModelClient defaultAuthModelClient;

    void write() {
        if (defaultAuthModelClient.check(TupleKey.of("thing:1", "reader", "user:me"))) {
            System.out.println("Allowed!");
        }
    }
}

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.openfga.url

OpenFGA server URL.

Example: http://openfga:8080

Environment variable: QUARKUS_OPENFGA_URL

URL

required

quarkus.openfga.store

Store id or name for default StoreClient bean.

If the provided property does not match the OpenFGA store id format (^[ABCDEFGHJKMNPQRSTVWXYZ0-9]{26$}) it will be treated as a store name and a matching store id will be resolved at runtime.

Environment variable: QUARKUS_OPENFGA_STORE

string

required

quarkus.openfga.always-resolve-store-id

Always Treat store as the name of a store and resolve the store id at runtime.

If true, the store id will always be resolved at runtime regardless of the format of the store property. Otherwise, the store id will be resolved only when store does not match the OpenFGA store id format.

Environment variable: QUARKUS_OPENFGA_ALWAYS_RESOLVE_STORE_ID

boolean

false

quarkus.openfga.authorization-model-id

Authorization model id for default AuthorizationModelClient bean.

If none is provided, the default bean will target the default authorization model for the store.

Environment variable: QUARKUS_OPENFGA_AUTHORIZATION_MODEL_ID

string

quarkus.openfga.tls-configuration-name

The name of the TLS configuration to use.

If not set and the default TLS configuration is configured (quarkus.tls.*) then that will be used. If a name is configured, it uses the configuration from quarkus.tls.<name>.* If a name is configured, but no TLS configuration is found with that name then an error will be thrown.

Environment variable: QUARKUS_OPENFGA_TLS_CONFIGURATION_NAME

string

quarkus.openfga.connect-timeout

Timeout to establish a connection with OpenFGA.

Environment variable: QUARKUS_OPENFGA_CONNECT_TIMEOUT

Duration 

5S

quarkus.openfga.read-timeout

Request timeout on OpenFGA.

Environment variable: QUARKUS_OPENFGA_READ_TIMEOUT

Duration 

5S

quarkus.openfga.non-proxy-hosts

List of remote hosts that are not proxied when the client is configured to use a proxy. This list serves the same purpose as the JVM nonProxyHosts configuration.

Entries can use the * wildcard character for pattern matching, e.g *.example.com matches www.example.com.

Environment variable: QUARKUS_OPENFGA_NON_PROXY_HOSTS

list of string

Health Check Configuration

Type

Default

quarkus.openfga.health.enabled

Whether a health check is published in case the smallrye-health extension is present.

Environment variable: QUARKUS_OPENFGA_HEALTH_ENABLED

boolean

true

Tracing Configuration

Type

Default

quarkus.openfga.tracing.enabled

Whether tracing spans of client commands are reported.

Environment variable: QUARKUS_OPENFGA_TRACING_ENABLED

boolean

true

Dev Services Configuration

Type

Default

quarkus.openfga.devservices.enabled

If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present.

When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in 'dev' or 'test' mode.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_ENABLED

boolean

quarkus.openfga.devservices.image-name

The container image name to use, for container based DevServices providers.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_IMAGE_NAME

string

quarkus.openfga.devservices.shared

Indicates if the OpenFGA instance managed by Quarkus DevServices is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, DevServices for OpenFGA starts a new container.

The discovery uses the quarkus-dev-service-openfga label. The value is configured using the service-name property.

Container sharing is only used in 'dev' mode.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_SHARED

boolean

true

quarkus.openfga.devservices.service-name

The value of the quarkus-dev-service-openfga label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, DevServices for OpenFGA looks for a container with the quarkus-dev-service-openfga label set to the configured value. If found, it will use this container instead of starting a new one, otherwise it starts a new container with the quarkus-dev-service-openfga label set to the specified value.

This property is used when you need multiple shared OpenFGA instances.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_SERVICE_NAME

string

openfga

quarkus.openfga.devservices.http-port

Optional fixed port the HTTP service will be bound to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_HTTP_PORT

int

quarkus.openfga.devservices.grpc-port

Optional fixed port the gRPC service will be bound to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_GRPC_PORT

int

quarkus.openfga.devservices.playground-port

Optional fixed port the Playground service will be bound to.

If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_PLAYGROUND_PORT

int

quarkus.openfga.devservices.store-name

Name of authorization store to create for DevServices.

Defaults to "dev".

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_STORE_NAME

string

dev

quarkus.openfga.devservices.authorization-model

JSON formatted authorization model to upload during DevServices initialization.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHORIZATION_MODEL

string

quarkus.openfga.devservices.authorization-model-location

Location of JSON formatted authorization model file to upload during DevServices initialization.

The location can be prefixed with classpath: or filesystem: to specify where the file will be read from; if not prefixed, it will be read from the classpath.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHORIZATION_MODEL_LOCATION

string

quarkus.openfga.devservices.authorization-tuples

JSON formatted authorization tuples to upload during DevServices initialization.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHORIZATION_TUPLES

string

quarkus.openfga.devservices.authorization-tuples-location

Location of JSON formatted authorization tuples file to upload during DevServices initialization.

The location can be prefixed with classpath: or filesystem: to specify where the file will be read from; if not prefixed, it will be read from the classpath.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHORIZATION_TUPLES_LOCATION

string

quarkus.openfga.devservices.authentication.method

Authentication method to configure for the dev services instance.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHENTICATION_METHOD

none, preshared, oidc

none

quarkus.openfga.devservices.authentication.preshared.keys

Pre-shared authentication keys.

The dev services OpenFGA instance will be configured with these pre-shared keys for authentication.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHENTICATION_PRESHARED_KEYS

list of string

required

quarkus.openfga.devservices.authentication.oidc.issuer

OIDC issuer (authorization server) signing the tokens, and where the keys will be fetched from.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHENTICATION_OIDC_ISSUER

string

required

quarkus.openfga.devservices.authentication.oidc.audience

OIDC audience of the tokens being signed by the authorization server.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHENTICATION_OIDC_AUDIENCE

string

required

quarkus.openfga.devservices.authentication.oidc.issuer-aliases

OIDC issuer DNS aliases that will be accepted as valid when verifying the iss field of the JWTs.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHENTICATION_OIDC_ISSUER_ALIASES

list of string

quarkus.openfga.devservices.authentication.oidc.subjects

OIDC subject names that will be accepted as valid when verifying the sub field of the JWTs. If empty, every sub will be allowed

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHENTICATION_OIDC_SUBJECTS

list of string

quarkus.openfga.devservices.authentication.oidc.client-id-claims

ClientID claims that will be used to parse the clientID - configure in order of priority (first is highest).

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_AUTHENTICATION_OIDC_CLIENT_ID_CLAIMS

list of string

quarkus.openfga.devservices.tls.pem-certificate-path

Path to file containing a PEM encoded certificate to use for the DevServices OpenFGA instance.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_TLS_PEM_CERTIFICATE_PATH

string

required

quarkus.openfga.devservices.tls.pem-key-path

Path to file containing a PEM encoded private key to use for the DevServices OpenFGA instance.

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_TLS_PEM_KEY_PATH

string

required

quarkus.openfga.devservices.startup-timeout

Timeout while creating the store/authorizationModel

Environment variable: QUARKUS_OPENFGA_DEVSERVICES_STARTUP_TIMEOUT

Duration 

5S

Credentials Configuration

Type

Default

quarkus.openfga.credentials.method

Credentials method to use for authentication.

When set to preshared, the required preshared configuration keys must be provided.

When set to oidc, the required oidc configuration keys must be provided.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_METHOD

none, preshared, oidc

none

Pre-shared Authentication Key Credentials Configuration

Type

Default

quarkus.openfga.credentials.preshared.key

Pre-shared authentication key.

The dev services OpenFGA instance will be configured with these pre-shared keys for authentication.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_PRESHARED_KEY

string

required

OIDC Client Credentials Configuration

Type

Default

quarkus.openfga.credentials.oidc.client-id

OAuth client id.

The client id is used to identify the client to the authorization server and is provided by the authorization service.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_OIDC_CLIENT_ID

string

required

quarkus.openfga.credentials.oidc.client-secret

OAuth client secret.

The client secret is used to authenticate the client to the authorization server and is provided by the authorization service.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_OIDC_CLIENT_SECRET

string

required

quarkus.openfga.credentials.oidc.audience

OAuth audience URI.

The audience for the access token, typically the URL of the service that will consume the token. This is generally configured in the authorization service.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_OIDC_AUDIENCE

URI

required

quarkus.openfga.credentials.oidc.scopes

OAuth scopes.

The scopes to request for the access token.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_OIDC_SCOPES

string

quarkus.openfga.credentials.oidc.token-issuer

OAuth token issuer URL.

The URL of the authorization service that will issue the access token.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_OIDC_TOKEN_ISSUER

URI

required

quarkus.openfga.credentials.oidc.token-issuer-path

OAuth token issuer path.

The path of the token issuer endpoint, relative to the token-issuer() URL.

Default value is /oauth/token.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_OIDC_TOKEN_ISSUER_PATH

string

quarkus.openfga.credentials.oidc.token-expiration-threshold

Token expiration threshold.

The duration before the token expiration at which the token should be refreshed.

Default value is 300s.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_OIDC_TOKEN_EXPIRATION_THRESHOLD

Duration 

quarkus.openfga.credentials.oidc.token-expiration-threshold-jitter

Token expiration threshold jitter.

The maximum jitter to add to the token expiration threshold.

Default value is 60s.

Environment variable: QUARKUS_OPENFGA_CREDENTIALS_OIDC_TOKEN_EXPIRATION_THRESHOLD_JITTER

Duration 
About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

  • If the value is only a number, it represents time in seconds.

  • If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

  • If the value is a number followed by h, m, or s, it is prefixed with PT.

  • If the value is a number followed by d, it is prefixed with P.