jpadilla / sdk-generator

OpenFGA Client SDK Generator

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

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 [e-mail]:openfga/sdk-generator.git

2. Clone existing SDKs into the clients directory

git clone [e-mail]:openfga/go-sdk.git clients/fga-go-sdk
git clone [e-mail]:openfga/js-sdk.git clients/fga-js-sdk
git clone [e-mail]:openfga/dotnet-sdk.git clients/fga-dotnet-sdk
git clone [e-mail]:openfga/python-sdk.git clients/fga-python-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 build
   • template/ directory'
     • LICENSE: License file from legal. Note: All SDKs must be MIT Licensed.
     • .github/workflows/tests.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
     • 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}}

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
KNOWN_HOSTS
FOSSA_API_KEY	FOSSA API Key
SNYK_TOKEN	Snyk API Key
GO_SDK_GITHUB_ORG_ID	The GitHub org for the SDK
GO_SDK_GITHUB_REPO_ID	The GitHub repo id for the SDK
GO_SDK_SSH_KEY	The SSH private deploy key for the SDK
JS_SDK_GITHUB_ORG_ID	The GitHub org for the SDK
JS_SDK_GITHUB_REPO_ID	The GitHub repo id for the SDK
JS_SDK_SSH_KEY	The SSH private deploy key for the SDK
DOTNET_SDK_GITHUB_ORG_ID	The GitHub org for the SDK
DOTNET_SDK_GITHUB_REPO_ID	The GitHub repo id for the SDK
DOTNET_SDK_SSH_KEY	The SSH private deploy key for the SDK
PYTHON_SDK_GITHUB_ORG_ID	The GitHub org for the SDK
PYTHON_SDK_GITHUB_REPO_ID	The GitHub repo id for the SDK
PYTHON_SDK_SSH_KEY	The SSH private deploy key for the SDK

The following keys are also available but should be considered deprecated. Automated release is disabled due to the complexity of generating relevant commit messages when using a generator.

Key	Comment
GIT_USER_EMAIL	Email of the user in the git commits
GIT_USER_NAME	Name of the user in the git commits
GO_SDK_DRY_RUN	Whether to show git diff and exit without pushing changes for the SDK
GO_SDK_TAGGING_DISABLE	Whether to disable tagging and publishing for the SDK
JS_SDK_DRY_RUN	Whether to show git diff and exit without pushing changes for the SDK
JS_SDK_TAGGING_DISABLE	Whether to disable tagging and publishing for the SDK
NPM_EMAIL	The email of the user pushing to npm
NPM_TOKEN	The token of the user pushing to npm
DOTNET_SDK_DRY_RUN	Whether to show git diff and exit without pushing changes for the SDK
DOTNET_SDK_TAGGING_DISABLE	Whether to disable tagging and publishing for the SDK

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 and Python SDKs.

• support the same features with other existing SDKs.

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