Add authentication to a provider
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 addusername
andpassword
parameters to your provider schema. In addition, you will set theConfigureContextFunc
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.
Then, checkout the implement-read
branch. This step is optional but recommended to ensure that your code matches the code from the previous tutorials.
Your directory should have the following structure.
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.
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.
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
.
Format your code.
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.
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.
Format your code.
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.
Test the provider
Now that you implemented authentication, verify that it works.
First, confirm that you are in the terraform-provider-hashicups
root directory.
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.
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.
Navigate to the terraform-provider-hashicups/examples
directory. This contains a sample Terraform configuration for the Terraform HashiCups provider.
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.
Finally, initialize your workspace to refresh your HashiCups provider, then apply.
Check the terminal containing your HashiCups logs for the recorded operations invoked by the HashiCups provider.
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.