datalad.api.credentials
- datalad.api.credentials(action='query', spec=None, *, name=None, prompt=None, dataset=None)
Credential management and query
This command enables inspection and manipulation of credentials used throughout DataLad.
The command provides four basic actions:
QUERY
When executed without any property specification, all known credentials with all their properties will be yielded. Please note that this may not include credentials that only comprise of a secret and no other properties, or legacy credentials for which no trace in the configuration can be found. Therefore, the query results are not guaranteed to contain all credentials ever configured by DataLad.
When additional property/value pairs are specified, only credentials that have matching values for all given properties will be reported. This can be used, for example, to discover all suitable credentials for a specific "realm", if credentials were annotated with such information.
SET
This is the companion to 'get', and can be used to store properties and secret of a credential. Importantly, and in contrast to a 'get' operation, given properties with no values indicate a removal request. Any matching properties on record will be removed. If a credential is to be stored for which no secret is on record yet, an interactive session will prompt a user for a manual secret entry.
Only changed properties will be contained in the result record.
The appearance of the interactive secret entry can be configured with the two settings datalad.credentials.repeat-secret-entry and datalad.credentials.hidden-secret-entry.
REMOVE
This action will remove any secret and properties associated with a credential identified by its name.
GET (plumbing operation)
This is a read-only action that will never store (updates of) credential properties or secrets. Given properties will amend/overwrite those already on record. When properties with no value are given, and also no value for the respective properties is on record yet, their value will be requested interactively, if a
prompt
text was provided too. This can be used to ensure a complete credential record, comprising any number of properties.Details on credentials
A credential comprises any number of properties, plus exactly one secret. There are no constraints on the format or property values or the secret, as long as they are encoded as a string.
Credential properties are normally stored as configuration settings in a user's configuration ('global' scope) using the naming scheme:
datalad.credential.<name>.<property>
Therefore both credential name and credential property name must be syntax-compliant with Git configuration items. For property names this means only alphanumeric characters and dashes. For credential names virtually no naming restrictions exist (only null-byte and newline are forbidden). However, when naming credentials it is recommended to use simple names in order to enable convenient one-off credential overrides by specifying DataLad configuration items via their environment variable counterparts (see the documentation of the
configuration
command for details. In short, avoid underscores and special characters other than '.' and '-'.While there are no constraints on the number and nature of credential properties, a few particular properties are recognized on used for particular purposes:
'secret': always refers to the single secret of a credential
'type': identifies the type of a credential. With each standard type, a list of mandatory properties is associated (see below)
'last-used': is an ISO 8601 format time stamp that indicated the last (successful) usage of a credential
Standard credential types and properties
The following standard credential types are recognized, and their mandatory field with their standard names will be automatically included in a 'get' report.
'user_password': with properties 'user', and the password as secret
'token': only comprising the token as secret
'aws-s3': with properties 'key-id', 'session', 'expiration', and the secret_id as the credential secret
Legacy support
DataLad credentials not configured via this command may not be fully discoverable (i.e., including all their properties). Discovery of such legacy credentials can be assisted by specifying a dedicated 'type' property.
Examples
Report all discoverable credentials:
> credentials()
Set a new credential mycred & input its secret interactively:
> credentials('set', name='mycred')
Remove a credential's type property:
> credentials('set', name='mycred', spec={'type': None})
Get all information on a specific credential in a structured record:
> credentials('get', name='mycred')
Upgrade a legacy credential by annotating it with a 'type' property:
> credentials('set', name='legacycred', spec={'type': 'user_password')
Set a new credential of type user_password, with a given user property, and input its secret interactively:
> credentials('set', name='mycred', spec={'type': 'user_password', 'user': '<username>'})
Obtain a (possibly yet undefined) credential with a minimum set of properties. All missing properties and secret will be prompted for, no information will be stored! This is mostly useful for ensuring availability of an appropriate credential in an application context:
> credentials('get', prompt='Can I haz info plz?', name='newcred', spec={'newproperty': None})
- Parameters:
action -- which action to perform. [Default: 'query']
spec -- specification of credential properties. Properties are given as name/value pairs. Properties with a None value indicate a property to be deleted (action 'set'), or a property to be entered interactively, when no value is set yet, and a prompt text is given (action 'get'). All property names are case-insensitive, must start with a letter or a digit, and may only contain '-' apart from these characters. Property specifications should be given a as dictionary, e.g., spec={'type': 'user_password'}. However, a CLI-like list of string arguments is also supported, e.g., spec=['type=user_password']. [Default: None]
name -- name of a credential to set, get, or remove. [Default: None]
prompt -- message to display when entry of missing credential properties is required for action 'get'. This can be used to present information on the nature of a credential and for instructions on how to obtain a credential. [Default: None]
dataset -- specify a dataset whose configuration to inspect rather than the global (user) settings. [Default: None]
on_failure ({'ignore', 'continue', 'stop'}, optional) -- behavior to perform on failure: 'ignore' any failure is reported, but does not cause an exception; 'continue' if any failure occurs an exception will be raised at the end, but processing other actions will continue for as long as possible; 'stop': processing will stop on first failure and an exception is raised. A failure is any result with status 'impossible' or 'error'. Raised exception is an IncompleteResultsError that carries the result dictionaries of the failures in its failed attribute. [Default: 'continue']
result_filter (callable or None, optional) -- if given, each to-be-returned status dictionary is passed to this callable, and is only returned if the callable's return value does not evaluate to False or a ValueError exception is raised. If the given callable supports **kwargs it will additionally be passed the keyword arguments of the original API call. [Default: None]
result_renderer -- select rendering mode command results. 'tailored' enables a command- specific rendering style that is typically tailored to human consumption, if there is one for a specific command, or otherwise falls back on the the 'generic' result renderer; 'generic' renders each result in one line with key info like action, status, path, and an optional message); 'json' a complete JSON line serialization of the full result record; 'json_pp' like 'json', but pretty-printed spanning multiple lines; 'disabled' turns off result rendering entirely; '<template>' reports any value(s) of any result properties in any format indicated by the template (e.g. '{path}', compare with JSON output for all key-value choices). The template syntax follows the Python "format() language". It is possible to report individual dictionary values, e.g. '{metadata[name]}'. If a 2nd-level key contains a colon, e.g. 'music:Genre', ':' must be substituted by '#' in the template, like so: '{metadata[music#Genre]}'. [Default: 'tailored']
result_xfm ({'datasets', 'successdatasets-or-none', 'paths', 'relpaths', 'metadata'} or callable or None, optional) -- if given, each to-be-returned result status dictionary is passed to this callable, and its return value becomes the result instead. This is different from result_filter, as it can perform arbitrary transformation of the result value. This is mostly useful for top- level command invocations that need to provide the results in a particular format. Instead of a callable, a label for a pre-crafted result transformation can be given. [Default: None]
return_type ({'generator', 'list', 'item-or-list'}, optional) -- return value behavior switch. If 'item-or-list' a single value is returned instead of a one-item return value list, or a list in case of multiple return values. None is return in case of an empty list. [Default: 'list']