Add authentication to a provider

9min
|
Terraform

Note: We recommend using the Terraform Plugin Framework for new provider development because it offers significant advantages compared to the SDKv2. Refer to the Plugin Framework tutorials to learn how to create providers using the framework.

In this tutorial, you will add authentication to a Terraform provider that interacts with the API of a fictional coffee-shop application called Hashicups, and access protected API endpoints. To do this, you will:

Update provider schema.
You will add username and password parameters to your provider schema. In addition, you will set the ConfigureContextFunc property to the the name of the function that will configure your provider, providerConfigure.
Define providerConfigure
This function actually configures your provider. If both the username and password are not empty, the function returns an authenticated API client; else, the function returns an unauthenticated API client. The authenticated API client is able to access protected endpoints, the unauthenticated one is not.

Prerequisites

To follow this tutorial, you need:

a Golang 1.15+ installed and configured.
the Terraform 0.14+ CLI installed locally.
Docker and Docker Compose to run an instance of HashiCups locally.

Navigate to your terraform-provider-hashicups directory. Next, fetch new changes.

$ git fetch

Then, checkout the implement-read branch. This step is optional but recommended to ensure that your code matches the code from the previous tutorials.

$ git checkout implement-read

Clone the implement-read branch of the Terraform HashiCups Provider repository.

$ git clone --branch implement-read https://github.com/hashicorp/terraform-provider-hashicups

Change into the cloned repository.

$ cd terraform-provider-hashicups

Then, install all the provider's dependencies.

$ go mod tidy

Build provider binary

Next, build the binary and move it into your user Terraform plugins directory. This allows you to sideload and test the custom provider. Select the tab for your operating system for specific instructions.

$ make install
go build -o terraform-provider-hashicups
mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/darwin_amd64

Build the provider binary.

$ go build -o terraform-provider-hashicups

Retrieve your system's OS and ARCH. You can find a full list of supported GOOS and GOARCH here.

$ export OS_ARCH="$(go env GOHOSTOS)_$(go env GOHOSTARCH)"

Create the appropriate subdirectory within the user plugins directory for the HashiCups provider if it doesn't exist already.

$ mkdir -p ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/$OS_ARCH

Next, move the binary to the appropriate subdirectory within your user plugins directory.

$ mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/$OS_ARCH

Build the provider binary.

$ go build -o terraform-provider-hashicups.exe

Create the appropriate subdirectory within the user plugins directory for the HashiCups provider if it doesn't exist already, replacing [OS_ARCH] with your system's OS_ARCH. You can find a full list of supported GO_ARCH here.

$ mkdir -p %APPDATA%\terraform.d\plugins\hashicorp.com\edu\hashicups\0.2\[OS_ARCH]

Then, move the binary to the appropriate subdirectory within your user plugins directory, replacing [OS_ARCH] with your system's OS_ARCH.

$ move terraform-provider-hashicups.exe %APPDATA%\terraform.d\plugins\hashicorp.com\edu\hashicups\0.2\[OS_ARCH]

Tip

The Perform CRUD operations with Providers tutorial explains why and how to sideload custom providers. Refer to it to learn more about where to install custom providers and how to reference them in your configuration.

Run HashiCups API

The HashiCups provider requires an instance of HashiCups. Navigate to the docker_compose directory then run docker-compose up to spin up a local instance of HashiCups on port :19090.

$ cd docker_compose && docker-compose up

Leave this terminal running.

In another terminal, verify that HashiCups is running by sending a request to its health check endpoint.

$ curl localhost:19090/health
ok

Navigate to your terraform-provider-hashicups directory.

$ cd ..

Your directory should have the following structure.

$ tree -L 2
.
├── Makefile
├── README.md
├── docker_compose
│   ├── conf.json
│   └── docker-compose.yml
├── examples
│   ├── coffee
│   ├── main.tf
├── go.mod
├── go.sum
├── hashicups
│   ├── data_source_coffee.go
│   └── provider.go
├── main.go
└── vendor

If you're stuck at any point during this tutorial, refer to the auth-configuration branch to see the changes implemented in this tutorial.

Update provider schema

HashiCups requires a username and password to generate an JSON web token (JWT) which is used to authenticate against protected endpoints. You will use this user to authenticate to the HashiCups provider to manage your orders.

Create a user on HashiCups named education with the password test123. If you already did this in a previous tutorial, you can skip signing up and reuse your previous token.

$ curl -X POST localhost:19090/signup -d '{"username":"education", "password":"test123"}'
{"UserID":1,"Username":"education","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTEwNzgwODUsInVzZXJfaWQiOjIsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.CguceCNILKdjOQ7Gx0u4UAMlOTaH3Dw-fsll2iXDrYU"}

$ curl -X POST localhost:19090/signin -d '{"username":"education", "password":"test123"}'
{"UserID":1,"Username":"education","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTEwNzgwODUsInVzZXJfaWQiOjIsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.CguceCNILKdjOQ7Gx0u4UAMlOTaH3Dw-fsll2iXDrYU"}

Set a HASHICUPS_TOKEN environment variable to the token generated in the previous step. You will use this later tutorials to verify your HashiCups order has been created, updated and deleted.

$ export HASHICUPS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTEwNzgwODUsInVzZXJfaWQiOjIsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.CguceCNILKdjOQ7Gx0u4UAMlOTaH3Dw-fsll2iXDrYU

