For Authlete 2.x documentation, see 2.x version.

First Steps

The Terraform provider does not support creating organizations, so the first step is to log in to the Authlete Management Console and create a new Organization, as shown below. If you don’t have an account, you can signup for a free trial account to get started. homepage

Creating the project

To get started let’s create a simple project with one Authlete service. You can find the source code on https://github.com/authlete/authlete-terraform-samples under simple_service directory. Keep in mind that Terraform projects have very loose structure requirements and are guided by conventions, so there is no hard requirement on the file structure. This sample shows a minimal configuration required for managing a service on Authlete using Terraform provider.

Setting your environment

In this sample, we will use environment variables to configure the Authlete Terraform plugin. The first thing you need is an Access Token, which authorizes the Terraform provider to securely call Authlete APIs. To create the Access Token, go to Organization Settings -> Basic Settings, then click Create under Access Tokens section. Once created, make sure to note the Token Value as it will be used in your environment configuration. Organization Token

Next, click the Create Service button to open the New Service screen and select the appropriate Cluster. Once selected, copy the URL and extract the Organization and Server IDs from it. To access the Organization ID:

Login to the Authlete Management Console
Navigate to your Organization page.
In the Organization Overview section, copy the Organization ID.
Set it as an environment variable by running the following command in your terminal:

    % export AUTHLETE_ORGANIZATION_ID="{ORG_ID}"

Replace {ORG_ID} with the actual ID you copied. New Service Setup

To access the Server ID:

Login to the Authlete Management Console
Navigate the Service page.
In the Service Overview section, copy the Cluster ID.
Set it as an environment variable by running the following command in your terminal:

    % export AUTHLETE_API_SERVER_ID="{SERVER_ID}"

Replace the "{SERVER_ID}" with the Cluster ID you copied. New Service Setup

Next, open your command line terminal and run the following commands to set your environment variables:

# Set your environment variables for Authlete
% export AUTHLETE_ORGANIZATION_ID="{ORG_ID}"
% export AUTHLETE_API_SERVER_ID="{SERVER_ID}"
% export AUTHLETE_API_VERSION="3.0"
% export AUTHLETE_SO_SECRET={ORG_TOKEN}
% export AUTHLETE_API_SERVER="https://us.authlete.com"  # Replace with your Dedicated Cloud server URL if needed.
% export AUTHLETE_IDP_SERVER="https://login.authlete.com"  # Replace with your Dedicated Cloud IDP URL if needed.

This will configure the necessary environment variables for the Terraform provider to interact with your Authlete instance. If you want these changes to persist across sessions, consider adding these export commands to your shell profile (e.g., ~/.bashrc, ~/.zshrc, or equivalent for your shell). This way, the environment variables will be automatically set every time you start a new terminal session.

Declaring the dependency to the provider and downloading it

The Authlete provider should be included in your project as a dependency and Terraform will take care of downloading it and making available to you. The providers dependencies are declared in a file provider.tf, by convention, and the structure is as below:

% cat provider.tf
terraform {
  required_providers {
    authlete = {
      source = "authlete/authlete"
      version = ">= 1.3.16"
    }
  }
}

After this file is created, go to the command line and run the initialization command that will create your workspace:

% terraform init

Initializing the backend...
Initializing provider plugins...
- Finding authlete/authlete versions matching ">= 1.3.16"...
- Installing authlete/authlete v1.3.16...
- Installed authlete/authlete v1.3.16 (self-signed, key ID E51D52BC3A580750)
Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:
https://www.terraform.io/docs/cli/plugins/signing.html
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

At this stage Terraform has downloaded the Authlete provider and installed it locally for you. Please note the version number might have changed to make sure to use the correct version from terraform registry.

Declaring the service resource

In Terraform vocabulary, the Authlete Services and Clients are resources. So we need to declare a resource with the Authlete-specific type in order to have it created. Go ahead and create a main.tf as the content below:

% cat main.tf
provider "authlete" {

}

resource "authlete_service" "as" {
  issuer = "https://as.mydomain.com"
  service_name = "MyDomainAS"
  description = "A terraform based service for managing the Authlete based OAuth server"
  supported_grant_types = ["AUTHORIZATION_CODE"]
  supported_response_types = ["CODE"]
}

output "api_key" {
   value = authlete_service.as.id
}

output "api_secret" {
   value = authlete_service.as.api_secret
   sensitive = true
}

