Skip to main content
For Authlete 2.x documentation, see 2.x version.

​
Managing OAuth clients with Terraform

Before we dig into the matter, a contextualization is required here as client management on the OAuth/OpenID Connect world has multiple angles and scenarios. The scenarios and use cases for the Authlete provider for Terraform is managing the clients that are structurally required on the Authorization Server. For example: clients that will be used by a web portal or API server, mobile apps of the company domain, or clients that are required to be transposed between environments.

​
Support for Authlete Client

As with the support for services, Authlete provider allows creating, changing, and deleting OAuth clients on services, but as the clients exists within a service, that service needs to be configured either on the provider or in the client configuration, as we will see on this document. To represent an Authlete OAuth client, an authlete_client Terraform resource is defined and the supported properties of the object can be found on the provider documentation page.

​
Configuring the provider

For most use cases, where you’re provisioning clients for a single service, the simplest way to configure the provider is by using the environment variables AUTHLETE_API_KEY and AUTHLETE_API_SECRET. This will specify the service to be used when provisioning the client. In Authlete 3.0, the AUTHLETE_API_SECRET should be set to an Organization token, which corresponds to the organization where the service exists. The following examples assume you have a service already created in Authlete. You can use the service from the simple_service example, or create a new service via the Authlete Management Console. If you are continuing from the simple_service example, retrieve the output from the terraform output command: 
$ terraform output api_key
"6505525048617"
If you created the service via the Management Console, head to the Management Console, copy your Organization Token and Service ID, and set them as environment variables: 
% export AUTHLETE_API_KEY="{SERVICE_ID}"
% export AUTHLETE_API_SECRET="{ORG_TOKEN}"
% export AUTHLETE_API_SERVER="https://us.authlete.com"
You can also change your shell profile to make those settings permanent.

​
Declaring the clients and provisioning

As we have done for service, we start by declaring the dependency to the Authlete Provider and initializing the working env. You can check the section Declaring the dependency on Creating a project from scratch. The source of this example can be found on https://github.com/authlete/authlete-terraform-samples under client_management directory. After the initialization, create a main.tf file with the content as below: 
% cat main.tf
provider "authlete" {

}

resource "authlete_client" "portal" {
   developer = "mydomain"
   client_id_alias = "portal_client"
   client_id_alias_enabled = false
   client_type = "CONFIDENTIAL"
   redirect_uris = [ "https://www.mydomain.com/cb" ]
   response_types = [ "CODE" ]
   grant_types = [ "AUTHORIZATION_CODE"]
   client_name = "Customer Portal client"
   requestable_scopes = ["openid", "profile"]
   lifecycle {
     ignore_changes = [
      # Prevent unintended deletion of requests created via PAR.
      request_uris
     ]
   }
}


output "client_id" {
   value = authlete_client.portal.id
}

output "client_secret" {
   value = authlete_client.portal.client_secret
   sensitive = true
}
The first block is asking Terraform to instantiate the Authlete provide in the background to talk to Authlete Service on your behalf. The resource block (the 2nd one) is declaring an OIDC client with portal identifier in Terraform and some properties for a client like those that a Web Portal OIDC client would use.
Note: When using PAR, depending on the timing and the implementation of the authorization server, unused records may remain in request_uris, which could be unintentionally deleted by Terraform. Therefore, in this tutorial, we explicitly ignore request_uris.
The third and fourth blocks are declaring output variables that refer to OAuth client attributes. The sensitive attribute of the client_secret instructs Terraform to never echo its value in the logs, but make it available when queried. To create that client, run the command below in the same directory. 
% 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_client.portal will be created
+ resource "authlete_client" "portal" {
    + application_type                                 = (known after apply)
    + auth_time_required                               = (known after apply)
    + authorization_sign_alg                           = (known after apply)
    + bc_delivery_mode                                 = (known after apply)
    + bc_request_sign_alg                              = (known after apply)
    + bc_user_code_required                            = (known after apply)
    + client_id                                        = (known after apply)
    + client_id_alias                                  = "portal_client"
    + client_id_alias_enabled                          = false
    + client_name                                      = "Customer Portal client"
    + client_secret                                    = (sensitive value)
    + client_type                                      = "CONFIDENTIAL"
    + created_at                                       = (known after apply)
    + derived_sector_identifier                        = (known after apply)
    + developer                                        = "mydomain"
    + dynamically_registered                           = (known after apply)
    + front_channel_request_object_encryption_required = (known after apply)
    + grant_types                                      = [
        + "AUTHORIZATION_CODE",
          ]
    + id                                               = (known after apply)
    + id_token_sign_alg                                = (known after apply)
    + modified_at                                      = (known after apply)
    + par_required                                     = (known after apply)
    + redirect_uris                                    = [
        + "https://www.mydomain.com/cb",
          ]
    + request_object_encryption_alg_match_required     = (known after apply)
    + request_object_encryption_enc_match_required     = (known after apply)
    + request_object_required                          = (known after apply)
    + request_sign_alg                                 = (known after apply)
    + requestable_scopes                               = [
        + "openid",
        + "profile",
          ]
    + requestable_scopes_enabled                       = (known after apply)
    + response_types                                   = [
        + "CODE",
          ]
    + subject_type                                     = (known after apply)
    + tls_client_certificate_bound_access_tokens       = (known after apply)
    + token_auth_method                                = (known after apply)
    + token_auth_sign_alg                              = (known after apply)
    + user_info_sign_alg                               = (known after apply)
      }

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