In your hashicups/provider.go file, replace the Provider() function with the code snippet below. This defines the provider schema (username, password) and the ConfigureContextFunc.

hashicups/provider.go

// Provider -
func Provider() *schema.Provider {
  return &schema.Provider{
    Schema: map[string]*schema.Schema{
      "username": &schema.Schema{
        Type:        schema.TypeString,
        Optional:    true,
        DefaultFunc: schema.EnvDefaultFunc("HASHICUPS_USERNAME", nil),
      },
      "password": &schema.Schema{
        Type:        schema.TypeString,
        Optional:    true,
        Sensitive:   true,
        DefaultFunc: schema.EnvDefaultFunc("HASHICUPS_PASSWORD", nil),
      },
    },
    ResourcesMap: map[string]*schema.Resource{},
    DataSourcesMap: map[string]*schema.Resource{
      "hashicups_coffees":     dataSourceCoffees(),
    },
    ConfigureContextFunc: providerConfigure,
  }
}

Format your code.

$ go fmt ./...

Notice the DefaultFunc for both the username and password parameters attempts to use the respective environment variables as the default values. This is useful for automated provider testing.

Define `providerConfigure`

Import the context, API client and diag libraries into the provider.go file. The providerConfigure function will use these libraries.

hashicups/provider.go

import (
  "context"

  "github.com/hashicorp-demoapp/hashicups-client-go"
  "github.com/hashicorp/terraform-plugin-sdk/v2/diag"
  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
)

Then, add the providerConfigure function below your Provider() function. This function retrieves the username and password from the provider schema to authenticate and configure your provider.

hashicups/provider.go

func providerConfigure(ctx context.Context, d *schema.ResourceData) (interface{}, diag.Diagnostics) {
  username := d.Get("username").(string)
  password := d.Get("password").(string)

  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  if (username != "") && (password != "") {
    c, err := hashicups.NewClient(nil, &username, &password)
    if err != nil {
      return nil, diag.FromErr(err)
    }

    return c, diags
  }

  c, err := hashicups.NewClient(nil, nil, nil)
  if err != nil {
    return nil, diag.FromErr(err)
  }

  return c, diags
}

Format your code.

$ go fmt ./...

Notice that the function is able to retrieve the username and password values from the *schema.ResourceData. The HashiCups API client is a simple API wrapper for the HashiCups API.

By returning the HashiCups API client, the provider will be able to access the API client as a meta input parameter. In the Implement Complex Read tutorial, you will use the meta input parameter to access a protected endpoint, /orders.

Save your hashicups/provider.go file, then load the API client library into your /vendor directory.

$ go mod tidy

Test the provider

Now that you implemented authentication, verify that it works.

First, confirm that you are in the terraform-provider-hashicups root directory.

$ pwd
~/terraform-provider-hashicups

$ make install
go build -o terraform-provider-hashicups
mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/darwin_amd64

Build the provider binary.

$ go build -o terraform-provider-hashicups

Retrieve your system's OS and ARCH. You can find a full list of supported GOOS and GOARCH here.

$ export OS_ARCH="$(go env GOHOSTOS)_$(go env GOHOSTARCH)"

Create the appropriate subdirectory within the user plugins directory for the HashiCups provider if it doesn't exist already.

$ mkdir -p ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/$OS_ARCH

Next, move the binary to the appropriate subdirectory within your user plugins directory.

$ mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/$OS_ARCH

Build the provider binary.

$ go build -o terraform-provider-hashicups.exe

$ mkdir -p %APPDATA%\terraform.d\plugins\hashicorp.com\edu\hashicups\0.2\[OS_ARCH]

Then, move the binary to the appropriate subdirectory within your user plugins directory, replacing [OS_ARCH] with your system's OS_ARCH.

$ move terraform-provider-hashicups.exe %APPDATA%\terraform.d\plugins\hashicorp.com\edu\hashicups\0.2\[OS_ARCH]

Tip

Navigate to the terraform-provider-hashicups/examples directory. This contains a sample Terraform configuration for the Terraform HashiCups provider.

$ cd examples

Then, authenticate your provider. You can either set them via environment variables (recommended) or update your provider block.

Set HASHICUPS_USERNAME and HASHICUPS_PASSWORD to education and test123 respectively.

$ export HASHICUPS_USERNAME=education \
  export HASHICUPS_PASSWORD=test123

Finally, initialize your workspace to refresh your HashiCups provider, then apply.

$ terraform init && terraform apply --auto-approve
Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Check the terminal containing your HashiCups logs for the recorded operations invoked by the HashiCups provider.

api_1  | 2020-12-10T09:26:23.349Z [INFO]  Handle User | signin
api_1  | 2020-12-10T09:26:23.357Z [INFO]  Handle Coffee
api_1  | 2020-12-10T09:26:23.488Z [INFO]  Handle User | signin
api_1  | 2020-12-10T09:26:23.606Z [INFO]  Handle User | signin

The provider should have invoked a request to the signin endpoint.

Next steps

In this tutorial, you added authentication to your HashiCups provider. If you were stuck during this tutorial, checkout the auth-configuration branch to see the changes implemented in this tutorial.

The Terraform Provider Scaffold is a quick-start repository for creating a Terraform provider. Use this GitHub template when you're ready to create a custom provider.
To learn more about the Terraform Plugin SDK, refer to the Terraform Plugin SDK Documentation.

Setup

Complex read

Prerequisites

Update provider schema

Define providerConfigure

Test the provider

Next steps

Define `providerConfigure`