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

If you want 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>2.1.0</version>
</dependency>

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

implementation("io.quarkiverse.openfga:quarkus-openfga-client:2.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

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.

In addition to starting and creating an authorization store, an authorization model can be initialized in the store by configuring the quarkus.openfga.devservices.authorization-model or quarkus.openfga.devservices.authorization-model.lcation property.

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.health.enabled

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

Environment variable: QUARKUS_OPENFGA_HEALTH_ENABLED

boolean

true

quarkus.openfga.tracing.enabled

Whether tracing spans of client commands are reported.

Environment variable: QUARKUS_OPENFGA_TRACING_ENABLED

boolean

false

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.url

OpenFGA server URL.

Example: http://openfga:8080

Environment variable: QUARKUS_OPENFGA_URL

URL

required

quarkus.openfga.shared-key

Shared authentication key.

If none provided unauthenticated access will be attempted.

Environment variable: QUARKUS_OPENFGA_SHARED_KEY

string

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.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

TLS configuration

Type

Default

quarkus.openfga.tls.skip-verify

Allows to bypass certificate validation on TLS communications.

If true this will allow TLS communications with OpenFGA, without checking the validity of the certificate presented by OpenFGA. This is discouraged in production because it allows man in the middle type of attacks.

Environment variable: QUARKUS_OPENFGA_TLS_SKIP_VERIFY

boolean

quarkus.openfga.tls.ca-cert

Certificate bundle used to validate TLS communications with OpenFGA.

The path to a pem bundle file, if TLS is required, and trusted certificates are not set through javax.net.ssl.trustStore system property.

Environment variable: QUARKUS_OPENFGA_TLS_CA_CERT

string
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.