Changes to Outputs:
+ client_id     = (known after apply)
+ client_secret = (sensitive value)
  authlete_client.portal: Creating...
  authlete_client.portal: Creation complete after 3s [id=6199126380453008]

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

Outputs:

client_id = "6199126380453008"
client_secret = <sensitive>
homepage After the creation of the client, you can validate the creation in the Management Console and/or query its client_id and secret via output commands like below: 
% terraform output client_id
"6199126380453008"
% terraform output client_secret
"97w_XXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXX_XXXXXXXXXX-XXXXXXXw8nNhg"

​
Changes on Client definition

Now any changes done on the client definition can be applied to Authlete by the provider. Challenged by requirements changes of refresh tokens for the portal client, for instance, you can go ahead and change the client definition to match the content like below: 
% cat main.tf
provider "authlete" {

}

resource "authlete_client" "portal" {
   developer = "mydomain"
   client_id_alias = "portal_client"
   client_id_alias_enabled = false
   client_type = "CONFIDENTIAL"
   redirect_uris = [ "https://www.mydomain.com/cb" ]
   response_types = [ "CODE" ]
   grant_types = [ "AUTHORIZATION_CODE", "REFRESH_TOKEN"]
   client_name = "Customer Portal client"
   requestable_scopes = ["openid", "profile"]
   access_token_duration = 30
   refresh_token_duration = 14400
   lifecycle {
     ignore_changes = [
      # Prevent unintended deletion of requests created via PAR.
      request_uris
     ]
   }
}


output "client_id" {
   value = authlete_client.portal.id
}

