doc/admin/scoped-tokens.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: admin
   4 title: Securing API access with scoped tokens
   5 ...
   6
   7 By default, Arvados API tokens grant unlimited access to a user account, and admin account tokens have unlimited access to the whole system.  If you want to grant restricted access to a user account, you can create a "scoped token" which is an Arvados API token which is limited to accessing specific APIs.
   8
   9 h2. Defining scopes
  10
  11 A "scope" consists of a HTTP method and API path.  A token can have multiple scopes.  Token scopes act as a whitelist, and the API server checks the HTTP method and the API path of every request against the scopes of the request token.
  12
  13 These examples use @/arvados/v1/collections@, but can be applied to any endpoint.  Consult the "API documentation":{{site.baseurl}}/api for details.
  14
  15 The scope @["GET", "/arvados/v1/collections"]@ will allow only GET or HEAD requests for the list of collections.  Any other HTTP method or path (including requests for a specific collection record, eg a request with path @/arvados/v1/collections/zzzzz-4zz18-0123456789abcde@) will return a permission error.
  16
  17 A trailing slash in a scope is signficant.  The scope @["GET", "/arvados/v1/collections/"]@ will allow only GET or HEAD requests *underneath* @collections@, so the request for an individual record path @/arvados/v1/collections/zzzzz-4zz18-0123456789abcde@) is allowed but a request to list collections will be denied.
  18
  19 The scope can include an object uuid.  The scope @["GET", "/arvados/v1/collections/zzzzz-4zz18-0123456789abcde"]@ only permits requests for the record @zzzzz-4zz18-0123456789abcde@.
  20
  21 Since a token can have multiple scopes, use @[["GET", "/arvados/v1/collections"], ["GET", "/arvados/v1/collections/"]]@ to allow both listing collections and fetching individual collection records.
  22
  23 Object create calls use the `POST` method.  A scope of @["POST", "/arvados/v1/collections"]@ will allow creating collections, but not reading, listing or updating them (or accessing anything else).
  24
  25 Object update calls use the `PATCH` method.  A scope of @["POST", "/arvados/v1/collections/"]@ will allow updating collections, but not listing or creating them.  (Note: while GET requests are denied an object can be read indirectly by using an empty PATCH which will return the unmodified object as the result).
  26
  27 h2. Creating a scoped token
  28
  29 A scoped token can be created at the command line:
  30
  31 <pre>
  32 $ arv api_client_authorization create --api-client-authorization '{"scopes": [["GET", "/arvados/v1/collections"], ["GET", "/arvados/v1/collections/"]]}'
  33 {
  34  "href":"/api_client_authorizations/x1u39-gj3su-bizbsw0mx5pju3w",
  35  "kind":"arvados#apiClientAuthorization",
  36  "etag":"9yk144t0v6cvyp0342exoh2vq",
  37  "uuid":"x1u39-gj3su-bizbsw0mx5pju3w",
  38  "owner_uuid":"x1u39-tpzed-fr97h9t4m5jffxs",
  39  "created_at":"2020-03-12T20:36:12.517375422Z",
  40  "modified_by_client_uuid":null,
  41  "modified_by_user_uuid":null,
  42  "modified_at":null,
  43  "user_id":3,
  44  "api_client_id":7,
  45  "api_token":"5a74htnoqwkhtfo2upekpfbsg04hv7cy5v4nowf7dtpxer086m",
  46  "created_by_ip_address":null,
  47  "default_owner_uuid":null,
  48  "expires_at":null,
  49  "last_used_at":null,
  50  "last_used_by_ip_address":null,
  51  "scopes":[
  52   [
  53    "GET",
  54    "/arvados/v1/collections"
  55   ],
  56   [
  57    "GET",
  58    "/arvados/v1/collections/"
  59   ]
  60  ]
  61 }
  62 </pre>
  63
  64 The response will include @api_token@ field which is the newly issued secret token.  It can be passed directly to the API server that issued it, or can be used to construct a @v2@ token.  A @v2@ format token is required if the token will be used to access other clusters in an Arvados federation.  An Arvados @v2@ format token consists of three fields separate by slashes: the prefix @v2@, followed by the token uuid, followed by the token secret.  For example: @v2/x1u39-gj3su-bizbsw0mx5pju3w/5a74htnoqwkhtfo2upekpfbsg04hv7cy5v4nowf7dtpxer086m@.