/
Deploy Smart ID

Deploy Smart ID

This article includes updates for Identity Manager 5.0.1.

Smart ID deployment configuration release note

Prerequisites

Docker Compose V2

From Docker Compose V2 the compose features are integrated into the Docker platform. If you use Compose V2, use the command "docker compose" (instead of "docker-compose"), that is, remove the dash and replace it with a space. Smart ID will not be affected by Compose V2 and can be used as today.

Smart ID deployment recommendations

See Smart ID deployment recommendations.

Smart ID components requirements and interoperability

For more information on the full support of databases, operating systems, browsers, and more, see:

Docker prerequisites

  • Docker client and engine version 20.10.10 or later

  • Docker Compose version 1.25.5 or later and Docker Compose file version 3.7 or later

General prerequisites

  • Supported host operating systems:

    • Linux that supports the Docker and Docker Compose versions above

    • Windows on request 

  • Valid licenses for all components to be used.

  • A database must be installed and in running mode. Supported databases are listed in Smart ID deployment recommendations.

  • Valid Support account at https://support.nexusgroup.com

  • For online deployment, as described below, your hosts need internet access.

    • If this is a offline deployment, the docker containers needs to be downloaded and transferred to the hosts.

  • DNS records must be created for each application to each Smart ID host:

    DNS examples

    # Identity Manager idm.smartid.example.com selfservice.smartid.example.com admin.smartid.example.com tenant.smartid.example.com # Digital Access access.smartid.example.com # Physical Access physicalaccess.smartid.example.com pa-maintenance.smartid.example.com pa-arx.smartid.example.com # Messaging Hermod mb.smartid.example.com

    If you do not have the possibility to create DNS records, for example in a test environment, then you can add the wanted DNS records in your localhost file. Add them both on the Smart ID host and on the clients that you want to use to access Smart ID.

Install Docker and Docker compose

Installation of Docker and Docker compose varies depending on your operating system.

Install Docker

To install Docker, go to the official documentation (Install Docker Engine | Docker Documentation) and chose the system on which you plan to install it. Then follow the installation guide.

Install Docker compose

To install Docker compose, follow the installation guide (Install Docker Compose | Docker Documentation).

Rootless Docker

Docker engine is by default run as root. If you do not want to run containers with root, but with a specific user, read more here: 

Deploy Smart ID

Configure services

Create Smart ID user account (Not required for Digital Access)

To avoid any permission issues, it is recommended that you create a dedicated Smart ID user account and run the Smart ID applications on the user's home directory.

  1. On each host, create a user account for Smart ID and add that user to the docker group.

    Create Smart ID User Ubuntu

    sudo adduser --disabled-password --gecos "" --shell /bin/bash nexus sudo usermod -aG docker nexus

     

    Create Smart ID User CentOS

    sudo adduser -r -d /home/nexus --shell /bin/bash nexus sudo usermod -aG docker nexus

     

  2. Switch to a Smart ID user: 

    Switch to Smart ID user

    su - nexus

Download Smart ID files

  1. Browse to support.nexusgroup.com/ and login with your account.

    1. Click on Download Portal and click on Smart ID.

    2. Click on SmartID-<version>-deployment<release-date>.tgz to download the deployment file to your computer. Where <version> represents the version you want to download.

    3. Click on SmartID-<version>-configuration.zip to download the configuration file to your computer. Where <version> represents the version you want to download.
      This file contains standard Smart ID configurations that can later be uploaded to Identity Manager.

    4. Transfer the SmartID-<version>-deployment<release-date>.tgz file to your Smart ID hosts and extract it in your Smart ID home folder <SMARTIDHOME>/:

      Go to home folder of Smart ID user

      cd <SMARTIDHOME> tar -xzf SmartID-23.04.6-deployment230728.tgz

Edit environment variables

You must change at least these variables, see instructions below:

  • SMARTID_INGRESS_DOMAIN

  • DBHOST

  • TRAEFIK_ACME_EMAIL

Other variables are optional to change, but in a production environment you must change the credentials.

