{"id":28403853,"url":"https://github.com/openfga/spring-boot-starter","last_synced_at":"2025-06-27T08:32:17.181Z","repository":{"id":232262226,"uuid":"765889022","full_name":"openfga/spring-boot-starter","owner":"openfga","description":"A Spring Boot Starter for OpenFGA","archived":false,"fork":false,"pushed_at":"2025-06-01T23:37:36.000Z","size":425,"stargazers_count":39,"open_issues_count":10,"forks_count":9,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-06-02T04:18:04.882Z","etag":null,"topics":["access-control","fga","fine-grained-authorization","openfga","openfga-client"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openfga.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-01T20:24:30.000Z","updated_at":"2025-05-13T06:37:13.000Z","dependencies_parsed_at":"2025-04-28T21:25:44.829Z","dependency_job_id":"19d6cb03-e3a5-48d5-9d9d-640ae945dd72","html_url":"https://github.com/openfga/spring-boot-starter","commit_stats":null,"previous_names":["openfga/spring-boot-starter"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/openfga/spring-boot-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfga%2Fspring-boot-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfga%2Fspring-boot-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfga%2Fspring-boot-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfga%2Fspring-boot-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openfga","download_url":"https://codeload.github.com/openfga/spring-boot-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openfga%2Fspring-boot-starter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262222534,"owners_count":23277452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-control","fga","fine-grained-authorization","openfga","openfga-client"],"created_at":"2025-06-01T19:11:03.281Z","updated_at":"2025-06-27T08:32:17.169Z","avatar_url":"https://github.com/openfga.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenFGA Spring Boot Starter\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fopenfga%2Ffga-spring-boot.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenfga%2Ffga-spring-boot?ref=badge_shield)\n[![Join our community](https://img.shields.io/badge/slack-cncf_%23openfga-40abb8.svg?logo=slack)](https://openfga.dev/community)\n[![Twitter](https://img.shields.io/twitter/follow/openfga?color=%23179CF0\u0026logo=twitter\u0026style=flat-square \"@openfga on Twitter\")](https://twitter.com/openfga)\n\nA Spring Boot Starter for OpenFGA.\n\n## About\n\n[OpenFGA](https://openfga.dev) is an open source Fine-Grained Authorization solution inspired\nby [Google's Zanzibar paper](https://research.google/pubs/pub48190/). It was created by the FGA team\nat [Auth0](https://auth0.com) based on [Auth0 Fine-Grained Authorization (FGA)](https://fga.dev), available\nunder [a permissive license (Apache-2)](https://github.com/openfga/rfcs/blob/main/LICENSE) and welcomes community\ncontributions.\n\nOpenFGA is designed to make it easy for application builders to model their permission layer, and to add and integrate\nfine-grained authorization into their applications. OpenFGA’s design is optimized for reliability and low latency at a\nhigh scale.\n\n## Resources\n\n- [OpenFGA Documentation](https://openfga.dev/docs)\n- [OpenFGA API Documentation](https://openfga.dev/api/service)\n- [Twitter](https://twitter.com/openfga)\n- [OpenFGA Community](https://openfga.dev/community)\n- [Zanzibar Academy](https://zanzibar.academy)\n- [Google's Zanzibar Paper (2019)](https://research.google/pubs/pub48190/)\n\n## Installation\n\nThe OpenFGA Spring Boot Starter is available on [Maven Central](https://central.sonatype.com/).\n\nIt can be used with the following:\n\n* Gradle (Groovy)\n\n```groovy\nimplementation 'dev.openfga:openfga-spring-boot-starter:0.2.0'\n```\n\n* Gradle (Kotlin)\n\n```kotlin\nimplementation(\"dev.openfga:openfga-spring-boot-starter:0.2.0\")\n```\n\n* Apache Maven\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003edev.openfga\u003c/groupId\u003e\n    \u003cartifactId\u003eopenfga-spring-boot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e0.2.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Getting Started\n\n### Requirements\n\nJava \u003e= 17 and Spring Boot \u003e= 3\n\n### Configuring the starter\n\nThe OpenFGA Spring Boot Starter can be configured via\nstandard [Spring configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config).\nThe configuration properties are used to create\nan [OpenFgaClient](https://github.com/openfga/java-sdk/blob/main/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java)\ninstance.\n\nTo initialize the OpenFGA Spring Boot Starter, please provide the configuration property `openfga.api-url`. An\n`OpenFgaClient` instance will then be created with the provided configuration.\n\nThe following examples demonstrate how to configure the OpenFGA Spring Boot Starter.\n\n#### No Credentials\n\n```yaml\n# src/main/resources/application.yaml\n\nopenfga:\n  api-url: YOUR_FGA_API_URL\n  store-id: YOUR_FGA_STORE_ID\n  authorization-model-id: YOUR_FGA_AUTHORIZATION_MODEL_ID\n```\n\n#### API Token\n\n```yaml\n# src/main/resources/application.yaml\n\nopenfga:\n  api-url: YOUR_FGA_API_URL\n  store-id: YOUR_FGA_STORE_ID\n  authorization-model-id: YOUR_FGA_AUTHORIZATION_MODEL_ID\n  credentials:\n    method: API_TOKEN # constant\n    config:\n      api-token: YOUR_API_TOKEN\n```\n\n#### Client Credentials\n\n```yaml\n# src/main/resources/application.yaml\n\nopenfga:\n  api-url: YOUR_FGA_API_URL\n  store-id: YOUR_FGA_STORE_ID\n  authorization-model-id: YOUR_FGA_AUTHORIZATION_MODEL_ID\n  credentials:\n    method: CLIENT_CONFIGURATION # constant\n    config:\n      client-id: YOUR_CLIENT_ID\n      client-secret: YOUR_CLIENT_SECRET\n      api-token-issuer: YOUR_API_TOKEN_ISSUER\n      api-audience: YOUR_API_AUDIENCE\n      scopes: YOUR_SPACE_SEPERATED_SCOPES\n```\n\n#### Full Configuration Example\n\n```yaml\n# src/main/resources/application.yaml\n\nopenfga:\n  api-url: YOUR_FGA_API_URL\n  store-id: YOUR_FGA_STORE_ID\n  authorization-model-id: YOUR_FGA_AUTHORIZATION_MODEL_ID\n  user-agent: YOUR_USER_AGENT # default: openfga-sdk java/version\n  read-timeout: 1m # default: 10 seconds\n  connect-timeout: 15 # default: 10 seconds\n  max-retries: 3 # default: no retries\n  minimum-retry-delay: 1m\n  http-version: HTTP_2\n  default-headers:\n    X-SOME-HEADER: Some Header Value\n  telemetry-configuration:\n    fga_client_request_model_id: YOUR_FGA_CLIENT_REQUEST_MODEL_ID\n  credentials:\n    method: CLIENT_CONFIGURATION # constant\n    config:\n      client-id: YOUR_CLIENT_ID\n      client-secret: YOUR_CLIENT_SECRET\n      api-token-issuer: YOUR_API_TOKEN_ISSUER\n      api-audience: YOUR_API_AUDIENCE\n      scopes: YOUR_SPACE_SEPERATED_SCOPES\n```\n\n### Configuration Properties\n\nThe OpenFGA Spring Boot Starter can be configured using the following properties:\n\n#### `openfga.api-url`\n\n- **Description**: The base URL of the OpenFGA API endpoint.\n- **Example**: `https://api.openfga.example.com`\n\n#### `openfga.store-id`\n\n- **Description**: The unique identifier for the store in OpenFGA.\n- **Example**: `store-12345`\n\n#### `openfga.authorization-model-id`\n\n- **Description**: The unique identifier for the authorization model in OpenFGA.\n- **Example**: `auth-model-67890`\n\n#### `openfga.user-agent`\n\n- **Description**: The user agent string to be included in the request headers.\n- **Example**: `MyApp/1.0.0`\n- **Default**: `openfga-sdk java/version`\n\n#### `openfga.read-timeout`\n\n- **Description**: The maximum duration to wait for a read operation to complete. Default unit is seconds. Must be positive or null.\n- **Example**: `30s`\n- **Default**: `10s`\n\n#### `openfga.connect-timeout`\n\n- **Description**: The maximum duration to wait for a connection to be established. Default unit is seconds. Must be positive or null.\n- **Example**: `10s`\n- **Default**: `10s`\n\n#### `openfga.max-retries`\n\n- **Description**: The maximum number of retry attempts for failed requests. Must be positive or null. If you set this to a positive value, ensure that you also set the `minimum-retry-delay` property.\n- **Example**: `5`\n- **Default**: No retries\n\n#### `openfga.minimum-retry-delay`\n\n- **Description**: The minimum delay between retry attempts. Default unit is seconds. Must be positive or null. Only used if `max-retries` is set.\n- **Example**: `500ms`\n- **Default**: `10s`\n\n#### `openfga.http-version`\n\n- **Description**: The HTTP version to use for requests.\n- **Example**: `HTTP_1_1`\n- **Default**: `HTTP_2`\n\n#### `openfga.default-headers`\n\n- **Description**: Default headers to be included in all requests.\n- **Example**:\n\n  ```yaml\n  default-headers:\n    X-Custom-Header: CustomHeaderValue\n\n  ```\n\n#### `openfga.telemetry-configuration`\n\n- **Description**: Configuration settings for telemetry, which help in monitoring and logging the behavior of the\n  OpenFGA client.\n- **Example**:\n\n  ```yaml\n  telemetry-configuration:\n    fga_client_request_model_id: \"example-model-id\"\n  ```\n\n#### `openfga.credentials.method`\n\n- **Description**: Specifies the authentication method to be used for connecting to the OpenFGA API.\n- **Possible Values**:\n  - `NONE`: No authentication.\n  - `API_TOKEN`: Use an API token for authentication.\n  - `CLIENT_CREDENTIALS`: Use OAuth2 client credentials for authentication.\n\n#### `openfga.credentials.config.api-token`\n\n- **Description**: The API token used for authenticating requests when the `API_TOKEN` method is selected.\n- **Example**: `your-api-token`\n\n#### `openfga.credentials.config.client-id`\n\n- **Description**: The client ID used for OAuth2 authentication when the `CLIENT_CREDENTIALS` method is selected.\n- **Example**: `your-client-id`\n\n#### `openfga.credentials.config.client-secret`\n\n- **Description**: The client secret used for OAuth2 authentication when the `CLIENT_CREDENTIALS` method is selected.\n- **Example**: `your-client-secret`\n\n#### `openfga.credentials.config.api-token-issuer`\n\n- **Description**: The issuer of the API token used for OAuth2 authentication when the `CLIENT_CREDENTIALS` method is\n  selected.\n- **Example**: `https://issuer.example.com`\n\n#### `openfga.credentials.config.api-audience`\n\n- **Description**: The audience for the API token used for OAuth2 authentication when the `CLIENT_CREDENTIALS` method is\n  selected.\n- **Example**: `https://api.example.com`\n\n#### `openfga.credentials.config.scopes`\n\n- **Description**: The scopes required for OAuth2 authentication when the `CLIENT_CREDENTIALS` method is selected.\n  Scopes are space-separated.\n- **Example**: `read write`\n\n### Using the `fgaClient` bean\n\nOnce configured, an `fgaClient` bean is available to be injected into your Spring components:\n\n```java\n\n@Service\npublic class MyService {\n\n    @Autowired\n    private OpenFgaClient fgaClient;\n}\n```\n\nThis can be used to interact with the FGA API, for example to write authorization data:\n\n```java\n// field injection just for briefness\n@Autowired\nprivate OpenFgaExceptionHandler exceptionHandler;\n\npublic Document createDoc(String id) {\n    // ...\n    ClientWriteRequest writeRequest = new ClientWriteRequest().writes(List.of(new ClientTupleKey()\n            .user(String.format(\"user:%s\", SecurityContextHolder.getContext().getAuthentication()))\n            .relation(\"owner\")\n            ._object(String.format(\"document:%s\", id))));\n\n    try {\n        fgaClient.write(writeRequest).get();\n    } catch (final InterruptedException | ExecutionException | FgaInvalidParameterException cause) {\n        // Option 1: use your custom exception handling for the native exception thrown from the client\n        // throw new RuntimeException(\"Error writing to FGA\", cause);\n      \n        // Option 2: use the exception handler provided by the starter\n        // the exception handler is available as autoconfigured bean\n        // do whatever you need with it log, throw, ...\n        // params follow the String.format() patterns\n        throw exceptionHandler.handle(cause, \"Error creating doc '%s'\", id);\n    }\n}\n```\n\n### Using the `fga` bean\n\nThe starter also creates an `fga` bean, which can be used in conjunction with Spring Security's method\nsecurity to protect access to resources using FGA:\n\n```java\n// Method body will only execute if the FGA check returns true. 403 otherwise.\n@PreAuthorize(\"@fga.check('document', #docId, 'reader', 'user', authentication?.name)\")\npublic Document getDocument(@PathVariable String docId) {\n    return repository.findById(id);\n}\n```\n\nYou may also omit the user ID, in which case the name of the currently authenticated principal\nwill be used as the user ID:\n\n```java\n// Method body will only execute if the FGA check returns true. 403 otherwise.\n@PreAuthorize(\"@fga.check('document', #docId, 'reader', 'user')\")\npublic Document getDocument(@PathVariable String docId) {\n    return repository.findById(id);\n}\n```\n\n## Customize ApiClient and HttpClient Configuration\n\nTo customize the `ApiClient` configuration, create a `@Bean` method in your Spring Boot application:\n\n```java\n@Bean\npublic ApiClient apiClient(HttpClient.Builder builder, ObjectMapper mapper) {\n    return new ApiClient(httpClientBuilder, objectMapper);\n}\n```\n\nSimilarly, to customize the `HttpClient.Builder`:\n\n```java\n@Bean\npublic HttpClient.Builder httpClientBuilder() {\n    return HttpClient.newBuilder()\n            .version(Version.HTTP_2);\n}\n```\n\n## Contributing\n\n### Issues\n\nIf you have found a bug or if you have a feature request,\nplease [create an issue](https://github.com/openfga/fga-spring-boot/issues). Please do not report security\nvulnerabilities on the public GitHub issue tracker.\n\n### Pull Requests\n\nPull requests are welcome, however, we do kindly ask that for non-trivial changes or feature additions, that you create\nan [issue]((https://github.com/openfga/fga-spring-boot/issues)) first.\n\n## Author\n\n[OpenFGA](https://github.com/openfga)\n\n## License\n\nThis project is licensed under the Apache-2.0 license. See\nthe [LICENSE](https://github.com/openfga/fga-spring-boot/blob/main/LICENSE) file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenfga%2Fspring-boot-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenfga%2Fspring-boot-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenfga%2Fspring-boot-starter/lists"}