Skip to main content

Docker

This section shows how to setup mID Provider using Docker Compose.

Prerequisites​

This section extends information on system requirements and Software. Any hardware retrospections needs to be handled before installing mID Provider(IAM) platform.

Software Prerequisites​

Hardware Prerequisites​

  • RAM 8GB
  • HARD DRIVE 20GB

Setting up your Environment​

Docker Compose relies on Docker Engine for any significant job, so make sure that Docker Engine is installed. Use the following commands to ensure the docker and docker compose is active and available in your system.

To ensure the docker is running

$ docker -v

If the above command fails, to start the docker use the following command

$ service docker start

To ensure the docker-compose is running

$ docker-compose  -v

Make sure that the package provided by the mID provider is available before proceeding further.

Docker Login​

Docker Login to Kobil private Repository hosted on Microsoft Azure Container Registry​

Login with your Kobil Repository credential set to the Microsoft Azure Container Registry (ACR). If you don’t have a Kobil private repository credential set, please contact KOBIL support.

$ docker login kobilsystems.azurecr.io

You will be prompted for the KOBIL “kobilsystems” username and password.

Usage: https://docs.docker.com/engine/reference/commandline/login/

Configuration of the mID Components​

Home Directory​

Extract the contents of the package provided by mID Provider.

cd /opt/kobil_iam_<version>

Copy this file to each machine in the folder defined in the previous step. This configuration needs to be edited for each machine separately.

Note: The directory or location can be chosen individually. The significance here is that the permission to start docker and docker-compose are fulfilled.

To up and run the application we need to do some configuration setup so let us start with the configuration part of it.

mID Provider(IDP)​

Edit Docker Compose File​

Below are the docker compose parameters to be configured for mID Provider:

Provide the domain of the mID provider

CLOUD_MASTER_DOMAIN = {tenant}.<host>

Eg:master.kobil.com

Provide the mID Provider port number

ADMIN_PORT=8444

Provide the Cloud Connector URL

REST_CONNECTOR_URL= https://<host>:<port>/

Eg: https://connector:8446/

Provide the token URL.

While using multi-tenant maintain the placeholder {realm}

TOKEN_URL=https://{realm}.<host>/digitanium/v3/token

Provide the keycloak Admin URL

KEYCLOAK_ADMIN_URL= https://localhost:8444/auth

Provide the keycloak Username and Password

These are optional parameters. If provided these credentials will be used to create the Admin User initially, else the credentials provided during registration will be used.

KEYCLOAK_USER= <username> Eg: admin

KEYCLOAK_PASSWORD=<password> Eg: admin123

Provide the DB VENDOR

DB_VENDOR=MSSQL

Supported DBs and the corresponding port values are listed below:

  • Oracle : 1521
  • Postgres : 5432
  • MySQL : 3306
  • MSSQL : 1433

Provide the database hostname.

No need to use protocol.

DB_ADDR=<DB_HOST>

Provide the database port number

DB_PORT=3306

Provide the database name

DB_DATABASE=<DB_NAME>

Provide the database username and password

DB_USER=<DB_USER>

DB_PASSWORD=<DB_PASSWORD>

Set true to disable SSL encryption

DISABLE_SSL=true

Set the Keycloak Log Level

Supported log levels are ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE and WARN.

KEYCLOAK_LOGLEVEL=INFO

ROOT_LOGLEVEL=INFO

Set the welcome screen theme

KEYCLOAK_WELCOME_THEME=kobil

If not set the default theme 'keycloak' will be used.

Set true to enable multi-tenant

ENABLE_TENANT=true

Set the 2FA token length

LOGIN_TOKEN_LENGTH_2FA=8

Set default theme to be used within mID

DEFAULT_THEME=kobil

If not set the default theme 'kobil' will be used.

These variables are needed only when you want to do clustering

JGROUPS_DISCOVERY_EXTERNAL_IP = <IP of MACHINE B, for MACHINE A & Vice Versa>

JGROUPS_DISCOVERY_PROTOCOL = JDBC_PING

JGROUPS_DISCOVERY_PROPERTIES=initial_hosts =<MACHINE A IP>[7600],<MACHINE B IP>[7600]

Supported JGROUPS_DISCOVERY_PROTOCOL values based on Database:

  • MYSQL : JDBC_PING
  • Oracle : JDBC_PING_ORACLE
  • Postgres : JDBC_PING_PG
  • MSSQL : JDBC_PING_MS

