README.md

OpenFGA Client SDK Generator

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

Table of Contents

• OpenFGA Client SDK Generator
  • Table of Contents
  • About
  • Resources
  • Currently Supported SDKs
  • Getting Started
    • Requirements
    • Usage
    • Adding a new SDK
      • Using the setup script
      • Manually
    • Uploading the SDK
    • Publishing/Open Sourcing the SDK
    • GitHub Action Secrets
  • Contributing
  • Author
  • License

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)

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

1. Git
2. Docker
3. Make (Optional, but makes things much easier)
4. curl
5. Bash
6. sed

Usage

1. Clone this repo:

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

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

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

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

Manually

1. 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
2. Update the Makefile.
   1. 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 ...

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

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

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

1. Setup Snyk, and ensure no security issues are present
2. Setup Fossa, and ensure no compliance issues are present
3. 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.