Set variables in the environment file to match your environment:  

  1. Open the environment file <SMARTIDHOME>/compose/smartid.env for editing. 

  2. Change timezone (TZ) to fit your environment.

  3. Change TRAEFIK_ACME_EMAIL to fit your deployment. You must do this even if you do not use ACME.

    Example: Change TRAEFIK_ACME_EMAIL

    TRAEFIK_ACME_EMAIL=smartid@example.com
  4. Change the database host (DBHOST) for Identity Manager, Hermod, or Digital Access to fit your deployment. If it is a test deployment and database is running on the same host, the host IP-address or the docker-ip of the Postgres deployment must be used. localhost or 127.0.0.1 will not work.

    Example: Change timezone and database host

    ### Global variables TZ=Europe/Stockholm DBHOST=jdbc:postgresql://postgresdb:5432 # DBHOST=jdbc:sqlserver://<SMARTID-DB-HOST>:1433 # DBHOST=jdbc:oracle:thin:@//<SMARTID-DB-HOST>:1521

  5. Change the version of Smart ID if needed: 

    Example: Change Smart ID Version

    ### Smart ID Version SMARTID_VERSION=23.04
  6. Change the value of SMARTID_INGRESS_DOMAIN to fit your deployment. It is recommended to use a sub-domain with wildcard for Smart ID. For example *.smartid.example.com and point that domain to your host.

    Example: Set Smart ID Ingress domain

    ### Ingress Configuration # Change the SMARTID_INGRESS_DOMAIN to your domain for example smartid.example.com ## Smart ID Ingress SMARTID_INGRESS_DOMAIN=<YOUR-SMARTID-DOMAIN> # Identity Manager Ingress IDM_OPERATOR_DOMAIN_PREFIX=idm IDM_ADMIN_DOMAIN_PREFIX=admin IDM_SELFSERVICE_DOMAIN_PREFIX=selfservice IDM_TENANT_DOMAIN_PREFIX=tenant # Hermod Ingress HERMOD_DOMAIN_PREFIX=mb # Physical Access Ingress PA_DOMAIN_PREFIX=physicalaccess PA_RABBITMQ_DOMAIN_PREFIX=pa-rabbitmq PA_MAINTENANCE_DOMAIN_PREFIX=pa-maintenance PA_ARX_DOMAIN_PREFIX=pa-arx
  7. Change database credentials
    To change the type or database name or password, change the following variables. If this is a test deployment, you don't have to change anything here. Note that the Physical Access database hosts is specified using the variable PA_DB_HOST.

    Example: Change database credentials

    # Database credentials IDM_DB_USER=idmuser IDM_DB_PASS= IDM_DB_NAME=idm ## Physical Access databases and Credentials PA_DB_USER=pauser PA_DB_PASS= PA_DB_NAME=pa PA_DB_TYPE=MSSQL # Change to your mssql hostname PA_DB_HOST=mssqldb ## Messaging Hermod database and Credentials HERMOD_DB_USER=hermoduser HERMOD_DB_PASS= HERMOD_DB_NAME=hermod ## Digital Access Databases and Credentials DA_DB_USER=dauser DA_DB_PASS= DA_DB_DRIVER=org.postgresql.Driver DA_DB_NAME_USER=da DA_DB_NAME_REPORT=da_report DA_DB_NAME_OATH=da_oath DA_DB_NAME_OAUTH2=da_oauth2

Bootstrap the sign and encrypt engine

It is crucial to perform the bootstrapping of the system correctly. See Bootstrapping the sign and encrypt engine for more information.

Initialize your deployment

