openfga/cli

Sponsored OSS

By Cloud Native Computing Foundation

Updated 20 days ago

A cross-platform CLI to interact with an OpenFGA server

Image
Security
Developer Tools

50K+

OpenFGA CLI

A cross-platform CLI to interact with an OpenFGA server

Go ReferenceReleaseLicenseFOSSA StatusJoin our communityTwitter

Table of Contents

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/Okta based on Okta 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

Installation

Brew
brew install openfga/tap/fga
Linux (deb, rpm and apk) packages

Download the .deb, .rpm or .apk packages from the releases page.

Debian:

sudo apt install ./fga_<version>_linux_<arch>.deb

Fedora:

sudo dnf install ./fga_<version>_linux_<arch>.rpm

Alpine Linux:

sudo apk add --allow-untrusted ./fga_<version>_linux_<arch>.apk
Windows

via Scoop

scoop install openfga
Docker
docker pull openfga/cli; docker run -it openfga/cli
Go
go install github.com/openfga/cli/cmd/fga@latest
Manually

Download the pre-compiled binaries from the releases page.

Building from Source

Make sure you have Go 1.20 or later installed. See the Go downloads page.

  1. Clone the repo to a local directory, and navigate to that directory:

    git clone https://github.com/openfga/cli.git && cd cli
    
  2. Then use the build command:

    go build -o ./dist/fga ./cmd/fga/main.go
    

    or if you have make installed, just run:

    make build
    
  3. Run the OpenFGA CLI with:

    ./dist/fga
    

Usage

Configuration

For any command that interacts with an OpenFGA server, these configuration values can be passed (where applicable)

NameFlagCLI~/.fga.yaml
API Url--api-urlFGA_API_URLapi-url
Shared Secret--api-tokenFGA_API_TOKENapi-token
Client ID--client-idFGA_CLIENT_IDclient-id
Client Secret--client-secretFGA_CLIENT_SECRETclient-secret
Scopes--api-scopesFGA_API_SCOPESapi-scopes
Token Issuer--api-token-issuerFGA_API_TOKEN_ISSUERapi-token-issuer
Token Audience--api-audienceFGA_API_AUDIENCEapi-audience
Store ID--store-idFGA_STORE_IDstore-id
Authorization Model ID--model-idFGA_MODEL_IDmodel-id

If you are authenticating with a shared secret, you should specify the API Token value. If you are authenticating using OAuth, you should specify the Client ID, Client Secret, API Audience and Token Issuer. For example:

# Note: This example is for Okta FGA
api-url: https://api.us1.fga.dev
client-id: 4Zb..UYjaHreLKOJuU8
client-secret: J3...2pBwiauD
api-audience: https://api.us1.fga.dev/
api-token-issuer: auth.fga.dev
store-id: 01H0H015178Y2V4CX10C2KGHF4
Commands

Stores

Descriptioncommandparametersexample
Create a Storecreate--namefga store create --name="FGA Demo Store"
Import a Storeimport--filefga store import --file store.fga.yaml
Export a Storeexport--store-idfga store export --store-id=01H0H015178Y2V4CX10C2KGHF4
List Storeslistfga store list
Get a Storeget--store-idfga store get --store-id=01H0H015178Y2V4CX10C2KGHF4
Delete a Storedelete--store-idfga store delete --store-id=01H0H015178Y2V4CX10C2KGHF4
Create Store

Command

fga store create

Parameters

  • --name: Name of the store to be created. If the model parameter is specified, the model file name will be used as the default store name.
  • --model: File with the authorization model. Can be in JSON, OpenFGA format, or fga.mod file (optional).
  • --format : Authorization model input format. Can be "fga", "json", or "modular" (optional, defaults to the model file extension if present).

Example

fga store create --name "FGA Demo Store"

Response

{
    "id": "01H0H015178Y2V4CX10C2KGHF4",
    "name": "FGA Demo Store",
    "created_at": "2023-05-19T16:10:07.637585677Z",
    "updated_at": "2023-05-19T16:10:07.637585677Z"
}

fga store create --model Model.fga

Response

