gluufederation/opendj repository overview

⁠Overview

Docker image packaging for OpenDJ.

⁠Versions

See Releases⁠ for stable versions. For bleeding-edge/unstable version, use gluufederation/opendj:5.0.0_dev.

⁠Environment Variables

The following environment variables are supported by the container:

• CN_CONFIG_ADAPTER: The config backend adapter, can be consul (default), kubernetes, or google.
• CN_CONFIG_CONSUL_HOST: hostname or IP of Consul (default to localhost).
• CN_CONFIG_CONSUL_PORT: port of Consul (default to 8500).
• CN_CONFIG_CONSUL_CONSISTENCY: Consul consistency mode (choose one of default, consistent, or stale). Default to stale mode.
• CN_CONFIG_CONSUL_SCHEME: supported Consul scheme (http or https).
• CN_CONFIG_CONSUL_VERIFY: whether to verify cert or not (default to false).
• CN_CONFIG_CONSUL_CACERT_FILE: path to Consul CA cert file (default to /etc/certs/consul_ca.crt). This file will be used if it exists and CN_CONFIG_CONSUL_VERIFY set to true.
• CN_CONFIG_CONSUL_CERT_FILE: path to Consul cert file (default to /etc/certs/consul_client.crt).
• CN_CONFIG_CONSUL_KEY_FILE: path to Consul key file (default to /etc/certs/consul_client.key).
• CN_CONFIG_CONSUL_TOKEN_FILE: path to file contains ACL token (default to /etc/certs/consul_token).
• CN_CONFIG_KUBERNETES_NAMESPACE: Kubernetes namespace (default to default).
• CN_CONFIG_KUBERNETES_CONFIGMAP: Kubernetes configmaps name (default to jans).
• CN_CONFIG_KUBERNETES_USE_KUBE_CONFIG: Load credentials from $HOME/.kube/config, only useful for non-container environment (default to false).
• CN_SECRET_ADAPTER: The secrets adapter, can be vault (default), kubernetes, or google.
• CN_SECRET_VAULT_VERIFY: whether to verify cert or not (default to false).
• CN_SECRET_VAULT_ROLE_ID_FILE: path to file contains Vault AppRole role ID (default to /etc/certs/vault_role_id).
• CN_SECRET_VAULT_SECRET_ID_FILE: path to file contains Vault AppRole secret ID (default to /etc/certs/vault_secret_id).
• CN_SECRET_VAULT_CERT_FILE: path to Vault cert file (default to /etc/certs/vault_client.crt).
• CN_SECRET_VAULT_KEY_FILE: path to Vault key file (default to /etc/certs/vault_client.key).
• CN_SECRET_VAULT_CACERT_FILE: path to Vault CA cert file (default to /etc/certs/vault_ca.crt). This file will be used if it exists and CN_SECRET_VAULT_VERIFY set to true.
• CN_SECRET_VAULT_ADDR: URL of Vault (default to http://localhost:8200).
• CN_SECRET_VAULT_NAMESPACE: Namespace used to access secrets (default to empty string).
• CN_SECRET_VAULT_KV_PATH: Path to KV secrets engine (default to secret).
• CN_SECRET_VAULT_PREFIX: Base prefix name used to build secret path (default to jans).
• CN_SECRET_VAULT_APPROLE_PATH: Path to AppRole (default to approle).
• CN_SECRET_KUBERNETES_NAMESPACE: Kubernetes namespace (default to default).
• CN_SECRET_KUBERNETES_CONFIGMAP: Kubernetes secrets name (default to jans).
• CN_SECRET_KUBERNETES_USE_KUBE_CONFIG: Load credentials from $HOME/.kube/config, only useful for non-container environment (default to false).
• CN_WAIT_MAX_TIME: How long the startup "health checks" should run (default to 300 seconds).
• CN_WAIT_SLEEP_DURATION: Delay between startup "health checks" (default to 10 seconds).
• CN_CERT_ALT_NAME: an additional DNS name set as Subject Alt Name in cert. If the value is not an empty string and doesn't match existing Subject Alt Name (or doesn't exist) in existing cert, then new cert will be regenerated and overwrite the one that saved in config backend. This environment variable is required only if oxShibboleth is deployed, to address issue with mismatched CN and destination hostname while trying to connect to OpenDJ. Note, any existing containers that connect to OpenDJ must be re-deployed to download new cert.
• CN_MAX_RAM_PERCENTAGE: Value passed to Java option -XX:MaxRAMPercentage.
• CN_JAVA_OPTIONS: Java options passed to entrypoint, i.e. -Xmx1024m (default to empty-string).
• CN_LDAP_AUTO_REPLICATE: enable replication automatically (default to true).
• CN_LDAP_REPL_CHECK_INTERVAL : Interval between replication check in seconds (default to 10).
• CN_LDAP_REPL_MAX_RETRIES: Maximum retries for auto-replication initialization (default to 10). After max. retries is reached, the process will be stopped regardless of replication status (may need to run the process manually).
• CN_LDAP_REPL_SOURCE: Address (example: ldap) used as source to replicate entries from (default to empty string).
• CN_LDAP_REPL_DISABLE_ON_EXIT: Automatically disable replication on exit (default to true).
• CN_LDAP_USE_SSL: Whether to use SSL connection to LDAP server (default to true).
• GOOGLE_PROJECT_ID: Google Project ID (default to empty string). Used when CN_CONFIG_ADAPTER or CN_SECRET_ADAPTER set to google.
• GOOGLE_APPLICATION_CREDENTIALS: Optional JSON file (contains Google credentials) that can be injected into container for authentication. Refer to https://cloud.google.com/docs/authentication/provide-credentials-adc#how-to⁠ for supported credentials.
• CN_GOOGLE_SECRET_VERSION_ID: Janssen secret version ID in Google Secret Manager. Defaults to latest, which is recommended.
• CN_GOOGLE_SECRET_MANAGER_PASSPHRASE: Passphrase for Janssen secret in Google Secret Manager. This is recommended to be changed and defaults to secret.
• CN_GOOGLE_SECRET_NAME_PREFIX: Prefix for Janssen secret in Google Secret Manager. Defaults to jans. If left jans-secret secret will be created.