Now we are done with the mID provider configuration, let us proceed further with the mID connector configuration.

mID Connector​

The mID connector configuration consist of multiple task to be accomplished so make sure to edit connector properties and docker compose along with the truststore.jks and application.keystore.

Edit Connector Properties​

  • Open Command line
  • cd config
  • edit connector.properties
Modify the URL list stated below to match your mID Server(SSMS)​
  • v2.ssms.asm.svc
  • v2.ssms.asm.mgt
  • v2.ssms.pam.svc
  • v2.ssms.kernal.mgt
  • v2.ssms.secovid.mgt
  • v2.ssms.secovid.svc
  • Replace the value of v2.ssms.truststore.password with your truststore.jks password
  • Replace the value of v2.ssms.capassword with your truststore.jks password
  • Replace SSMS_HOSTNAME with your SSMS host.
Modify the Credentials as stated below with Operator and Portal Credentials from your mID Server(SSMS)​

  • v2.ssms.mgt.username to be assigned with Operator Username that holds the SSMS Role 'Admin'.

  • v2.ssms.mgt.password to be assigned with Operator Password

  • v2.ssms.svc.username to be assigned with Portal Username

  • v2.ssms.svc.password to be assigned with Portal Password

    Role can be modified, or permissions could be restricted to make use of limited functionality.

Multi-tenant Support​
  • To enable multitenant, set ENABLE_TENANT environment variable to true in docker-compose file.
  • In case multitenant is enabled each API request should include below headers
    • Mgmt_Authorization - Management Credentials - Format: username: password
    • Por_Authorization - Portal Credentials - Format: username: password
Log Level​

Defines the Log Level options: ALL, INFO, WARN, ERROR

Edit Docker Compose​

Below are the docker compose parameters to be configured for mID connector:

Set true to disable SSL encryption

DISABLE_SSL = true

Set true to enable multi-tenant

ENABLE_TENANT = true

Set to true to run Redis in cluster mode (OR) false to run in non-cluster mode

REDIS_CLUSTER_MODE = false

Provide the host and port number where redis is running

REDIS_HOST = redis:6379

Provide the password that has been set during the redis db configuration

REDIS_PWD=<REDIS_AMIN_PWD>

Create application.keystore​

ssl.crt​
  • Certificate file of your server
ssl.key​
  • Private key
Steps to Generate Private key​
  • Step 1 openssl pkcs12 -export -in ssl.crt -inkey ssl.key -out abc.p12 ​
  • Step 2 keytool -importkeystore -srckeystore abc.p12 -srcstoretype PKCS12 -destkeystore application.keystore -deststoretype JKS

truststore.jks​

  • This is the trust store file of your SSMS.

Edit Application configuration​

  • Open Command line.
  • cd kobil-rest-connector
  • cd appconfig
  • Edit application.yml for below parameters
  • key-store-password - Assign with keystore password you set during keystore creation
  • key-alias - Assign with keystore alias you set during keystore creation

The configuration part of mID connector is completed, let us switch to the Nginx Gateway configuration.

Nginx Gateway​

Following steps will enable Nginx server:

Step 1

  • Open Command line.
  • cd build
  • cd kobil-nginx-gateway
  • Open nginx.conf file
  • Search for key {HOST}
  • Replace the value with your server address
  • Search for key {APP_NAME}
  • Replace the value with your application name

Step 2

  • Open Command line.
  • cd build
  • cd certs
  • Replace dhparam.pem, ssl.crt, ssl.key, application.keystore files respective to your server
  • Open default.conf file
  • Search for key {HOST}
  • Replace the value with your host name

Make sure all the above steps are completed in Nginx Gateway to proceed into further configuation part.

mID Pooler​

Edit Docker Compose​

Below are the docker compose parameters to be configured for mID Pooler:

Set to true to run Redis in cluster mode (OR) false to run in non-cluster mode

REDIS_CLUSTER_MODE=false

Provide the host and port number where redis is running

REDIS_HOST=redis:6379

Provide the password that has been set during the redis db configuration

REDIS_PWD=<REDIS_AMIN_PWD>

Ensure the configuration part of mID pooler is completed before switching into further configuation part.

Redis​

Edit Docker Compose​

Set the password for the redis db

REDIS_PWD=<REDIS_AMIN_PWD>

