OpenFGA Client SDK Generator

This is the main generator responsible for generating the OpenFGA SDKs from the OpenFGA OpenAPIv2 Document.

OpenFGA Client SDK Generator

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

Currently Supported SDKs

Language	GitHub	Package Manager
Javascript	openfga/js-sdk
Go	openfga/go-sdk
.NET	openfga/dotnet-sdk
Python	openfga/python-sdk
Java	openfga/java-sdk

Getting Started

Requirements

Git
Docker
Make (Optional, but makes things much easier)
curl
Bash
sed

Usage

Clone this repo:

git clone git@github.com:openfga/sdk-generator.git

Clone existing SDKs into the clients directory

git clone git@github.com:openfga/go-sdk.git clients/fga-go-sdk
git clone git@github.com:openfga/js-sdk.git clients/fga-js-sdk
git clone git@github.com:openfga/dotnet-sdk.git clients/fga-dotnet-sdk
git clone git@github.com:openfga/python-sdk.git clients/fga-python-sdk
git clone git@github.com:openfga/java-sdk.git clients/fga-java-sdk

Build and test the client sdks
```
make
```

Adding a new SDK

Using the setup script

There is a helpful script to setup a new SDK

make setup-new-sdk

It will ask you for a an SDK ID, use something like: go, js, dotnet, java, etc...
It will ask you for a valid generator
Then in will initialize all the files, you will need to add the configuration specific to that sdk
Now you can run make build-client-${SDK_ID} to generate the SDK

Manually

Create config dir in: config/clients/{lang}/. It should include:
- CHANGELOG.md: To be updated as new releases are generated
- generator.txt: the name of the generator to use. Must be a valid generator
- config.overrides.json: Custom config for this generator + overrides to the common config in config/common/config.base.json
- .openapi-generator-ignore: Any files that the generator should ignore and not built
- template-source: Newer SDKs should have this to mark what commit of the generator we branched off
- template/ directory
  - LICENSE: Apache-2.0 License
  - .github/workflows/main.yml: Any CI checks that need to run
  - The following files, each with the relevant section (look at the JS template for an example):
    - README_installation.mustache
    - README_initializing.mustache
    - README_calling_api.mustache
    - README_api_endpoints.mustache
    - README_models.mustache
    - README_license_disclaimer.mustache
    - README_custom_badges.mustache (optional, any custom badges for this specific SDK)
    - gitignore_custom.mustache (optional, any custom ignores for this specific SDK)
    - NOTICE_details.mustache (optional, see Updating the Notice files)
  - custom files according to the generator

Update the Makefile.

add a target for the new sdk

.PHONY: build-client-{{LANG}}
build-client-{{LANG}}:
make build-client sdk_language={{LANG}} tmpdir=${TMP_DIR}
# ... any other custom build steps ...

add it as a dependency to the build-all-clients

.PHONY: build-all-clients
build-all-clients: build-client-js build-client-go ...  build-client-{{LANG}}

add a target for the new sdk's tests that depend on the build target

.PHONY: test-client-{{LANG}}
test-client-{{LANG}}: build-client-{{LANG}}
# ... any custom test code ...

add it as a dependency to the test-all-clients

.PHONY: test-all-clients
test-all-clients: test-client-js test-client-go ...  test-client-{{LANG}}

Note: Try to ensure that the SDK is built through container files so that other contributors would not need to set up the full language framework/toolchain whenever they need to contribute. Checkout the go sdk build steps as an example.

Updating the Notice files

1- Ensure that fossaComplianceNoticeId has been set in each SDK's config overrides. 2- Run make update-fossa-reports

Uploading the SDK

Once the SDK is ready, you need to:

Create a repo under the openfga github org. Call it: ${SDK_ID}-sdk
Add it to the generator's test and deploy actions
Add any necessary secrets to the generator's repo on github (and document them in the readme)

Publishing/Open Sourcing the SDK

Once the SDK is ready, you need to:

Setup Snyk, and ensure no security issues are present
Setup Fossa, and ensure no compliance issues are present
Request a review from the team

Note: Semgrep will be automatically enabled - there is nothing you need to do for that.

GitHub Action Secrets

Key	Comment
`FOSSA_API_KEY`	FOSSA API Key
`SNYK_TOKEN`	Snyk API Key

Contributing

Please review the Contributing Guidelines before sending a PR or opening an issue.

In addition, we ask that the SDKs:

be generated from the openapiv2 swagger document using the sdk-generator.
have roughly the same consistent interface for configuration, such as JS, GoLang, .NET, Python and Java SDKs.
support the same features with other existing SDKs, including: Retries, Error Handling, .
have a base set of functional tests.
have no tests that talk to an external service (external calls should be disallowed and mocked).
have building & publishing automated through GitHub actions.
be created and modified through pull requests to this sdk-generator repository instead of individual repositories. Most of the code will be in mustache files that will end up generating the resulting SDK for the appropriate language.

Author

OpenFGA

License

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

The template files in this repo are based on the original files from OpenAPI Generator.

openfga / sdk-generator

readme