github.com/dahs81/otto@v0.2.1-0.20160126165905-6400716cf085/website/source/docs/concepts/auth.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Authentication"
     4  sidebar_current: "docs-concepts-auth"
     5  description: |-
     6    Before performing any operation with Vault, the connecting client must be authenticated.
     7  ---
     8  
     9  # Authentication
    10  
    11  Before performing any operation with Vault, the connecting client must be
    12  _authenticated_. Authentication is the process of verifying a person or
    13  machine is who they say they are and assigning an identity to them. This
    14  identity is then used when making requests with Vault.
    15  
    16  Authentication in Vault is pluggable via authentication backends. This
    17  allows you to authenticate with Vault using a method that works best for your
    18  organization. For example, you can authenticate using GitHub, certs, etc.
    19  
    20  ## Authentication Backends
    21  
    22  There are many authentication backends available for Vault. They
    23  are enabled using `vault auth-enable`. After they're enabled, you can
    24  learn more about them using `vault path-help auth/<name>`. For example,
    25  if you enable GitHub, you can use `vault path-help auth/github` to learn more
    26  about how to configure it and login.
    27  
    28  Multiple authentication backends can be enabled, but only one is required
    29  to gain authentication. It is not currently possible to force a user through
    30  multiple authentication backends to gain access.
    31  
    32  This allows you to enable human-friendly as well as machine-friendly
    33  backends at the same time. For example, for humans you might use the
    34  "github" auth backend, and for machines you might use the "app-id" backend.
    35  
    36  ## Tokens
    37  
    38  There is an [entire page dedicated to tokens](/docs/concepts/tokens.html),
    39  but it is important to understand that authentication works by verifying
    40  your identity and then generating a token to associate with that identity.
    41  
    42  For example, even though you may authenticate using something like GitHub,
    43  Vault generates a unique access token for you to use for future requests.
    44  The CLI automatically attaches this token to requests, but if you're using
    45  the API you'll have to do this manually.
    46  
    47  This token given for authentication with any backend can also be used
    48  with the full set of token commands, such as creating new sub-tokens,
    49  revoking tokens, and renewing tokens. This is all covered on the
    50  [token concepts page](/docs/concepts/tokens.html).
    51  
    52  ## Authenticating
    53  
    54  #### Via the CLI
    55  
    56  To authenticate with the CLI, `vault auth` is used. This supports many
    57  of the built-in authentication methods. For example, with GitHub:
    58  
    59  ```
    60  $ vault auth -method=github token=<token>
    61  ...
    62  ```
    63  
    64  After authenticating, you will be logged in. The CLI command will also
    65  output your raw token. This token is used for revocation and renewal.
    66  As the user logging in, the primary use case of the token is renewal,
    67  covered below in the "Auth Leases" section.
    68  
    69  To determine what variables are needed for an authentication method,
    70  supply the `-method` flag without any additional arguments and help
    71  will be shown.
    72  
    73  If you're using a method that isn't supported via the CLI, then the API
    74  must be used.
    75  
    76  #### Via the API
    77  
    78  API authentication is generally used for machine authentication. Each
    79  auth backend implements is own login endpoint. Use the `vault path-help`
    80  mechanism to find the proper endpoint.
    81  
    82  For example, the GitHub login endpoint is located at `auth/github/login`.
    83  And to determine the arguments needed, `vault path-help auth/github/login` can
    84  be used.
    85  
    86  ## Auth Leases
    87  
    88  Just like secrets, identities have
    89  [leases](/docs/concepts/lease.html) associated with them. This means that
    90  you must reauthenticate after the given lease period to continue accessing
    91  Vault.
    92  
    93  To set the lease associated with an identity, reference the help for
    94  the specific authentication backend in use. It is specific to each backend
    95  how leasing is implemented.
    96  
    97  And just like secrets, identities can be renewed without having to
    98  completely reauthenticate. Just use `vault token-renew <token>` with the
    99  token associated with your identity to renew it.