{
  "store": {
    "id":"01H6H9CNQRP2TVCFR7899XGNY8",
    "name":"Model",
    "created_at":"2023-07-29T16:58:28.984402Z",
    "updated_at":"2023-07-29T16:58:28.984402Z"
  },
  "model": {
    "authorization_model_id":"01H6H9CNQV36Y9WS1RJGRN8D06"
  }
}

To automatically set the created store id as an environment variable that will then be used by the CLI, you can use the following command:

export FGA_STORE_ID=$(fga store create --model model.fga | jq -r .store.id)
Import Store

Command

fga store import

Parameters

  • --file: File containing the store.
  • --store-id: Specifies the store id to import into
  • --max-tuples-per-write: Max tuples to send in a single write (optional, default=1)
  • --max-parallel-requests: Max requests to send in parallel (optional, default=4)

Example

fga store import --file model.fga.yaml

Response

{}
Export Store

Command

fga store export

Parameters

  • --store-id: Specifies the store to export
  • --output-file: The file to output the store to (optional, writes to the terminal if omitted)
  • --model-id: Specifies the model to export (optional, exports the latest model if omitted)
  • --max-tuples: Specifies the max number of tuples to include in the output (option, defaults to 100)

Example

fga store export --store-id=01H0H015178Y2V4CX10C2KGHF4

Response

name: Test
model: |+
    model
      schema 1.1

    type user

    type group
      relations
        define member: [user]
        define moderator: [user]

tuples:
    - user: user:1
      relation: member
      object: group:admins
    - user: user:1
      relation: member
      object: group:employees
    - user: user:2
      relation: member
      object: group:employees
    - user: user:1
      relation: moderator
      object: group:employees
tests:
    - name: Tests
      check:
        - user: user:1
          object: group:admins
          assertions:
            member: true
        - user: user:2
          object: group:admins
          assertions:
            member: false
        - user: user:1
          object: group:employees
          assertions:
            member: true
            moderator: true
        - user: user:2
          object: group:employees
          assertions:
            member: true
            moderator: false

If using output-file, the response will be written to the specified file on disk. If the desired file already exists, you will be prompted to overwrite the file.

List Stores

Command

fga store list

Parameters

  • --max-pages: Max number of pages to retrieve (default: 20)

Example

fga store list

Response

{
  "stores": [{
    "id": "..",
    "name": "..",
    "created_at": "",
    "updated_at": "",
    "deleted_at": ""
  }, { .. }]
}
Get Store

Command

fga store get

Parameters

  • --store-id: Specifies the store id to get

Example

fga store get --store-id=01H0H015178Y2V4CX10C2KGHF4

Response

{
    "id": "01H0H015178Y2V4CX10C2KGHF4",
    "name": "FGA Demo Store",
    "created_at": "2023-05-19T16:10:07.637585677Z",
    "updated_at": "2023-05-19T16:10:07.637585677Z"
}
Delete Store

Command

fga store delete

Parameters

  • --store-id: Specifies the store id to delete

Example

fga store delete --store-id=01H0H015178Y2V4CX10C2KGHF4

Response

{}

Authorization Models

  • model
Descriptioncommandparametersexample
Read Authorization Modelslist--store-idfga model list --store-id=01H0H015178Y2V4CX10C2KGHF4
Write Authorization Model write--store-id, --filefga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file model.fga
Read a Single Authorization Modelget--store-id, --model-idfga model get --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1
Validate an Authorization Modelvalidate--file, --formatfga model validate --file model.fga
Run Tests on an Authorization Modeltest--tests, --verbosefga model test --tests tests.fga.yaml
Transform an Authorization Modeltransform--file, --input-formatfga model transform --file model.json
Read Authorization Models

List all authorization models for a store, in descending order by creation date. The first model in the list is the latest one.

Command

fga model list

Parameters

  • --store-id: Specifies the store id
  • --max-pages: Max number of pages to retrieve (default: 20)
  • --field: Fields to display. Choices are: id, created_at and model. Default are id, created_at.

Example

fga model list --store-id=01H0H015178Y2V4CX10C2KGHF4

Response

{
  "authorization_models": [
    {
      "id":"01H6H9XH1G5Q6DK6PFMGDZNH9S",
      "created_at":"2023-07-29T17:07:41Z"
    },
    {
      "id":"01H6H9PPR6C3P45R75X55ZFP46",
      "created_at":"2023-07-29T17:03:57Z"
    }
  ]
}
Write Authorization Model