⁠Deployment Requirements

⁠New Deployment

1. Generate ldap_password secret contains password for cn=Directory Manager, for example: Test1234#.

2. Generate ldap_truststore_password secret contains truststore password, for example:

   tr -dc 'a-zA-Z0-9' < /dev/urandom | fold -w 12 | head -n 1
   

   Copy

3. Create opendj.crt and opendj.key files, for example:

   openssl req \
       -x509 \
       -newkey rsa:2048 \
       -sha256 \
       -days 365 \
       -nodes \
       -keyout opendj.key \
       -out opendj.crt \
       -subj '/CN=demoexample.jans.io' \
       -addext 'subjectAltName=DNS:ldap,DNS:opendj'
   

   Copy

   Note that, pass extra DNS:<opendj-service-name> to match the k8s service name for OpenDJ.

   Prepare ldap_ssl_cert secret using the following command:

   cat opendj.crt | base64 -w0
   

   Copy

   Prepare ldap_ssl_key secret using the following command:

   cat opendj.key | base64 -w0
   

   Copy

4. Put secrets above in configuration.json (some keys are omitted):

   {
       "_secret": {
           "ldap_password": "<ldap_password>",
           "ldap_truststore_pass": "<ldap_truststore_password>",
           "ldap_ssl_cert": "<ldap_ssl_cert>",
           "ldap_ssl_key": "<ldap_ssl_key>"
       },
       "_configmap": {
           "optional_scopes": "[\"couchbase\", \"ldap\", \"redis\", \"sql\"]",
           "admin_email": "[email protected]",
           "hostname": "demoexample.jans.io",
           "city": "Austin",
           "country_code": "US",
           "orgName": "Gluu",
           "state": "TX"
       }
   }
   

   Copy

   If using charts' values.yaml, put respected secrets as seen in example below:

   config:
     ldapPassword: "<ldap_password>"
     ldapTruststorePassword: "<ldap_truststore_password>"
     configmap:
       cnLdapCrt: "<ldap_ssl_cert>"
       cnLdapKey: "<ldap_ssl_key>"
   

   Copy