Note: The password set here must be used for mID Connector and mID Pooler as well.

Now we are done with all the configuration setup, let us proceed further to run the docker compose.

Run Docker Compose​

This command will pull images from the private Kobil “kobilsystems” ACR. You need to be logged into ACR.

$ docker-compose up -d

Note: Docker hub login is a mandatory before executing this command*

Use Kobil Image from ACR​

Default and initial docker-compose configuration files are covering references to Kobil Docker repository "kobil" which is not longer used for saving updated Kobil images.

Kobil GmbH moved to Microsoft Azure Container Registry (ACR) hosting all Kobil Service Images in private registry "kobilsystems" now. Along with the move from Docker to Azure also the repository (pathes) are changed for the Kobil Images which requires the following changes to the existing sample docker-compose.yaml files.

  • Change the Registry service (logoff from docker hub / run docker login kobilsystems.azurecr.io)
  • Change the repository image path (edit the docker-compose.yaml file)

Current sample docker-compose.yaml code section may look like below covering the image reference to "kobil" (which is the docker-hub reference):

connector:
  image: "kobil/kobil-cloud-connector:2.4.1"
  logging:
    driver: loki
    options:
      loki-url: "http://localhost:3100/loki/api/v1/push"
            ...
  ports:
    - "8446:8446"
  container_name: kobil_rest_connector
  restart: always

The image references to "kobil/kobil-cloud-connector:2.4.1" which is in context of the existing "docker login" to the docker-hub registry "kobil". This needs to be changed to have an active login to ACR "kobilsystems". For this doing a "docker logout kobil" on the used host - followed by a "docker login kobilsystems.azurecr.io" using the private Kobil provided repository access credentials.

Checking the given default source "docker-compose.yaml" we have to modify as below to the new image references. Find the new pathes which in ACR are very different to the "kobil" docker registry.

image: "nginx:1.20.1-alpine"                  <remains>
image: "kobil/kobil-cloud-connector:2.4.1"    kobilsystems.azurecr.io/idp/ssms-connector:2.4.1
image: "redis:5.0.8"                          <remains>
image: "kobil/kobil-cloud-pooler:2.4.1"       kobilsystems.azurecr.io/idp/ssms-pooler:2.4.1
image: "kobil/kobil-health-check:1.8.1"       kobilsystems.azurecr.io/idp/health-check:1.8.1
image: "kobil/kobiliam:2.4.2"                 kobilsystems.azurecr.io/idp/core:2.4.2
image: grafana/loki:latest                    <remains>
image: grafana/promtail:latest                <remains>
image: grafana/grafana:master                 <remains>

Once modified the "docker-compose.yaml" covering the new image references and having at host/runtime level for the docker runtime a new successful login to "kobilsystems.azurecr.io" the docker-compose.yaml is ready for startup. At processing level and network layer nothing changes.

Uninstallation of mID Provider​

Navigate to the extracted package folder

$ cd /opt/kobiliam

Run following command to uninstall IAM and connector containers

$ sudo /usr/local/bin/docker-compose down

Run following command to remove images

$ sudo /usr/local/bin/docker-compose down --rmi 'all'

Docker Hub Logout​

Log out from a Docker registry.

$ docker logout

Usage: https://docs.docker.com/engine/reference/commandline/logout/

Upgrade​

Check for latest releases

mID Provider Versions: https://midprovider.developer.kobil.com/versions/

  • Review all the changes incorporated as a part of the respective release notes and prepare for an update.
  • Back up old installation (Database, Configuration, Certificates, Themes, and so on).
  • As a best practice, test all upgrades or patches in a non-productive environment, to prevent any installation issues from being exposed in production environment.
  • Be aware that after an upgrade, the database will no longer be compatible with old installations.
  • Make sure to update supported packages like connector, pooler if necessary. Same information will be provided as a part of the release notes.
  • If it is just a version update or patch update and you do not have any certificate or other critical configuration updates, then an easiest way is to edit the “docker-compose” file in the respective package to reflect latest versioning and prepare for upgrade.
  • Once the changes are complete, execute the following commands to start upgrades.

Run following command to pull images from KOBIL docker Hub.

$ docker pull <image_to_update>

Note: Docker hub login is a mandatory before executing this command*

Run following command to stop docker compose

$ docker-compose down

Run the following command to start docker compose.

$ docker-compose up -d