output "client_secret" {
   value = authlete_client.portal.client_secret
   sensitive = true
}
Here we are including the refresh token as an allowed grant type of this client, setting the access token to valid for 30 seconds, and defining the refresh token to be valid for 4 hours. To apply those changes you run the terraform apply command as below: 
% terraform apply
authlete_client.portal: Refreshing state... [id=6199126380453008]

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_client.portal will be updated in-place
  ~ resource "authlete_client" "portal" {
      ~ access_token_duration                            = 0 -> 30
      ~ grant_types                                      = [
            "AUTHORIZATION_CODE",
          + "REFRESH_TOKEN",
        ]
        id                                               = "6199126380453008"
      ~ refresh_token_duration                           = 0 -> 14400
      ~ requestable_scopes                               = [
          + "openid",
          + "profile",
        ]
        # (30 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: yes

authlete_client.portal: Modifying... [id=6199126380453008]
authlete_client.portal: Modifications complete after 1s [id=6199126380453008]

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

Outputs:

client_id = "6199126380453008"
client_secret = <sensitive>
Now if you check the Management Console, those changes should be reflected there. Client Settings Note that Terraform has a copy of the state of the client locally and the checking for differences to be changed on the server is done locally, which means that if you change the client definition on the server, the changes might be overwritten by Terraform when updating the client.

​
Configuring service on the client

If you need to manage clients of different Authlete services in the same workspace, you can specify the service’s API key and API secret on the client resource itself. This can be done using references to variables or other resources objects. As an example, we will use the same portal client from previous section and declare it for test and production services and the api key and secret will be references to variables. You can check the source of the example on https://github.com/authlete/authlete-terraform-samples under client_services folder. The input variables are defined, by convention, in a variables.tf file using a structure as below. Keep in mind that this variable approach is used extensively on Terraform projects that are multi modules, so it can be a powerful mechanism for defining very large deployments with multiple components. 
variable "authlete_service_test_api_key" {
  type = string
  description = "The api key of the Authlete test service"
  nullable = false
}

variable "authlete_service_test_api_secret" {
  type = string
  description = "The api secret of the Authlete test service"
  sensitive = true
  nullable = false
}

variable "authlete_service_production_api_key" {
  type = string
  description = "The api key of the Authlete production service"
  nullable = false
}

variable "authlete_service_production_api_secret" {
  type = string
  description = "The api secret of the Authlete production service"
  sensitive = true
  nullable = false
}
With those parameters defined, we can define each client like below. Note the service_api_key and service_api_secret properties’ values are prefixed with a var. to scope the reference to input variables. 
resource "authlete_client" "test_portal" {
   service_api_key = var.authlete_service_test_api_key
   service_api_secret = var.authlete_service_test_api_secret
   developer = "mydomain"
   client_id_alias = "portal_client"
   client_id_alias_enabled = false
   client_type = "CONFIDENTIAL"
   redirect_uris = [ "https://test.mydomain.com/cb",
      "http://localhost:3000/cb" ]
   response_types = [ "CODE" ]
   grant_types = [ "AUTHORIZATION_CODE", "REFRESH_TOKEN"]
   client_name = "Customer Portal client"
   requestable_scopes = ["openid", "profile"]
   access_token_duration = 30
   refresh_token_duration = 14400
   lifecycle {
     ignore_changes = [
      # Prevent unintended deletion of requests created via PAR.
      request_uris
     ]
   }
}

resource "authlete_client" "prod_portal" {
   service_api_key = var.authlete_service_production_api_key
   service_api_secret = var.authlete_service_production_api_secret
   developer = "mydomain"
   client_id_alias = "portal_client"
   client_id_alias_enabled = false
   client_type = "CONFIDENTIAL"
   redirect_uris = [ "https://www.mydomain.com/cb" ]
   response_types = [ "CODE" ]
   grant_types = [ "AUTHORIZATION_CODE", "REFRESH_TOKEN"]
   client_name = "Customer Portal client"
   requestable_scopes = ["openid", "profile"]
   access_token_duration = 30
   refresh_token_duration = 14400
}
Here for instance the test client can redirect to a test env and localhost:3000 for debugging purpose, while the production client can redirect only to the production portal. To run this example, you can define a variables file and provide it on command line when applying, as in the execution shown below: 
% cat services.tfvars
authlete_service_test_api_key = "6505525048617"
authlete_service_test_api_secret = "nXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXA"
authlete_service_production_api_key = "6509917760277"
authlete_service_production_api_secret = "BXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXs"
% terraform  apply -var-file="services.tfvars" --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_client.prod_portal will be created
  + resource "authlete_client" "prod_portal" {
      + access_token_duration                            = 30
      + service_api_key                                  = "6509917760277"
      + service_api_secret                               = (sensitive value)
      + application_type                                 = (known after apply)
      + auth_time_required                               = (known after apply)
      + authorization_sign_alg                           = (known after apply)
      + bc_delivery_mode                                 = (known after apply)
      + bc_request_sign_alg                              = (known after apply)
      + bc_user_code_required                            = (known after apply)
      + client_id                                        = (known after apply)
      + client_id_alias                                  = "portal_client"
      + client_id_alias_enabled                          = false
      + client_name                                      = "Customer Portal client"
      + client_secret                                    = (sensitive value)
      + client_type                                      = "CONFIDENTIAL"
      + created_at                                       = (known after apply)
      + derived_sector_identifier                        = (known after apply)
      + developer                                        = "mydomain"
      + dynamically_registered                           = (known after apply)
      + front_channel_request_object_encryption_required = (known after apply)
      + grant_types                                      = [
          + "AUTHORIZATION_CODE",
          + "REFRESH_TOKEN",
        ]
      + id                                               = (known after apply)
      + id_token_sign_alg                                = (known after apply)
      + modified_at                                      = (known after apply)
      + par_required                                     = (known after apply)
      + redirect_uris                                    = [
          + "https://www.mydomain.com/cb",
        ]
      + refresh_token_duration                           = 14400
      + request_object_encryption_alg_match_required     = (known after apply)
      + request_object_encryption_enc_match_required     = (known after apply)
      + request_object_required                          = (known after apply)
      + request_sign_alg                                 = (known after apply)
      + requestable_scopes                               = [
          + "openid",
          + "profile",
        ]
      + requestable_scopes_enabled                       = (known after apply)
      + response_types                                   = [
          + "CODE",
        ]
      + subject_type                                     = (known after apply)
      + tls_client_certificate_bound_access_tokens       = (known after apply)
      + token_auth_method                                = (known after apply)
      + token_auth_sign_alg                              = (known after apply)
      + user_info_sign_alg                               = (known after apply)
    }

  # authlete_client.test_portal will be created
  + resource "authlete_client" "test_portal" {
      + access_token_duration                            = 30
      + service_api_key                                  = "6505525048617"
      + service_api_secret                               = (sensitive value)
      + application_type                                 = (known after apply)
      + auth_time_required                               = (known after apply)
      + authorization_sign_alg                           = (known after apply)
      + bc_delivery_mode                                 = (known after apply)
      + bc_request_sign_alg                              = (known after apply)
      + bc_user_code_required                            = (known after apply)
      + client_id                                        = (known after apply)
      + client_id_alias                                  = "portal_client"
      + client_id_alias_enabled                          = false
      + client_name                                      = "Customer Portal client"
      + client_secret                                    = (sensitive value)
      + client_type                                      = "CONFIDENTIAL"
      + created_at                                       = (known after apply)
      + derived_sector_identifier                        = (known after apply)
      + developer                                        = "mydomain"
      + dynamically_registered                           = (known after apply)
      + front_channel_request_object_encryption_required = (known after apply)
      + grant_types                                      = [
          + "AUTHORIZATION_CODE",
          + "REFRESH_TOKEN",
        ]
      + id                                               = (known after apply)
      + id_token_sign_alg                                = (known after apply)
      + modified_at                                      = (known after apply)
      + par_required                                     = (known after apply)
      + redirect_uris                                    = [
          + "https://test.mydomain.com/cb",
          + "http://localhost:3000/cb",
        ]
      + refresh_token_duration                           = 14400
      + request_object_encryption_alg_match_required     = (known after apply)
      + request_object_encryption_enc_match_required     = (known after apply)
      + request_object_required                          = (known after apply)
      + request_sign_alg                                 = (known after apply)
      + requestable_scopes                               = [
          + "openid",
          + "profile",
        ]
      + requestable_scopes_enabled                       = (known after apply)
      + response_types                                   = [
          + "CODE",
        ]
      + subject_type                                     = (known after apply)
      + tls_client_certificate_bound_access_tokens       = (known after apply)
      + token_auth_method                                = (known after apply)
      + token_auth_sign_alg                              = (known after apply)
      + user_info_sign_alg                               = (known after apply)
    }

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

Changes to Outputs:
  + prod_portal_client_id     = (known after apply)
  + prod_portal_client_secret = (sensitive value)
  + test_client_secret        = (sensitive value)
  + test_portal_client_id     = (known after apply)
authlete_client.prod_portal: Creating...
authlete_client.test_portal: Creating...
authlete_client.test_portal: Creation complete after 1s [id=6203275126999388]
authlete_client.prod_portal: Creation complete after 1s [id=6203280133550227]

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

Outputs:

prod_portal_client_id = 6203280133550227
prod_portal_client_secret = <sensitive>
test_client_secret = <sensitive>
test_portal_client_id = 6203275126999388
If such a module is used in a multimodule project, the output variables could be used to inject the client id and secret from a configuration system to test and production environments, or a secret management solution. Next Step