Command

fga model write

Parameters

  • --store-id: Specifies the store id
  • --file: File containing the authorization model.
  • --format: Authorization model input format. Can be "fga", "json", or "modular". Defaults to the file extension if provided (optional)

Example

  • fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file=model.fga
  • fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file=fga.mod
  • fga model write --store-id=01H0H015178Y2V4CX10C2KGHF4 '{"type_definitions": [ { "type": "user" }, { "type": "document", "relations": { "can_view": { "this": {} } }, "metadata": { "relations": { "can_view": { "directly_related_user_types": [ { "type": "user" } ] }}}} ], "schema_version": "1.1"}' --format json

Response

{
  "authorization_model_id":"01GXSA8YR785C4FYS3C0RTG7B1"
}
Read a Single Authorization Model

Command

fga model get

Parameters

  • --store-id: Specifies the store id
  • --model-id: Specifies the model id
  • --format: Authorization model output format. Can be "fga" or "json" (default fga).
  • --field: Fields to display, choices are: id, created_at and model. Default is model.

Example

fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1

Response

model
  schema 1.1

type user

type document
  relations
    define can_view: [user]
Read the Latest Authorization Model

If model-id is not specified when using the get command, the latest authorization model will be returned.

Command

fga model get

Parameters

  • --store-id: Specifies the store id

Example

fga model get --store-id=01H0H015178Y2V4CX10C2KGHF4

Response

model
  schema 1.1

type user

type document
  relations
    define can_view: [user]
Validate an Authorization Model

Command

fga model validate

Parameters

  • --file: File containing the authorization model.
  • --format: Authorization model input format. Can be "fga", "json", or "modular". Defaults to the file extension if provided (optional)

Example

fga model validate --file model.json

JSON Response

  • Valid model with an ID
{"id":"01GPGWB8R33HWXS3KK6YG4ETGH","created_at":"2023-01-11T16:59:22Z","is_valid":true}
  • Valid model without an ID
{"is_valid":true}
  • Invalid model with an ID
{"id":"01GPGTVEH5NYTQ19RYFQKE0Q4Z","created_at":"2023-01-11T16:33:15Z","is_valid":false,"error":"invalid schema version"}
  • Invalid model without an ID
{"is_valid":false,"error":"the relation type 'employee' on 'member' in object type 'group' is not valid"}
Run Tests on an Authorization Model

Given a model, and a set of tests (tuples, check and list objects requests, and expected results) report back on any tests that do not return the same results as expected.

Command

fga model test

Parameters

  • --tests: Name of the tests file. Must be in yaml format (see below)
  • --verbose: Outputs the results in JSON

If a model is provided, the test will run in a built-in OpenFGA instance (you do not need a separate server). Otherwise, the test will be run against the configured store of your OpenFGA instance. When running against a remote instance, the tuples will be sent as contextual tuples, and will have to abide by the OpenFGA server limits (20 contextual tuples per request).

The tests file should be in yaml and have the following format:

---
name: Store Name # store name, optional
# model_file: ./model.fga # a global model that would apply to all tests, optional
# model can be used instead of model_file, optional
model: |
  model
    schema 1.1
  type user
  type folder
    relations
      define owner: [user] 
      define parent: [folder]
      define can_view: owner or can_view from parent
      define can_write: owner or can_write from parent
      define can_share: owner

# tuple_file: ./tuples.yaml # global tuples that would apply to all tests, optional
tuples: # global tuples that would apply to all tests, optional
  - user: folder:1
    relation: parent
    object: folder:2
tests: # required
  - name: test-1
    description: testing that the model works # optional
    # tuple_file: ./tuples.json # tuples that would apply per test
    tuples:
      - user: user:anne
        relation: owner
        object: folder:1
    check: # a set of checks to run
      - user: user:anne
        object: folder:1
        assertions:
          # a set of expected results for each relation
          can_view: true
          can_write: true
          can_share: false
    list_objects: # a set of list objects to run
      - user: user:anne
        type: folder
        assertions:
          # a set of expected results for each relation
          can_view:
            - folder:1
            - folder:2
          can_write:
            - folder:1
            - folder:2
  - name: test-2
    description: another test
    tuples:
      - user: user:anne
        relation: owner
        object: folder:1
    check:
      - user: user:anne
        object: folder:1
        assertions:
          # a set of expected results for each relation
          can_view: true
    list_objects:
      - user: user:anne
        type: folder
        assertions:
          # a set of expected results for each relation
          can_view:
            - folder:1
            - folder:2

