Name
====

dragom-credential-manager

Description
===========

Manages credentials used by Dragom to access external systems.

Synopsis
========

dragom-credential-manager enum-resource-realm-mappings
  Enumerates the resource pattern to realm mappings.

dragom-credential-manager enum-passwords
  Enumerates the realms and users for which a password is defined.

dragom-credential-manager get-password <resource> [<user>]
  Returns the decrypted password for the realm corresponding to a resource and
  a specific user if specified.

dragom-credential-manager set-password <resource> [<user>]
  Sets the password for the realm corresponding to a resource and a specific
  user if specified.

dragom-credential-manager remove-password <resource> [<user>]
  Removes the password for the realm corresponding to a resource and a specific
  user if specified.

dragom-credential-manager enum-default-users
  Enumerates the default users for the realms.

dragom-credential-manager get-default-user <resource>
  Returns the default user for the realm corresponding to a resource.

dragom-credential-manager set-default-user <resource> <user>
  Sets the default user for the realm corresponding to a resource.

dragom-credential-manager remove-default-user <resource>
  Removes the default user for the realm corresponding to a resource.
  
dragom-credential-manager --help
  Displays this help information.

Arguments
=========

The first argument is the command to execute. The following arguments depend on
the command.

  Command enum-resource-realm-mappings
  ------------------------------------

  Enumerates the resource pattern to realm mapping that are supported by the
  configuration of the tool.

  Command enum-passwords
  ----------------------

  Enumerates the realms and users form which a password is defined. The
  passwords themselves are not returned.

  Command get-password <resource> [<user>]
  ----------------------------------------

  Returns the decrypted password for the realm corresponding to a resource and
  a specific user if specified.

  If the user is not specified and the resource specifies the user, the
  password for that user is returned.

  If the resource does not specify the user, the password for the default user
  of the realm is returned.

  If no default user is set for the realm, the tool exits with the exit code 1.

  Only the password is returned with no header, other information or linefeed.

  This command is useful to allow a CLI tool outside of Dragom to obtain a
  password. It is to be used with care as the password is returned decrypted,
  in plain text. A tool which invokes this command should generally store the
  password in an environment variable and at the very least avoid outputting it
  on stdout.

  Command set-password <resource> [<user>]
  ----------------------------------------

  Sets the password for the realm corresponding to a resource and a specific
  user if specified.

  If the user is not specified and the resource specifies the user, the
  password for that user is set.

  If the resource does not specify the user, the password for the default user
  of the realm is set.

  If no default user is set for the realm, the tool exits with the exit code 1.
  
  If for some reason the password cannot be set, the tool exists with the exit
  code 1.

  If a password is already set for the realm and the user, it is overwritten.

  The password is stored encrypted.

  Command remove-password <resource> [<user>]
  -------------------------------------------

  Removes the password for the realm corresponding to a resource and a specific
  user if specified.

  If the user is not specified and the resource specifies the user, the
  password for that user is removed.

  If the resource does not specify the user, the password for the default user
  of the realm is removed.

  If no default user is set for the realm, no action is performed.

  Command enum-default-users
  --------------------------

  Enumerates the default users for the realms.

  Command get-default-user
  ------------------------

  Returns the default user for the realm corresponding to a resource.
  
  The resource may specify a user, in which case this user is returned.

  If there is no default user, the tool exits with the exit code 1.

  Command set-default-user <resource> <user>
  ------------------------------------------

  Sets the default user for the realm corresponding to a resource.

  The resource must not specify a user, otherwise the tool exits with the
  exit code 1.
  
  Command remove-default-user <resource>
  --------------------------------------

  Removes the default user for the realm corresponding to a resource.

<resource>: Resource that will be mapped to the realm on which to apply the
  command. See "Resource" below.
  
<user>: User to for which to apply the command. 

Options
=======

--help: Displays this help information. 

Resource
========

A resource is typically a URL of an external system such as:

https://acme.com/jenkins

Resources are mapped to realms with which the passwords are associated, as
opposed to being associated with the individual resources. Many different
resources can be mapped to the same realm if, for example, two different
external systems use the same user directory for authentication.

The enum-resource-realm-mappings command enumerates these mappings, in which
the resources are identified by regular expressions and the realms can contain
references to captured groups.

A resource can contain a specific user, as in:

https://jsmith@acme.com/jenkins

When this is the case the user is taken into consideration by the various
commands.

Among the resource to realm and user mapping, there is generally one which
allows specifying a realm explicitly with the following syntax:

REALM:<realm>

In this case the realm must be supported by the configuration of the tool and
be returned by the enum-resource-realm-mappings command.

Exit code
=========

0 on success.

1 on error.