Quick Start

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


docker run \
        --name josso \
        --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 \

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.1.4:

$ mkdir ~/.terraform.d/plugins/atricore.com/iam/josso/0.1.4/linux_amd64
$ copy terraform-provider-josso ~/.terraform.d/plugins/atricore.com/iam/josso/0.1.4/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 JOSSO provider, 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)


terraform {
  required_providers {
    josso = {
      version = "~> 0.1.4"
      source  = "atricore.com/iam/josso"


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

provider "josso" {
  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. JOSSO can run multiple appliances simultaneously, so all resources must be defined in the context of an appliance. The resource is josso_identity_appliance

resource "josso_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 JOSSO 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 josso_idvault.

resource "josso_idvault" "sso-users" {
  ida  = josso_identity_appliance.ida-1.name
  name = "sso-users"

The next step is to define our identity provider. josso_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 "josso_idp" "idp" {
  ida  = josso_identity_appliance.ida-1.name
  name = "idp"

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

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


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.

JOSSO 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 "josso_execenv_tomcat" "tc85" {
  ida         = josso_identity_appliance.ida-1.name
  name        = "tc85"
  description = "Tomcat 8.5"
  version     = "8.5"
  depends_on  = [josso_idp.idp]

resource "josso_app_agent" "partnerapp1" {
  ida          = josso_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         = josso_idp.idp.name
    is_preferred = true

  exec_env = josso_execenv_tomcat.tc85.name

  depends_on = [
    josso_idp.idp, josso_execenv_tomcat.tc85


Last Updated:
Contributors: Sebastian