To initialize the deployment:

  1. Make the initialization scripts executable if they are not already:

    Make init scripts executable

    cd <SMARTIDHOME>/docker/compose chmod +x init-smartid.sh (Run with sudo for Digital Access) chmod +x helperCreateLink.sh chmod +x helperFunctions.sh
  2. Run the initialization script for Smart ID. The script checks if docker and docker-compose are installed; if not, the script will exit. It creates docker networks, symbolic links, directories and users, and sets permissions for Smart ID.

    Run init script

    $ ./init-smartid.sh (Run with sudo for Digital Access) Preflight check: Docker is installed Preflight check: Docker-Compose is installed ---------------------------------------------------------------------------------------- Preparing SmartID for deployment... ----------------------------------------------------------------------------------------

    Then, the script asks a few questions:

    1. The script asks if bootstrap certificates should be created.

      Script snippet: ask for bootstrapping

      Should bootstrap certificates be created (Should only be used for non-production systems)? [Y/n]

      For a production deployment, type n for No. Then, the script will skip this step.

      For a test deployment, type y for Yes. Then the script will create self-signed certificates needed for the sign and encrypt engine.

    2. The script asks if a Postgres database should be deployed.

      Script snippet: ask for Postgres

      Should PostgreSQL be deployed (Should only be used for non-production systems)? [Y/n]

      For a production deployment, type n for No. Then, the script will skip this step.

      For a test deployment, type y for Yes. Then the script will create and start a Postgres database.

      Script snippet: ask for Postgres answered Yes

      Should PostgreSQL be deployed (Should only be used for non-production systems)? [Y/n] y Creating directories for PostgreSQL Deploying and starting PostgreSQL
    3. The script asks if traefik should be used as Ingres/proxy. Typing y for Yes will create acme.json and set the permissions.

      Not required for Digital Access. 

      Script snippet: ask for Traefik answered Yes

      Should Traefik be used as Ingress/Proxy? [Y/n] y Creating acme.json and setting permissions for ACME Copying Let´s Encrypt CA Certificate to ./cacerts
    4. The script asks if Digital Access will be deployed to the host. Typing y for Yes will create the user "pwuser" and set permissions.

      Script snippet: ask for Digital Access answered Yes

      Should SmartID Digital Access be deployed on this host? [Y/n] y Creating directories for Digital Access Creating pwuser for Digital Access and setting permissions to digitalaccess/services
    5. After that, the script finishes and you can proceed to the next step. See Edit environment variables.

      Script snippet: script ran successfully

      ---------------------------------------------------------------------------------------- Smart ID is now ready for deployment. Proceed to the next step by editing smartid.env to make the neccessary changes for your deployment. For documentation check https://doc.nexusgroup.com ----------------------------------------------------------------------------------------
  3. To see exactly what steps have been done, see the log file init-smartid.log after executing the script.

If there are any permission issues, for example to access the PostgreSQL database, make sure that you have permissions to access the Smart ID configuration and docker files.

 

Only for Digital Access and CentOS:
If you are deploying Digital Access on a CentOS >=7 and you want to use port 443, you must redirect the network traffic internally on the host. This can be done in many ways, here is one example. As a result of this you must also change the listening port for the Access Point to 9001. If this is not changed, the startup of the Access Point container will fail. The result after the change is that all incoming traffic on 443 will be redirected internally to 9001.

  1. Redirect traffic from 443 to 9001

    Redirect traffic

    iptables -t nat -I PREROUTING -p tcp --dport 443 -j REDIRECT --to-ports 9001 iptables -t nat -I OUTPUT -p tcp -d 127.0.0.1 --dport 443 -j REDIRECT --to-ports 9001
  2. Change listening port for Access Point in Digital Access Admin:

    1. Go to Manage System > Access Points.

    2. Click on the Service ID for the Access Point that you want to edit.

    3. Change Portal Port and Sandbox Port to 9001.

    4. Click Save.

    5. Publish the configuration.

Configure certificates (Not required for Digital Access)

Configure TLS certificate

This instruction is only valid for Identity Manager, Messaging and Physical Access. 

TLS in Digital Access are configured inside the application.

To change TLS Certificate:

  1. Make sure your certificate and key are in PEM format.

  2. Put your certificate and key in <SMARTIDHOME>/compose/certs.

  3. Change permissions of the certificate and key file:

    Example: Change permissions

    chmod 600 smartidtls_cer.pem chmod 600 smartidtls_key.pem
  4. Open <SMARTIDHOME>/compose/smartid.env for editing.

  5. Change the default certificates by editing the filenames smartidtls_cer.pem and smartidtls_key.pem:

    Example: Change default certificates

    TRAEFIK_TLS_DEFAULT_CERTIFICATE=smartidtls_cer.pem TRAEFIK_TLS_DEFAULT_CERTIFICATEKEY=smartidtls_key.pem

Enable Strict SNI

