Terraform

JOSSO 2.6 supports Terraform as a management tool. You can define identity appliances and their components as TF resources. This enables identity-as-code definitions.

TIP

You can import existing appliances using the jossoctl tool.

Quick Start

• Start JOSSO EE server; we will use a docker container
• Install the terraform plugin
• Create and test an example identity appliance

Starting JOSSO

docker run \
        --name josso-ee \
        --detach \
        --env JOSSO_CLIENT_ID="idbus-f2f7244e-bbce-44ca-8b33-f5c0bde339f7" \
        --env JOSSO_CLIENT_SECRET="7oUHlv(HLT%vxK4L" \
        --env JOSSO_ADMIN_USR=myadmin \
        --env JOSSO_ADMIN_PWD=changeme \
        --env JOSSO_SKIP_ADMIN_CREATE=false \
        -p8081:8081 -p8101:8101 \
        atricore/josso-ee:2.6.0-latest

Install the Terraform plugin

Once downloaded, copy the provider in terraform plugins folder. You must change the folder name depending on your OS, architecture and provider version. In our example we use linux, amd64 and version 0.2.0:

$ mkdir ~/.terraform.d/plugins/atricore.com/iam/iamtf/0.2.0/linux_amd64
$ copy terraform-provider-iamtf ~/.terraform.d/plugins/atricore.com/iam/iamtf/0.2.0/linux_amd64

A simple example

This example uses a simple Java web application running in Tomcat. We will define two files: one to declare the IAM.tf plugin, the other to define our identity appliance and all its resources. You could also create one file for each resource (idp, sp, identity store, etc.).

main.tf

terraform {
  required_providers {
    iamtf = {
      version = "~> 0.1.0"
      source  = "atricore.com/iam/iamtf"
    }
  }
}

ida-1.tf

First we need to define the provider. This has information about the IAM.tf server to be configured:

provider "iamtf" {
  org_name      = "atricore"
  endpoint      = "http://localhost:8081/atricore-rest/services"
  client_id     = "idbus-f2f7244e-bbce-44ca-8b33-f5c0bde339f7"
  client_secret = "7oUHlv(HLT%vxK4L"
}

Now we need to define an identity appliance. IAM.tf servers can run multiple appliances simultaneously, so all resources must be defined in the context of an appliance. The resource is iamtf_identity_appliance

resource "iamtf_identity_appliance" "ida-1" {
  name        = "ida-1"
  namespace   = "com.atricore.idbus.testacc.ida01"
  description = "Appliance #1"
  location    = "http://localhost:8081"
}

We need an identity source, a users repository that IAM.tf will access to retrieve user information. Directory servers and relational databases are supported, but in our example we are using the built-in identity vault iamtf_idvault.

resource "iamtf_idvault" "sso-users" {
  ida  = iamtf_identity_appliance.ida-1.name
  name = "sso-users"
}

The next step is to define our identity provider, iamtf_idp. We will use all the default settings. The IDP must reference our identity source, and it requires a public/private key pair for security (encryption and signature).

resource "iamtf_idp" "idp" {
  ida  = iamtf_identity_appliance.ida-1.name
  name = "idp"

  keystore {
    resource = filebase64("./idp.p12")
    password = "changeme"
  }

  id_sources = [iamtf_idvault.sso-users.name]
  depends_on = [
    iamtf_idvault.sso-users
  ]

}

And finally, we need a service provider (application). In our example, we are using a Java web application running in Tomcat. You can have as many applications as needed, and these may use different protocols like SAML and OIDC.

IAM.tf provides a set of SSO agents that can be installed in different environments/containers, to enable SSO capabilities. We use the Tomcat agent in this example:

resource "iamtf_execenv_tomcat" "tc85" {
  ida         = iamtf_identity_appliance.ida-1.name
  name        = "tc85"
  description = "Tomcat 8.5"
  version     = "8.5"
  depends_on  = [iamtf_idp.idp]
}

resource "iamtf_app_agent" "partnerapp1" {
  ida          = iamtf_identity_appliance.ida-1.name
  name         = "partnerapp1"
  app_location = "http://localhost:8080/partnerapp-1"

  keystore {
    resource = filebase64("./sp.p12")
    password = "changeme"
    key_password = "secret"
  }

  idp {
    name         = iamtf_idp.idp.name
    is_preferred = true
  }

  exec_env = iamtf_execenv_tomcat.tc85.name

  depends_on = [
    iamtf_idp.idp, iamtf_execenv_tomcat.tc85
  ]

}

Reference

Take a look at the plugin reference documentation for details on each resource:

• Providers
• Identity Appliance

Some examples related to commonly used components:

• Identity Provider
• Basic Authentication