How do you Revoke an Access Grant using Uplink CLI with Examples

Developer Discussions FAQ
1

I’m attempting to delete an access grant I created in the satellite UI via the Uplink CLI in the ubuntu command line and I keep running into the error, “Error: uplink: permission denied (metaclient: Unauthorized attempt to revoke macaroon)” when I run the command

uplink revoke <enter access grant key in config.yaml>

I have inspected the config.yaml file located ~/.local/share/storj/uplink and I can confirm I’m entering the correct value.

Examples in the docs here are limited. I am aware I can delete the access grant from the satellite UI as well as from the config.yaml. My question is how is uplink revoke supposed to work? Please provide examples.

2

Hello @stouser1 ,
Welcome to the forum!

The uplink revoke is usually used when you do not remove the root access grant from the satellite UI and want to revoke a derived access grant (for example - you gave a link to some object and now change your mind).

If you did remove the root access grant from the satellite UI - all derived access grants were revoked automatically.
To remove the access from the uplink you can either replace it with a new access grant, or remove the deleted access from the config.yaml file (you can see a path to the config file by uplink setup --help command in the tip for the --config-dir option). The cardinal way is to remove this file completely with all access grants altogether.

3

Are you saying then you cannot remove the root access grant using the uplink revoke command?
How do I delete ALL access grants from the satellite UI and config.yaml at the same time by using the uplink cli? Is this possible?
Also, why am I getting the error message when I attempt to revoke access? I followed the usage examples in the doc. Can you provide some better working examples of how to use the uplink revoke command with named access grant or serialized access grant? For example; uplink revoke access_here [flags], what does access_here refer to?

4

Yes. You can revoke only derived access grants from the CLI. The root API key or access grant can be only removed and this should be done in the satellite UI. This will immediately invalidate all derived access grants.

No, it’s not possible and not considered as far as I know. But you can request this feature in the DCS feature requests - voting - Storj Community Forum (official) or Issues · storj/storj · GitHub

Because you are trying to revoke a root access grant. As I said - it’s not possible via CLI.
You need to have a derived access grant to revoke it.
For example

$ uplink share --readonly=false
...
Sharing access to satellite 12tRQrMTWUWwzwGh18i7Fqs67kmdhH9t6aToeiwbo5mfS2rUmo@us2.storj.io:7777
=========== ACCESS RESTRICTIONS ==========================================================
Download  : Allowed
Upload    : Allowed
Lists     : Allowed
Deletes   : Allowed
NotBefore : No restriction
NotAfter  : No restriction
Paths     : WARNING! The entire project is shared!
=========== SERIALIZED ACCESS WITH THE ABOVE RESTRICTIONS TO SHARE WITH OTHERS ===========
Access    : 1Sfrjgorjgmorgiorg...

NEVER DO THIS ^^^^, this is only for test purpose!
You will get an access grant with full permissions, then you can revoke it by

$ uplink revoke 1Sfrjgorjgmorgiorg...
=========== SUCCESSFULLY REVOKED =========================================================
NOTE: It may take the satellite several minutes to process the revocation request,
      depending on its caching policies.

No one command with the revoked access grant will work:

$ uplink --access 1Sfrjgorjgmorgiorg... ls
Error: uplink: uplink: permission denied (bucket: metaclient: Unauthorized API credentials)

It’s a placeholder for a serialized access grant, the 1Sfrjgorjgmorgiorg... in my example.
The revoke of the named access grant is not possible, I created a bug a while ago, it should be solved in [Tech Preview] Uplinkng (new enhanced uplink cli) and then merged to the uplink, when it matures.
But you can revoke the named access grant if you provide not the name but the access grant itself (you can take it from the config file, see uplink setup --help for tooltip --config-dir)

6

Thanks for the clarification! How would I distinguish between a root access grant and derived access grant in the satellite UI or config.yaml (besides the generic Web file browser API key access grant that’s automatically created in the satellite UI)?

I’m assuming there are only two types of access grant formats: named and serialized, correct?

Also, is there a way to password protect objects / files shared via url?

7

In the satellite UI you can have only root access grants/API keys.
In the CLI it’s not so obvious, because you can import derived access grant.
However, you can use the uplink access inspect <access grant> to see - is it has a root key or not.

$ uplink access inspect
{
  "satellite_addr": "12tRQrMTWUWwzwGh18i7Fqs67kmdhH9t6aToeiwbo5mfS2rUmo@us2.storj.io:7777",
  "encryption_access": {
    "default_key": "***",
    "default_path_cipher": "ENC_AESGCM"
  },
  "api_key": "1d**",
  "macaroon": {
    "head": "***",
    "caveats": [
      {
        "nonce": "1***=="
      }
    ],
    "tail": "***"
  }
}

$ uplink share
Sharing access to satellite 12tRQrMTWUWwzwGh18i7Fqs67kmdhH9t6aToeiwbo5mfS2rUmo@us2.storj.io:7777
=========== ACCESS RESTRICTIONS ==========================================================
Download  : Allowed
Upload    : Disallowed
Lists     : Allowed
Deletes   : Disallowed
NotBefore : No restriction
NotAfter  : No restriction
Paths     : WARNING! The entire project is shared!
=========== SERIALIZED ACCESS WITH THE ABOVE RESTRICTIONS TO SHARE WITH OTHERS ===========
Access    : 1Dw***

$ uplink access inspect 1Dw***
{
  "satellite_addr": "12tRQrMTWUWwzwGh18i7Fqs67kmdhH9t6aToeiwbo5mfS2rUmo@us2.storj.io:7777",
  "encryption_access": {
    "default_key": "***",
    "default_path_cipher": "ENC_AESGCM"
  },
  "api_key": "12***",
  "macaroon": {
    "head": "***",
    "caveats": [
      {
        "nonce": "1***=="
      },
      {
        "disallow_writes": true,
        "disallow_deletes": true,
        "nonce": "2***"
      }
    ],
    "tail": "***"
  }
}

As you can see, in the root access there is only one nonce, in the derived - two.

This access grant created when you use an Objects browser.

In regarding operations in uplink CLI - yes. But from the architecture point of view - two: the API key - it’s an access grant without attached encryption key and satellite, but possible with caveats, and [serialized] access grant, contained API key, satellite URL and port with SatelliteID, encryption key and caveats.
See Understanding Key Constructs in Storj Architecture - Storj Docs

8

How are derived access grants created then?

Other than adjusting the permissions or setting an expiration date, is there a way in the satellite UI to password protect download links of files you share from your bucket?

9

with uplink share and caveats, see share - Storj Docs

Directly - no. If you share from the Objects browser, you will have a shorted URL with linkshare service, which allows a read-only access to anyone who have this link.
However, if you would like to give a password-restricted access, then perhaps it’s better to archive the content with the password and share link to this object. To have an access someone should have a link and password.

The other way is to write your own site or application to implement a such feature with provided SDKs - Storj Docs and Storj - Third Party · GitHub

1 Like
10

Thanks a bunch Alexey! Appreciate the clarification.

2 Likes