In the first block, we are “configuring” an instance of the Authlete provider. This will instruct Terraform to actually instanciate some components that will talk to Authlete on your behalf. The second block is declaring a resource of type authlete_service with id as in the project. That name is specific to Terraform and it is not applied to the server-side configuration of Authlete. The properties in that block are straight forward: we are declaring an OAuth server that will accept only authorization code flow and the name on the server side will be MyDomainAS. The last 2 blocks are the instructions to Terraform to make available the id (which is the api_key) and the api_secret that you will use for configuring your AS and accessing that specific service in Authlete. To create that OAuth server backend on Authlete, go to command line and run the command below:

% terraform apply --auto-approve

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # authlete_service.as will be created
  + resource "authlete_service" "as" {
      + api_secret                            = (known after apply)
      + client_id_alias_enabled               = false
      + description                           = "A terraform based service for managing the Authlete based OAuth server"
      + direct_authorization_endpoint_enabled = false
      + direct_introspection_endpoint_enabled = false
      + direct_jwks_endpoint_enabled          = false
      + direct_revocation_endpoint_enabled    = false
      + direct_token_endpoint_enabled         = false
      + direct_user_info_endpoint_enabled     = false
      + id                                    = (known after apply)
      + issuer                                = "https://as.mydomain.com"
      + service_name                          = "MyDomainAS"
      + single_access_token_per_subject       = true
      + supported_grant_types                 = [
          + "AUTHORIZATION_CODE",
        ]
      + supported_response_types              = [
          + "CODE",
        ]
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + api_key    = (known after apply)
  + api_secret = (sensitive value)
authlete_service.as: Creating...
authlete_service.as: Creation complete after 6s [id=6505525048617]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

api_key = "6505525048617"
api_secret = <sensitive>

Congratulations! You have created a service in Authlete from Terraform. You can check the new service created in the Management Console by navigating to your Organization. New Service Setup

If you want to check the API key and API secret of the created service you can use the commands below. If your components are also configured using Terraform, this wouldn’t be required.

$ terraform output api_key
"6505525048617"
$ terraform output api_secret
"RtkKFbVqXXXXXXXXXXXXXXXXG6CNITo"

Managing the configuration

With the service created, as there will be requirements changes, a change management process needs to be established. Keep in mind that Terraform has the concept of workspaces and that can be handy for managing Test, Preproduction and Production configurations of services on Authlete. Regardless of how are you managing the state changes and version control of the scripts, the approach for changing the Authlete Service is to change the resource in the .tf file and apply those changes. Let’s use the service created in the previous section and include support for the client credentials grant type. So we change the main.tf that we have created to be like below and apply those changes using the terraform apply command:

% cat main.tf
provider "authlete" {

}

resource "authlete_service" "as" {
  issuer = "https://as.mydomain.com"
  service_name = "MyDomainAS"
  description = "A terraform based service for managing the Authlete based OAuth server"
  supported_grant_types = ["AUTHORIZATION_CODE", "CLIENT_CREDENTIALS"]
  supported_response_types = ["CODE"]
}

output "api_key" {
   value = authlete_service.as.id
}

output "api_secret" {
   value = authlete_service.as.api_secret
   sensitive = true
}
% terraform apply
authlete_service.as: Refreshing state... [id=6505525048617]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  # authlete_service.as will be updated in-place
  ~ resource "authlete_service" "as" {
        id                                            = "6505525048617"
      ~ supported_grant_types                         = [
            "AUTHORIZATION_CODE",
          + "CLIENT_CREDENTIALS",
        ]
        # (65 unchanged attributes hidden)
    }

Plan: 0 to add, 1 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

The Authlete provider has detected the inclusion of the CLIENT_CREDENTIALS grant type and Terraform is asking for your approval to change the service definition. After confirming the change the provider will fetch the status of that service from server and apply that specifically change.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

authlete_service.as: Modifying... [id=6505525048617]
authlete_service.as: Modifications complete after 6s [id=6505525048617]

Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

Outputs:

api_key = "6505525048617"
api_secret = <sensitive>

Please note that if you have changed the service definition you need to bring your change to Terraform state using the command terraform import. Next Step

Terraform

Self-Managed Deployment

Observability

Performance

Migration from Existing System

Networking

Integration with API Gateways

Operational Policies

Access Control

Developer Console

Service Owner Console

Creating a project from scratch

First Steps

Creating the project

Setting your environment

Declaring the dependency to the provider and downloading it

Declaring the service resource

Managing the configuration

​First Steps

​Creating the project

​Setting your environment

​Declaring the dependency to the provider and downloading it

​Declaring the service resource

​Managing the configuration

First Steps

Creating the project

Setting your environment

Declaring the dependency to the provider and downloading it

Declaring the service resource

Managing the configuration