github.com/eliastor/durgaform@v0.0.0-20220816172711-d0ab2d17673e/website/docs/internals/login-protocol.mdx (about)

     1  ---
     2  page_title: Login Protocol
     3  description: >-
     4    The login protocol is used for authenticating Terraform against servers
     5    providing Terraform-native services.
     6  ---
     7  
     8  # Server-side Login Protocol
     9  
    10  ~> **Note:** You don't need to read these docs to _use_
    11  [`terraform login`](/cli/commands/login).  The information below is for
    12  anyone intending to implement the server side of `terraform login` in order to
    13  offer Terraform-native services in a third-party system.
    14  
    15  The `terraform login` command supports performing an OAuth 2.0 authorization
    16  request using configuration provided by the target host. You may wish to
    17  implement this protocol if you are producing a third-party implementation of
    18  any [Terraform-native services](/internals/remote-service-discovery),
    19  such as a Terraform module registry.
    20  
    21  First, Terraform uses
    22  [remote service discovery](/internals/remote-service-discovery) to
    23  find the OAuth configuration for the host. The host must support the service
    24  name `login.v1` and define for it an object containing OAuth client
    25  configuration values, like this:
    26  
    27  ```json
    28  {
    29    "login.v1": {
    30      "client": "terraform-cli",
    31      "grant_types": ["authz_code"],
    32      "authz": "/oauth/authorization",
    33      "token": "/oauth/token",
    34      "ports": [10000, 10010],
    35    }
    36  }
    37  ```
    38  
    39  The properties within the discovery object are as follows:
    40  
    41  * `client` (Required): The `client_id` value to use when making requests, as
    42    defined in [RFC 6749 section 2.2](https://tools.ietf.org/html/rfc6749#section-2.2).
    43  
    44    Because Terraform is a _public client_ (it is installed on end-user systems
    45    and thus cannot protect an OAuth client secret), the `client_id` is purely
    46    advisory and the server must not use it as a guarantee that an authorization
    47    request is truly coming from Terraform.
    48  
    49  * `grant_types` (Optional): A JSON array of strings describing a set of OAuth
    50    2.0 grant types the server is able to support. A "grant type" selects a
    51    specific mechanism by which an OAuth server authenticates the request and
    52    issues an authorization token.
    53  
    54    Terraform CLI currently only supports a single grant type:
    55  
    56    * `authz_code`: [authorization code grant](https://tools.ietf.org/html/rfc6749#section-4.1).
    57      Both the `authz` and `token` properties are required when `authz_code` is
    58      present.
    59  
    60    Other grant types may be supported in future versions of Terraform CLI,
    61    and may impose different requirements on the `authz` and `token` properties.
    62    If not specified, `grant_types` defaults to `["authz_code"]`.
    63  
    64  * `authz` (Required if needed for a given grant type): the server's
    65    [authorization endpoint](https://tools.ietf.org/html/rfc6749#section-3.1).
    66    If given as a relative URL, it is resolved from the location of the
    67    service discovery document.
    68  
    69  * `token` (Required if needed for a given grant type): the server's
    70    [token endpoint](https://tools.ietf.org/html/rfc6749#section-3.2).
    71    If given as a relative URL, it is resolved from the location of the
    72    service discovery document.
    73  
    74  * `ports` (Optional): A two-element JSON array giving an inclusive range of
    75    TCP ports that Terraform may use for the temporary HTTP server it will start
    76    to provide the [redirection endpoint](https://tools.ietf.org/html/rfc6749#section-3.1.2)
    77    for the first step of an authorization code grant. Terraform opens a TCP
    78    listen port on the loopback interface in order to receive the response from
    79    the server's authorization endpoint.
    80  
    81    If not specified, Terraform is free to select any TCP port greater than or
    82    equal to 1024.
    83  
    84    Terraform allows constraining this port range for interoperability with OAuth
    85    server implementations that require each `client_id` to be associated with
    86    a fixed set of valid redirection endpoint URLs. Configure such a server
    87    to expect a range of URLs of the form `http://localhost:10000/`
    88    with different consecutive port numbers, and then specify that port range
    89    using `ports`.
    90  
    91    We recommend allowing at least 10 distinct port numbers if possible, and
    92    assigning them to numbers greater than or equal to 10000, to minimize the
    93    risk that all of the possible ports will already be in use on a particular
    94    system.
    95  
    96  When requesting an authorization code grant, Terraform CLI implements the
    97  [Proof Key for Code Exchange](https://tools.ietf.org/html/rfc7636) extension in
    98  order to protect against other applications on the system intercepting the
    99  incoming request to the redirection endpoint. We strongly recommend that you
   100  select an OAuth server implementation that also implements this extension and
   101  verifies the code challenge sent to the token endpoint.
   102  
   103  Terraform CLI does not support OAuth refresh tokens or token expiration. If your
   104  server issues time-limited tokens, Terraform CLI will simply begin receiving
   105  authorization errors once the token expires, after which the user can run
   106  `terraform login` again to obtain a new token.
   107  
   108  -> **Note:** As a special case, Terraform can use a
   109  [Resource Owner Password Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.3)
   110  only when interacting with `app.terraform.io` ([Terraform Cloud](/cloud)),
   111  under the recommendation in the OAuth specification to use this grant type only
   112  when the client and server are closely related. The `password` grant type is
   113  not supported for any other hostname and will be ignored.