Example

fga model test --tests tests.fga.yaml

For more examples of .fga.yaml files, check the sample-stores repository/

Response

(FAILING) test-1: Checks (2/3 passing) | ListObjects (2/2 passing)
ⅹ Check(user=user:anne,relation=can_share,object=folder:1): expected=false, got=true
---
# Test Summary #
Tests 1/2 passing
Checks 3/4 passing
ListObjects 3/3 passing
Transform an Authorization Model

Command

fga model transform

Parameters

  • --file: File containing the authorization model
  • --input-format: Authorization model input format. Can be "fga", "json", or "modular". Defaults to the file extension if provided (optional)
  • --output-format: Authorization model output format. Can be "fga" or "json". If not specified, it will default to fga if the input format is json and to json otherwise (optional)

Example

fga model transform --file model.json

Response

model
  schema 1.1

type user

type document
  relations
    define can_view: [user]

Relationship Tuples

  • tuple
Descriptioncommandparametersexample
Write Relationship Tupleswrite--store-id, --model-idfga tuple write user:anne can_view document:roadmap --store-id=01H0H015178Y2V4CX10C2KGHF4
Delete Relationship Tuplesdelete--store-id, --model-idfga tuple delete user:anne can_view document:roadmap --store-id=01H0H015178Y2V4CX10C2KGHF4
Read Relationship Tuplesread--store-id, --model-idfga tuple read --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1
Read Relationship Tuple Changes (Watch)changes--store-id, --type, --start-time, --continuation-token,fga tuple changes --store-id=01H0H015178Y2V4CX10C2KGHF4 --type=document --start-time=2022-01-01T00:00:00Z --continuation-token=M3w=
Import Relationship Tuplesimport--store-id, --model-id, --filefga tuple import --store-id=01H0H015178Y2V4CX10C2KGHF4 --model-id=01GXSA8YR785C4FYS3C0RTG7B1 --file tuples.json
Write Relationship Tuples

Command

fga tuple write --store-id=

Parameters

  • <user>: User
  • <relation>: Relation
  • <object>: Object
  • --condition-name: Condition name (optional)
  • --condition-context: Condition context (optional)
  • --store-id: Specifies the store id
  • --model-id: Specifies the model id to target (optional)
  • --file: Specifies the file name, json, yaml and csv files are supported
  • --max-tuples-per-write: Max tuples to send in a single write (optional, default=1)
  • --max-parallel-requests: Max requests to send in parallel (optional, default=4)
  • --hide-imported-tuples: When importing from a file, do not output successfully imported tuples in the command output (optional, default=false)

Example (with arguments)

  • fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap
  • fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 user:anne can_view document:roadmap --condition-name inOffice --condition-context '{"office_ip":"10.0.1.10"}'

Response

{
  "successful": [
    {
      "object":"document:roadmap",
      "relation":"writer",
      "user":"user:annie"
    }
  ],
}

Example (with file)

fga tuple write --store-id=01H0H015178Y2V4CX10C2KGHF4 --file tuples.json

If using a csv file, the format should be:

user_type,user_id,user_relation,relation,object_type,object_id,condition_name,condition_context
folder,product,,parent,folder,product-2021,inOfficeIP,"{""ip_addr"":""10.0.0.1""}"

If using a yaml file, the format should be:

- user: folder:5
  relation: parent
  object: folder:product-2021
- user: folder:product-2021
  relation: parent
  object: folder:product-2021Q1

If using a json file, the format should be:

[
  {
    "user": "user:anne",
    "relation": "owner",
    "object": "folder:product"
  },
  {
    "user": "folder:product",
    "relation": "parent",
    "object": "folder:product

Docker Pull Command

docker pull openfga/cli