Permission Modes

note

As of v1.0.5 zrok sharing now defaults to the closed permission mode. The --closed flag has been removed and has been replaced with a new --open flag for users who want to retain the open permission model. Otherwise, the closed permission mode works exactly the same.

Shares created in zrok v0.4.26 and newer now include a choice of permission mode.

Shares created with zrok v0.4.25 and older were created using what is now called the open permission mode. Whether public or private, these shares can be accessed by any user of the zrok service instance, as long as they know the share token of the share. Effectively shares with the open permission mode are accessible by any user of the zrok service instance.

zrok now supports a closed permission mode, which allows for more fine-grained control over which zrok users are allowed to privately access your shares using zrok access private.

zrok defaults to continuing to create shares with the open permission mode. This will likely change in a future release. We're leaving the default behavior in place to allow users a period of time to get comfortable with the new permission modes.

Creating a Share with Closed Permission Mode

Adding the --closed flag to the zrok share command will create shares using the closed permission mode:

$ zrok share private --headless --closed -b web .
[   0.066]    INFO main.(*sharePrivateCommand).run: allow other to access your share with the following command:
zrok access private 0vzwzodf0c7g

By default any environment owned by the account that created the share is allowed to access the new share. But a user trying to access the share from an environment owned by a different account will enounter the following error message:

$ zrok access private 0vzwzodf0c7g
[ERROR]: unable to access ([POST /access][401] accessUnauthorized)

The zrok share command includes an --access-grant flag, which allows you to specify additional zrok accounts that are allowed to access your shares:

$ zrok share private --headless --closed --access-grant anotheruser@test.com -b web .
[   0.062]    INFO main.(*sharePrivateCommand).run: allow other to access your share with the following command:
zrok access private y6h4at5xvn6o

And now anotheruser@test.com will be allowed to access the share:

$ zrok access private --headless y6h4at5xvn6o
[   0.049]    INFO main.(*accessPrivateCommand).run: allocated frontend 'VyvrJihAOEHD'
[   0.051]    INFO main.(*accessPrivateCommand).run: access the zrok share at the following endpoint: http://127.0.0.1:9191

Adding and Removing Access Grants for Existing Shares

If you've created a share (either reserved or ephemeral) and you forgot to include an access grant, or want to remove an access grant that was mistakenly added, you can use the zrok modify share command to make the adjustments:

Create a share:

$ zrok share private --headless --closed -b web .
[   0.064]    INFO main.(*sharePrivateCommand).run: allow other to access your share with the following command:
zrok access private s4czjylwk7wa

In another shell in the same environment you can execute:

$ zrok modify share s4czjylwk7wa --add-access-grant anotheruser@test.com
updated

And to remove the grant:

$ zrok modify share s4czjylwk7wa --remove-access-grant anotheruser@test.com
updated

Using Permission Modes with Reserved Names (v2.0)

In zrok v2.0, you can use permission modes with reserved names for persistent public shares:

# create a reserved name
$ zrok create name -n public myapp

# share with closed permission mode using the name
$ zrok share public localhost:8080 -n public:myapp --closed --access-grant friend@example.com

For persistent private shares in v2.0, use the --share-token flag:

# create a persistent private share with custom token and closed permissions
$ zrok share private localhost:8080 --share-token myapi --closed --access-grant colleague@example.com

You can modify access grants for shares using reserved names or custom share tokens:

# modify a share using a reserved name's current share token
$ zrok modify share <currentShareToken> --add-access-grant user@example.com

# or modify using the custom share token
$ zrok modify share myapi --add-access-grant user@example.com

Limitations

As of v0.4.26 there is currently no way to list the current access grants. This will be addressed shortly in a subsequent update.