terraform/website/docs/internals/login-protocol.html.markdown

layout	page_title	sidebar_current	description
docs	Login Protocol	docs-internals-login-protocol	The login protocol is used for authenticating Terraform against servers providing Terraform-native services.

Server-side Login Protocol

~> Note: You don't need to read these docs to use terraform login. The information below is for anyone intending to implement the server side of terraform login in order to offer Terraform-native services in a third-party system.

The terraform login command supports performing an OAuth 2.0 authorization request using configuration provided by the target host. You may wish to implement this protocol if you are producing a third-party implementation of any Terraform-native services, such as a Terraform module registry.

First, Terraform uses remote service discovery to find the OAuth configuration for the host. The host must support the service name login.v1 and define for it an object containing OAuth client configuration values, like this:

{
  "login.v1": {
    "client": "terraform-cli",
    "grant_types": ["authz_code"],
    "authz": "/oauth/authorization",
    "token": "/oauth/token",
    "ports": [10000, 10010],
  }
}

The properties within the discovery object are as follows:

• client (Required): The client_id value to use when making requests, as defined in RFC 6749 section 2.2.

  Because Terraform is a public client (it is installed on end-user systems and thus cannot protect an OAuth client secret), the client_id is purely advisory and the server must not use it as a guarantee that an authorization request is truly coming from Terraform.

• grant_types (Optional): A JSON array of strings describing a set of OAuth 2.0 grant types the server is able to support. A "grant type" selects a specific mechanism by which an OAuth server authenticates the request and issues an authorization token.

  Terraform CLI currently only supports a single grant type:

  • authz_code: authorization code grant. Both the authz and token properties are required when authz_code is present.

  Other grant types may be supported in future versions of Terraform CLI, and may impose different requirements on the authz and token properties. If not specified, grant_types defaults to ["authz_code"].

• authz (Required if needed for a given grant type): the server's authorization endpoint. If given as a relative URL, it is resolved from the location of the service discovery document.

• token (Required if needed for a given grant type): the server's token endpoint. If given as a relative URL, it is resolved from the location of the service discovery document.

• ports (Optional): A two-element JSON array giving an inclusive range of TCP ports that Terraform may use for the temporary HTTP server it will start to provide the redirection endpoint for the first step of an authorization code grant. Terraform opens a TCP listen port on the loopback interface in order to receive the response from the server's authorization endpoint.

  If not specified, Terraform is free to select any TCP port greater than or equal to 1024.

  Terraform allows constraining this port range for interoperability with OAuth server implementations that require each client_id to be associated with a fixed set of valid redirection endpoint URLs. Configure such a server to expect a range of URLs of the form http://localhost:10000/ with different consecutive port numbers, and then specify that port range using ports.

  We recommend allowing at least 10 distinct port numbers if possible, and assigning them to numbers greater than or equal to 10000, to minimize the risk that all of the possible ports will already be in use on a particular system.

When requesting an authorization code grant, Terraform CLI implements the Proof Key for Code Exchange extension in order to protect against other applications on the system intercepting the incoming request to the redirection endpoint. We strongly recommend that you select an OAuth server implementation that also implements this extension and verifies the code challenge sent to the token endpoint.

Terraform CLI does not support OAuth refresh tokens or token expiration. If your server issues time-limited tokens, Terraform CLI will simply begin receiving authorization errors once the token expires, after which the user can run terraform login again to obtain a new token.

-> Note: As a special case, Terraform can use a Resource Owner Password Credentials Grant only when interacting with app.terraform.io (Terraform Cloud), under the recommendation in the OAuth specification to use this grant type only when the client and server are closely related. The password grant type is not supported for any other hostname and will be ignored.