⁠Migrated from existing setup

1. Create opendj_configuration_export.py in host:

   import os
   
   from jans.pycloudlib import get_manager
   
   manager = get_manager()
   
   # pull secrets for future use
   manager.secret.to_file("ldap_ssl_cert", "/tmp/opendj.crt", decode=True)
   manager.secret.to_file("ldap_ssl_key", "/tmp/opendj.key", decode=True)
   manager.secret.to_file("ldap_truststore_pass", "/tmp/ldap_truststore_password")
   manager.secret.to_file("encoded_ox_ldap_pw", "/tmp/ldap_password", decode=True)
   
   # converts and push to secrets
   manager.secret.from_file("ldap_ssl_cert", "/tmp/opendj.crt")
   manager.secret.from_file("ldap_ssl_key", "/tmp/opendj.key")
   manager.secret.from_file("ldap_password", "/tmp/ldap_password")
   

   Copy

2. Copy the script to one of existing pod and run it, for example:

   kubectl -n jans cp opendj_configuration_export.py jans-auth-xzddfi:/tmp/opendj_configuration_export.py
   
   # this script will create required files
   kubectl -n jans exec jans-auth-xzddfi:/tmp/opendj_configuration_export.py
   

   Copy

3. Download files generated by the script, for example:

   kubectl -n jans cp jans-auth-xzddfi:/tmp/ldap_password ldap_password
   kubectl -n jans cp jans-auth-xzddfi:/tmp/ldap_truststore_password ldap_truststore_password
   kubectl -n jans cp jans-auth-xzddfi:/tmp/opend.crt opendj.crt
   kubectl -n jans cp jans-auth-xzddfi:/tmp/opend.key opendj.key
   

   Copy

4. Prepare ldap_ssl_cert secret using the following command:

   cat opendj.crt | base64 -w0
   

   Copy

   Prepare ldap_ssl_key secret using the following command:

   cat opendj.key | base64 -w0
   

   Copy

5. Put secrets above in configuration.json (some keys are omitted):

   {
       "_secret": {
           "ldap_password": "<ldap_password>",
           "ldap_truststore_pass": "<ldap_truststore_password>",
           "ldap_ssl_cert": "<ldap_ssl_cert>",
           "ldap_ssl_key": "<ldap_ssl_key>"
       },
       "_configmap": {
           "optional_scopes": "[\"couchbase\", \"ldap\", \"redis\", \"sql\"]",
           "admin_email": "[email protected]",
           "hostname": "demoexample.jans.io",
           "city": "Austin",
           "country_code": "US",
           "orgName": "Gluu",
           "state": "TX"
       }
   }
   

   Copy

   If using charts' values.yaml, put respected secrets as seen in example below:

   config:
     ldapPassword: "<ldap_password>"
     ldapTruststorePassword: "<ldap_truststore_password>"
     configmap:
       cnLdapCrt: "<ldap_ssl_cert>"
       cnLdapKey: "<ldap_ssl_key>"
   

   Copy

⁠Deployment Strategy

1. Deploy single OpenDJ instance
2. Scale up OpenDJ instances and auto replication will occur by default (see also LDAP Replication⁠)
3. Run python3 /app/scripts/deregister_peer.py inside the container before removing any OpenDJ instance (in Kubernetes, we can use preStop hook instead)

⁠LDAP Replication

The replication process is automatically run when the container runs, only if these conditions are met:

1. There are multiple LDAP containers running in the cluster
2. The o=jans, o=site, o=metric backends have not been replicated nor have entries

Check the LDAP container logs to see the result and optionally run /opt/opendj/bin/dsreplication status inside the container.