Strict server name indication (SNI) can be used as an extra security measure. By default, strict SNI is set to false.  

  1. Set TRAEFIK_TLS_STRICTSNI to true in smartid.env

    Enable Strict SNI

    TRAEFIK_TLS_STRICTSNI=true

Change Cipher Suites and TLS version

  1. Open <SMARTIDHOME>/docker/compose/traefik/config/traefik-tls.yml for editing.

    traefik-tls.yml

    tls: stores: default: defaultCertificate: certFile: /certs/{{env "TRAEFIK_TLS_DEFAULT_CERTIFICATE"}} keyFile: /certs/{{env "TRAEFIK_TLS_DEFAULT_CERTIFICATEKEY"}} options: default: sniStrict: {{env "TRAEFIK_TLS_STRICTSNI"}} minVersion: VersionTLS12 maxVersion: VersionTLS12 cipherSuites: - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305 - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305 - TLS_AES_128_GCM_SHA256 - TLS_AES_256_GCM_SHA384 - TLS_CHACHA20_POLY1305_SHA256 - TLS_FALLBACK_SCSV
  2. Add or delete any Cipher Suites.

  3. To change TLS version for traefik, use minVersion and maxVersionminVersion is the minimum allowed TLS version, and maxVersion is the maximum allowed TLS version. Default, the allowed version of TLS is 1.2.

    Note that some mobile devices do not have full support for TLS 1.3 and can cause compatibility issues.

    TLS Versions

    TLSv10 VersionTLS12 VersionTLS13

Start and verify services

Start ingress/proxy Traefik

This is only required at the first startup.

  • Start the ingress/proxy Traefik: 

    Start Traefik

    cd <SMARTIDHOME>/compose/traefik docker-compose up -d

The ingress Traefik has a dashboard were status can be viewed. It can be accessed at your host IP address at port 8080.

http://<SMARTID-HOST-IPADDRESS>:8080

Start Identity Manager

  1. Start the initialization of the database. This is only required at the first startup: 

    Initialize the database

    cd <SMARTIDHOME>/compose/identitymanager/updatedb docker-compose up
    1. Information is written on the screen, and if it was successful, you should see this text at the end:
      smartid-idm-updatedb exited with code 0

    2. To instead write all information only to the log file, add -d to the command, like this:
      docker-compose up -d

  2. Check the logs of the database initialization:

    Check logs for initialization

    cd <SMARTIDHOME>/compose/identitymanager/updatedb docker-compose logs -f
  3. Start Identity Manager components:

    1. Location of services

      Example - Location of Identity Manager services

      <SMARTIDHOME>/compose/identitymanager/admin <SMARTIDHOME>/compose/identitymanager/operator <SMARTIDHOME>/compose/identitymanager/tenant
    2. Start the services:

      Example - Start Identity Manager Admin

      cd <SMARTIDHOME>/compose/identitymanager/admin docker-compose up -d

       

Start Hermod

  • Start Hermod: 

    Start Hermod

    cd <SMARTIDHOME>/compose/messaging docker-compose up -d

Start Smart ID Self-Service

  • Start Smart ID Self-Service: 

    Start Self-Service

    cd <SMARTIDHOME>/compose/selfservice docker-compose up -d

Start Physical Access

  1. Give permission to use the logs/rabbitmq directory:

    Give permission

    cd <SMARTIDHOME>/compose/physicalaccess sudo chmod -R a+rw logs/rabbitmq/
  2. Start Physical Access with one or more PACS connectors. See the list of PACS connector services below.
    The services smartid-pa-rabbitmq, smartid-pa-scimapi and smartid-pa-maintenance must be started for all Physical Access use cases: 

    Syntax: Start Physical Access with PACS connectors

    cd <SMARTIDHOME>/compose/physicalaccess docker-compose up -d smartid-pa-rabbitmq smartid-pa-scimapi smartid-pa-maintenance [PACS_connector1 PACS_connector2]

     

    Example: Start Physical Access with ASSA ARX connector

    cd <SMARTIDHOME>/compose/physicalaccess docker-compose up -d smartid-pa-rabbitmq smartid-pa-scimapi smartid-pa-maintenance smartid-pa-arx

PACS

PACS connector service name

For more information

PACS

