Quick Start

You have two options to get you started, the simplest is to run a docker based example that provides all the components to test IAM.tf, the second is to create your own example and use existing infrastructure like DB servers etc. Before we get into these two scenarios, we need to install a few of components.

• Server: it can be run in a container, or standalone (we'll use a container in this example)
• Terraform plugin: used to configure the server
• Command line tool: manages a running server

In this guide we will install these three tools, and run a simple example. We will follow these steps: first we are going to start a new IAM.tf server. Then we are going to create the configuration for our example. We call IAM.tf configurations identity appliances. Once the identity appliance is stored in the server, we will use iamtfctl to build and start that appliance. Let's get started.

Install iamtfctl

This utility allows you to control IAM.tf servers. Just download the binary file and copy it in any folder part of your PATH (i.e. /usr/bin). You can test you have the right version by typing iamtfctl version

unzip ~/Downloads/iamtfctl-linux-amd64-0.4.3.zip

iamtfctl version
v0.4.3

iamtfctl --help
IAM.tf is an IAM platform. This is the command line interface application

Usage:
  iamtfctl [command]

Available Commands:
  activate    Activate all agent resources
  build       A brief description of your command
  completion  Generate the autocompletion script for the specified shell
  delete      delete identity appliance
  export      export resource details
  help        Help about any command
  import      import resource details
  layout      layout identity appliance
  list        List all resources of a given type
  start       start an identity appliance
  stop        Stop the identity appliance
  test        test a resource
  validate    validate identity appliance
  version     prints command version
  view        View resource details

Flags:
  -a, --appliance string         Appliance id or name
      --client-id string         client id
      --client-password string   josso user password
      --client-secret string     client secret
      --client-user string       josso user
      --config string            config file (default is $HOME/.josso-cli-go.yaml)
  -d, --debug                    enable client debug
  -e, --endpoint string          josso server endpoint
  -h, --help                     help for iamtfctl
      --quiet                    quiet
      --trace                    trace api traffic
  -v, --verbose                  verbose output

Use "iamtfctl [command] --help" for more information about a command.

You can check the created appliance by using the iamtfctl command

iamtfctl list appliances

Run a docker based example

Let's get the examples from github. We will run myiam-02 example in this guide. We will need:

• docker
• docker-compose
• iamtfcl
• iamtfct terraform provider

This examples starts an openldap server containing user information, an IAM.tf server to act as identity provider and a tomcat server running two web applications.

Get the example from GitHub

You can take a look at several IAM.tf examples in GitHub.

git clone https://github.com/atricore/iamtf-examples.git

Start the all containers

Before starting the containers, we need to build them running docker-compose build. Once the process is completed we can start all three containers using docker-compose up -d

cd iamtf-examples/myiam-02
docker-compose build
docker-compose up -d

Create the Identity Appliance

After IAM.tf server has been started, we can apply our identity appliance definition using terraform. The configuration files are in the tf folder.

Tips

iamtfctl configuration: you can configure endpoint, client-id and client-secret as environment variables or in a yaml file.

cd tf
terraform init
terraform apply
iamtfctl start \
--appliance myiam-02 \
--endpoint http://localhost:8081/atricore-rest/services \
--client-id idbus-f2f7244e-bbce-44ca-8b33-f5c0bde339f7 \
--client-secret "7oUHlv(HLT%vxK4L"

Test it!

You can now open a web browser and access one of the applications: http://localhost:8080/partnerapp1. Use user1 for username and user1pwd for password. If you access the 2nd application after you authentiated, you will see that you are automatically recognized http://localhost:8080/partnerapp2

Tips

both applications are the same base code deployed twice, in different contexts: partnerapp1 and partnerapp2

Build your own example

This section is about creating a new example from scratch. We will start an IAM.tf server, create an identity appliance configuration and user terraform and iamtfctl to deploy it into the server and start all IAM services.

Start the server

We are using the container version of the server, but you can also run it as a standalone process in any Windows, Linux or MacOS environment.

For more details, check the container documentation.

docker run \
        --name iamtf \
        --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/iamtf:latest

Create Identity Appliance

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.610"
      source  = "atricore/iamtf"
    }
  }
}

ida-1.tf

First we need to define the provider. This has information about the IAM.tf server to be configured, you can see that client_id and client_secret match the values we set when starting the sever JOSSO_CLIENT_ID and JOSSO_CLIENT_SECRET

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 iedentity 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 identiyt 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"

  authn_basic {
    priority     = 0
    pwd_hash     = "SHA-256"
    pwd_encoding = "BASE64"
  }

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

  id_sources = [iamtf_idvault.sso-users.name]

}

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("./provider.p12")
    password = "changeme"
    key_password = "secret"
  }

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

  exec_env = iamtf_execenv_tomcat.tc85.name

}

Create provider key pair

You need to provide a PKCS#12 keystore with a key pair for securing providers. You can use a self-signed certificate, or request one from your Certificate Authority.

• Generate a self signed key-pair using openssl

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj /CN=MyProvider
openssl pkcs12 -export -in cert.pem -inkey key.pem -out provider.p12 -name "provider"

Apply terraform configuration

terraform init

Once the plugin has been initialized, you can apply the changes to the server

terraform apply

Build and Start the Identity Appliance

iamtfctl start -a ida-1

Tips

You can configure iamtfctl credentials using environment variables or a configuration file

Manual installation 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.6.1:

unzip ~/Downloads/terraform-provider-iamtf_0.6.1_linux_amd64.zip
mkdir -p ~/.terraform.d/plugins/atricore/iamtf/0.6.1/linux_amd64
mv terraform-provider-iamtf ~/.terraform.d/plugins/atricore/iamtf/0.6.1/linux_amd64

Download this example

• main.tf
• ida-1.tf