doc/api/methods/credentials.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "credentials"
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/credentials@
  14
  15 Object type: @oss07@
  16
  17 Example UUID: @zzzzz-oss07-0123456789abcde@
  18
  19 h2. Resource
  20
  21 Stores a credential, such as a username/password or API token, for use by running containers to access an external resource on the user's behalf.
  22
  23 Each Credential offers the following attributes, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  24
  25 table(table table-bordered table-condensed).
  26 |_. Attribute|_. Type|_. Description|
  27 |name|string|Name for the credential, unique by owner.|
  28 |description|string|Free text description of this credential.|
  29 |credential_class|string|The type of credential stored in this record. See below for more information.|
  30 |scopes|array of string|(optional) One or more specific resources this credential applies to.|
  31 |external_id|string|The non-secret part of the credential.|
  32 |secret|string|The secret part of the credential that should kept hidden where possible.|
  33 |expires_at|timestamp|Date at which the @secret@ field is not longer valid and can no longer be accessed (and may be scrubbed from the database).  If @expires_at@ has past, any attempts to access the @secret@ endpoint (see below) also return an error.|
  34
  35 The @secret@ field can be set when the record is created or updated by users with at @can_write@ permission, however the value of @secret@ is not returned in the regular @get@ or @list@ API calls, and cannot be used in queries.
  36
  37 Credentials can be read using an Arvados token issued to a container running on behalf of a user who has @can_read@ permission to the credential, using the @secret@ API call (see below).  Calling the @secret@ API with a regular Arvados token (i.e. not associated with a running container) will return a permission denied error.
  38
  39 This design is intended to minimize accidental exposure of the secret material, but does not inherently protect it from users who have been given @can_read@ access, since it is necessary for code running on those user's behalf to access the secret in order to make use of it.
  40
  41 As of Arvados 3.2, all credentials are owned by the system user and the @name@ field must be unique on a given Arvados instance.  Credentials are shared using normal permission links.
  42
  43 h2. Credential classes
  44
  45 The @credential_class@ field is used to identify what kind of credential is stored and how to interpret the other fields of the record.
  46
  47 h3. aws_access_key
  48
  49 table(table table-bordered table-condensed).
  50 |_. Attribute|_. Description|
  51 |credential_class|String "aws_access_key"|
  52 |scopes|(optional, not yet implemented in Arvados 3.2) A list of S3 buckets (in the form "s3://bucketname") to which these credentials grant access.|
  53 |external_id|The value of "aws_access_key_id" from @~/.aws/credentials@|
  54 |secret|The value of "aws_secret_access_key" @~/.aws/credentials@|
  55
  56 h2. Methods
  57
  58 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  59
  60 Required arguments are displayed in %{background:#ccffcc}green%.
  61
  62 h3. create
  63
  64 Create a new Credential.
  65
  66 Arguments:
  67
  68 table(table table-bordered table-condensed).
  69 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  70 {background:#ccffcc}.|credential|object|Credential resource|request body||
  71
  72 h3. delete
  73
  74 Delete an existing Credential.
  75
  76 Arguments:
  77
  78 table(table table-bordered table-condensed).
  79 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  80 {background:#ccffcc}.|uuid|string|The UUID of the Credential in question.|path||
  81
  82 h3. get
  83
  84 Get a credential by UUID.  The @secret@ field is not returned in @get@ API calls.  To get the value of @secret@, use the @secret@ API call.
  85
  86 Arguments:
  87
  88 table(table table-bordered table-condensed).
  89 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  90 {background:#ccffcc}.|uuid|string|The UUID of the Credential in question.|path||
  91
  92 h3. list
  93
  94 List credentials.  The @secret@ field is not returned in @list@ API calls, and cannot be used in queries.  To get the value of @secret@, use the @secret@ API call.
  95
  96 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
  97
  98 h3. update
  99
 100 Update attributes of an existing credential.  May be used to update the value of @secret@.
 101
 102 Arguments:
 103
 104 table(table table-bordered table-condensed).
 105 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 106 {background:#ccffcc}.|uuid|string|The UUID of the Credential in question.|path||
 107 |credential|object||query||
 108
 109 h3. secret
 110
 111 Get the value of @secret@.  Returns a JSON object in the form @{"external_id": "...", "secret": "..."}@.
 112
 113 Only permitted when called with a Arvados token issued to a container running on behalf of a user who has @can_read@ permission to the credential.  Calling this API with a regular Arvados token (i.e. not associated with a running container) will return a permission denied error.
 114
 115 If @expires_at@ has passed, this endpoint will return an error.
 116
 117 Calls to the @secret@ API endpoint are logged as @event_type: secret_access@ in the audit log table.
 118
 119 Arguments:
 120
 121 table(table table-bordered table-condensed).
 122 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 123 {background:#ccffcc}.|uuid|string|The UUID of the Credential in question.|path||