README.md

OpenFGA Spring Boot Starter

A Spring Boot Starter for OpenFGA.

About

OpenFGA is an open source Fine-Grained Authorization solution inspired by Google's Zanzibar paper. It was created by the FGA team at Auth0 based on Auth0 Fine-Grained Authorization (FGA), available under a permissive license (Apache-2) and welcomes community contributions.

OpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate fine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a high scale.

Resources

• OpenFGA Documentation
• OpenFGA API Documentation
• Twitter
• OpenFGA Community
• Zanzibar Academy
• Google's Zanzibar Paper (2019)

Installation

The OpenFGA Spring Boot Starter is available on Maven Central.

It can be used with the following:

• Gradle (Groovy)

implementation 'dev.openfga:openfga-spring-boot-starter:0.0.1'

• Gradle (Kotlin)

implementation("dev.openfga:openfga-spring-boot-starter:0.0.1")

• Apache Maven

<dependency>
    <groupId>dev.openfga</groupId>
    <artifactId>openfga-spring-boot-starter</artifactId>
    <version>0.0.1</version>
</dependency>

Getting Started

Requirements

Java 17 and Spring Boot 3

Configuring the starter

The OpenFGA Spring Boot Starter can be configured via standard Spring configuration. The configuration properties are used to create an OpenFgaClient instance.

No Credentials

# src/main/resources/application.yaml

openfga:
  api-url: YOUR_FGA_API_URL
  store-id: YOUR_FGA_STORE_ID
  authorization-model-id: YOUR_FGA_AUTHORIZATION_MODEL_ID

API Token

# src/main/resources/application.yaml

openfga:
  api-url: YOUR_FGA_API_URL
  store-id: YOUR_FGA_STORE_ID
  authorization-model-id: YOUR_FGA_AUTHORIZATION_MODEL_ID
  credentials:
    method: API_TOKEN # constant
    config:
      api-token: YOUR_API_TOKEN

Client Credentials

# src/main/resources/application.yaml

openfga:
  api-url: YOUR_FGA_API_URL
  store-id: YOUR_FGA_STORE_ID
  authorization-model-id: YOUR_FGA_AUTHORIZATION_MODEL_ID
  credentials:
    method: CLIENT_CONFIGURATION # constant
    config:
        client-id: YOUR_CLIENT_ID
        client-secret: YOUR_CLIENT_SECRET
        api-token-issuer: YOUR_API_TOKEN_ISSUER
        api-audience: YOUR_API_AUDIENCE
        scopes: YOUR_SPACE_SEPERATED_SCOPES

Using the fgaClient bean

Once configured, an fgaClient bean is available to be injected into your Spring components:

@Service
public class MyService {
    
    @Autowired
    private OpenFgaClient fgaClient;
}

This can be used to interact with the FGA API, for example to write authorization data:

public Document createDoc(String id) {
    // ...
    ClientWriteRequest writeRequest =  new ClientWriteRequest()
            .writes(List.of(new ClientTupleKey()
                    .user(String.format("user:%s", SecurityContextHolder.getContext().getAuthentication()))
                    .relation("owner")
                    ._object(String.format("document:%s", id))));

    try {
        fgaClient.write(writeRequest).get();
    } catch (InterruptedException | ExecutionException | FgaInvalidParameterException e) {
        throw new RuntimeException("Error writing to FGA", e);
    }
    // ...
}

Using the fga bean

The starter also creates an fga bean, which can be used in conjunction with Spring Security's method security to protect access to resources using FGA:

// Method body will only execute if the FGA check returns true. 403 otherwise.
@PreAuthorize("@fga.check('document', #docId, 'reader', 'user', authentication?.name)")
public Document getDocument(@PathVariable String docId) {
    return repository.findById(id);
}

You may also omit the user ID, in which case the name of the currently authenticated principal will be used as the user ID:

// Method body will only execute if the FGA check returns true. 403 otherwise.
@PreAuthorize("@fga.check('document', #docId, 'reader', 'user')")
public Document getDocument(@PathVariable String docId) {
    return repository.findById(id);
}

Contributing

Issues

If you have found a bug or if you have a feature request, please create an issue. Please do not report security vulnerabilities on the public GitHub issue tracker.

Pull Requests

Pull requests are welcome, however we do kindly ask that for non-trivial changes or feature additions, that you create an issue first.

Author

OpenFGA

License

This project is licensed under the Apache-2.0 license. See the LICENSE file for more info.