PACS connector service name

For more information

ASSA ARX

smartid-pa-arx

Set up integration with ASSA ARX

Bewator Omnis

smartid-pa-omnis

Set up integration with Bewator Omnis

Bravida Integra

smartid-pa-integra

Set up integration with Bravida Integra

Interflex IF-6040

smartid-pa-interflex

Set up integration with Interflex IF-6040

Kaba exos 9300

smartid-pa-kabaexos

Set up integration with Dorma Kaba Exos

RCO R-CARD M5 Admin API

smartid-pa-rcom5

Set up integration with RCO R-CARD M5 Admin API

RCO R-CARD M5

smartid-pa-rco

Set up integration with RCO R-CARD M5

Salto (we have 2 Salto: SALTO ProAccess and SALTO ProAccess SPACE)

smartid-pa-salto

Set up integration with Salto

Security Shells iSecure

smartid-pa-isecure

Set up integration with Security Shells iSecure for connection with HID controllers

SiPass

smartid-pa-sipass

Set up integration with SiPass Integrated

SiPort

smartid-pa-siport

Set up integration with SiPort

Unilock

smartid-pa-unilock

Set up integration with UniLock

Unison Pacom

smartid-pa-unison

Set up integration with Unison Pacom

PACS demo service

smartid-pa-demo

Set up PACS demo service

Start Digital Access

Digital Access must always be deployed on its own host. It can not be run together with other Smart ID Applications because it will use the hosts network. If you want to configure Digital Access in High availability or distributed mode using bridge network, see Set up high availability for Digital Access deployment (bridge network).

The bridge network setup will not work if you want to use an external radius client for authentication. In that case, follow the swarm setup in Deploy Digital Access component on Docker.

  1. Start Digital Access sub components, by going into the wanted component folder:

    Digital Access - services location

    <SMARTIDHOME>/compose/digitalaccess/accesspoint <SMARTIDHOME>/compose/digitalaccess/policy-service <SMARTIDHOME>/compose/digitalaccess/authentication-service <SMARTIDHOME>/compose/digitalaccess/administration <SMARTIDHOME>/compose/digitalaccess/distribution-service

     

    Example: Start Dígital Access Administration service

    cd <SMARTIDHOME>/compose/digitalaccess/administration docker-compose up -d

Verify services

Verify the Smart ID installation: 

  1. Verify each component, by browsing to the DNS names and the configured port, for example:

    Example DNS names

    Smart ID Self-Service: selfservice.smartid.example.com Smart ID Identity Manager: idm.smartid.example.com Smart ID Digital Access: digitalaccess.smartid.example.com Smart ID Physical Access: physicalaccess.smartid.example.com Smart ID Messaging (Hermod): hermod.smartid.example.com Traefik Ingress Dashboard: http://<SMARTID-HOST-IPADDRESS>:8080
    1. For Physical Access, verify the started Physical Access services by browsing to the DNS names, for example:

      Example DNS names

      Smart ID Physical Access: physicalaccess.smartid.example.com Physical Access RabbitMQ service: pa-rabbitmq.smartid.example.com Physical Access SCIM API: pa-scimapi.smartid.example.com Physical Access Maintenance: pa-maintenance.smartid.example.com Physical Access ASSA ARX connector: pa-arx.smartid.example.com

      Or browse to the IP address for all started services, for example:

      IP address

      https://<SMARTID-HOST-IPADDRESS>:<PORT>

      The default port for each Physical Access service can be found in Default ports in Smart ID.

  2. List all running docker containers:

    Example: List containers

    docker ps
  3. Check the logs:

    1. To check a log, go to the application folder, for example <SMARTIDHOME>/compose/identitymanager and run this command:

      Example: Check logs

      docker-compose logs -f <CONTAINER>
    2. To check all logs with tail, go to the application folder, for example <SMARTIDHOME>/compose/identitymanager and run this command:

      Example: Check all logs with tail

      docker-compose logs -f

Stop services

  • To stop a specific service, go to the application folder, for example <SMARTIDHOME>/compose/identitymanager/operator and run this command:

Stop services
... docker-compose stop

Configure Smart ID

Continue with Configure Smart ID.

Related content

Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions