Directory/LDAP identity source

This tutorial describes how to integrate IAM.tfopen in new window with a Directory server. User will be authenticated by JOSSO with an LDAP Bind (connection) to the server using the retrieved user credentials (user identifier and password). In order to use a Directory server as the identity source for user and role information, an LDAP server accessible from the IAM.tfopen in new window erver. The TCP/IP ports involved in an LDAP session are the 389 and the 636 for SSL. IAM.tfopen in new window will work with any LDAPv3 supporting server.

Prerequisites

Before starting, make sure that the following prerequisites are meet.

Tips

You may want to set the password expiration policy to never to prevent future problems.

Configuration

The first step is to define the elements that represent the Identity Provider (IdP) in the Identity Appliance. The following components must be added to the configuration:

  • Identity Appliance: represents the configuration

  • SAML Identity Provider: represents the core set of identity services.

  • LDAP Identity Source: represents the user repository, and the rules to retrieve user and role information.

  • Directory Service Authentication: represents the repository used to authenticate users by performing binds.

  • IAM.tfopen in new window Partner Application: The resource represents the sample application, it holds information about the application base URL

  • Tomcat Execution Environment: This elements represents the Tomcat server where the application is running. Here you can specify the server version, etc.

iamtf_identity_appliance

First let's create a main.tfopen in new window file to contain the provider configuration, and the identity appliance resource definition: iamtf_identity_appliance. This file can also contain configuration for the IAM.tfopen in new window server, like server endpoint, client id and client secret. One of the key configuration elements is the location property. This is the base URL that users will use to access IAM.tfopen in new window services. In this example we use http://localhost:8081, but normally this will be set to something like https://mysso.mycompany.com

main.tfopen in new window

terraform {
  required_providers {
    iamtf = {
      version = "~> 0.6.1"
      source  = "atricore/iamtf"
    }
  }
}

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"
}

resource "iamtf_identity_appliance" "mysso-01" {
  name        = "mysso-01"
  namespace   = "tf.iam.mysso01"
  description = "Appliance #1"
  location    = "http://localhost:8081"
}

iamtf_idp

This defines the identity provider element in our configuration. You will need a public/private key pair, that you can easily generate using openssl. In our example, we are using directory based authentication: authn_bind_ldap, this means that the idp will perform an LDAP bind with the credentials entered by the user. If succeeds, the user is considered authenticated. This is useful to avoid accessing passwords directly from the LDAP server. Properties used by the authn_bind_lda element are similar to those used by the iamtf_idsource_ldap identity source element (see below)

Take a look at iamtf_idp reference for more information.

idp-1.tfopen in new window

resource "iamtf_idp" "idp-1" {

  ida  = iamtf_identity_appliance.mysso-01.name
  name = "idp-1"

  // pkcs#12 keystore with private key/certificate
  keystore {
    resource = filebase64("./saml.p12")
    password = "changeme"
  }

  // directory based authentication
  authn_bind_ldap {
    priority          = 0
    provider_url      = "ldap://openldap:1389"
    username          = "cn=admin,dc=devsso1,dc=atricore,dc=com"
    password          = "secret"
    authentication    = "simple"
    password_policy   = "none"
    perform_dn_search = false

    // Users
    users_ctx_dn      = "ou=users,dc=devsso1,dc=atricore,dc=com"
    userid_attr       = "uid"

    saml_authn_ctx    = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
    referrals         = "follow"
    operational_attrs = true

  }

  id_sources = [iamtf_idsource_ldap.sso-users.name]

}

iamtf_idsource_ldap

This element refers to the directory server where user and role information is stored. The following properties need to be configured, the configuration can be devided into thre groups: Connection, Users and Groups.

Take a look at iamtf_idsource_ldap reference for more information.

Connection

The set of properties used to identify and connect to the directory server.

  • provider_url The ldap server URL, normally in the form: ldap[s]😕/server:port, where protocol can be ldap or ldaps (for secure connections). Make sure that the port matches the protocol.
  • username the DN of the user to be used by to bind to the LDAP Server when retrieving user and role information (service account)"cn=admin,dc=devsso1,dc=atricore,dc=com"
  • password the password to be used for binding to the LDAP Server.

Users

Details on how to obtain user information from the directory server.

  • users_ctx_dn the fixed distinguished name for the context to search for user accounts, when SUBTREE is set as * search_scope, users will also be searched in sub-contexts.
  • userid_attr the name of the attribute that contains the user identifier. This is used to locate the user.
  • user_attributes a list of attributes to be retrieved from the directory and to be used as user claims. Each user_attributes is defined by mapping the name of the attribute in the directory and the name of the claim to be reported to applications.

Groups

  • groups_ctx_dn the fixed distinguished name to the context to search for user roles.
  • groupid_attr the attribute containing the role name
  • groupmember_attr the name of the attribute that, in the object containing the user roles, references role members (users). The attribute value should be the DN (or UID, see Role Matching Mode above) of the user associated with the role. This is used to locate the user roles.

Tips

Since IAM.tfopen in new window relays on Java JNDI support, you must ensure that the LDAP server certificate is configured as trusted in the JDK instance used by IAM.tfopen in new window when using LDAPS (SSL).

For Active Directory, we must use the following values:

  • username : either the service account full DN, or in the form of DOMAIN/user
  • userid_attr : sAMAccountName
  • groupmember_attr : member
  • groupid_attr : sAMAccountName

In our example, we’re using OpenLDAP

sso-users.tfopen in new window

resource "iamtf_idsource_ldap" "sso-users" {

    ida             = iamtf_identity_appliance.mysso-01.name
    name            = "sso-users"
    
    // Connection
    provider_url    = "ldap://openldap:1389"
    username        = "cn=admin,dc=devsso1,dc=atricore,dc=com"
    password        = "secret"

    // Groups
    groups_ctx_dn   = "ou=groups,dc=devsso1,dc=atricore,dc=com"
    groupid_attr    = "cn"
    groupmember_attr = "member"

    // Users
    users_ctx_dn    = "ou=users,dc=devsso1,dc=atricore,dc=com"
    userid_attr     = "uid"

    // User attributes
    user_attributes {
        attribute = "cn"
        claim = "first_name"
    }

    user_attributes {
        attribute = "sn"
        claim = "last_name"
    }

    user_attributes {
        attribute = "mail"
        claim = "email"
    }

}

Downloads

You can download the example files here:

Last Updated:
Contributors: Sebastian, fbosch