Skip to main content
Skip table of contents

Deploy Smart ID

This article includes updates for Smart ID 23.04.

All the components in the Smart ID Workforce solution are deployed as Docker containers, except Smart ID Certificate Manager (CM) and Nexus OCSP Responder

Smart ID deployment configuration release note

Smart ID deployment configuration release notes
CODE
All notable changes to this project will be documented in this file. Be aware that the [Unreleased] features are not yet available in the official tagged builds.

## [Release 23.10.2-2023-10-27]

### Added

### Changed
- Modified permissions of the 'certs' directory in init-smartid.sh to 755 (to allow Hermod to read the directory). [CRED-16526]
- Updated Prime Connectors version. [CRED-16153]

## [Release 23.04.9-2023-10-31]

### Added

### Changed
- Modified permissions of the 'certs' directory in init-smartid.sh to 755 (to allow Hermod to read the directory). [CRED-16526]

## [Release 23.04.7-2023-08-28]

### Added
- Added missing attestation key config to signencrypt.xml (fixes VSC). [CRED-16128]  

## [Release 23.04.5-2023-07-17]

### Added
- Added a readme-wsl-dev.txt how to setup SmartID Docker containers in a WSL environment. [CRED-15948]
- Added environment variable to docker-compose.yml of authentication service.

### Changed
- Restored environment references for Digital Access and Physical Access containers [CRED-15915]

## [Release 23.04.4-2023-06-30]

### Added
- Added restart-all.sh for easy stopping and starting of all containers or a subset of them. [CRED-15854]

### Changed
- The variable DOCKER_NETWORK_MTU has the default value 1500 now. You are not forced to choose between several options. [CRED-15854]
- When executing init-smartid.sh a message informs you about the current MTU value and when it is recommended to reduce it. [CRED-15854]
- The names of most of the docker containers start with "smartid-" by default. This prefix can be changed now via variable DOCKER_CONTAINER_BASE_NAME in file smartid.env. [CRED-15854]
- The hostname of the postgresql container now has the DOCKER_CONTAINER_BASE_NAME prefix as well.

## [Release 23.04.3-2023-06-23]

### Added

- Added AriadNext Connector Docker image. [CRED-14963] 
- Added file .gitattributes to make \*.sh and \*.env files always containing only LF instead of any CRLF. Fixed file datadog.env accordingly. [CRED-15795]

### Changed

- Escaped the ESC character (0x1B) in echo statements of shell scripts to avoid problems with Azure file preview and git diff output. [CRED-15795]


## [Release 23.04.2-2023-06-02]

### Added

### Changed

## [Release 23.04.1-2023-05-11]

### Added

- Added init-smartid.env to configure the docker network MTU. [CRED-14088 via CRED-15316]
- Added helperFunctions.sh and helperCreateLink.sh to be used by init-smartid.sh. [CRED-14088 via CRED-15316]

### Changed

- Replace deprecated docker network syntax in docker-compose.yml files. [CRED-14088 via CRED-15316]
- init-smartid.sh / stop-smartid.sh detect if docker needs sudo. [CRED-14088 via CRED-15316]
- init-smartid.sh now optionally removes files created by previous runs (postgres db, bootstrapped certs, etc). [CRED-14088 via CRED-15316]
- No explicit setting of env_file in docker-compose.yml files. [CRED-14088 via CRED-15316]
- Messaging database is now configured via MESSAGING_DB_URL var. [CRED-14088 via CRED-15316]
- stop-smartid.sh now uses the compose command "down" instead of "stop", which also removes the containers after shutting them down. [CRED-14088 via CRED-15316]

## [Release 23.04.0-2023-04-28]

### Added

- Added Workspace One Connector Docker image. [CRED-14215] 

### Changed

## [Release 22.10.8-2023-11-27]
 
### Added
  
### Changed
- Modified permissions of the 'certs' directory in init-smartid.sh to 755 (to allow Hermod to read the directory). [CRED-16526]

## [Release 22.10.0-2022-09-20]

### Added

- Added ContentProviderJWSSigner descriptor in signencrypt.xml. [CRED-12232]
- Added renewFromKeypairs.sh to renew end-entity certs.

  WARNING:

  - This only works if you (re-)bootstrap with the updated createca.sh, as the old version discarded data required for renewal.
  - Re-bootstrapping will invalidate any encrypted secrets and history signatures in IDM due to chaning the keys.
  - Re-bootstrapping will also overwrite the certificates and keys in the docker deployment folder, so make a backup first,
    so you can use the respective tools for re-signing and re-encrypting existing history/secrets.

### Changed

- automatically (re-)start mailhog
- fixed naming of traefik rules for mobile-iron
- Changed createca.sh to retain keypairs and CA metadata, so we can enable renewal (see above).
- Removed cRLSign attribute from ca.conf to avoid issues with failing CRL checks.
  NOTE: This only has an effect on newly bootstrapped CAs.

## [Release 22.04.0-2022-05-05]

### Added

- Added Mobile Iron Docker image. [CRED-11817]
- Added new properties for MI image in smartid.env. [CRED-11817]

### Changed

- Changed properties for Nexus GO Cards API V2. [CRED-12951]

## [Release 21.10.0-2021-11-09]

### Added

- Added Digicert Global Root CA certificate. [CRED-11688]
- Added some Let's Encrypt root certificates. [DEVOPS-971]
- Added documentation for maxProfiles option to hermod-conf.yml
- Added `.yamllint` file to set default YAML linting config. [DEVOPS-1085]
- Added volume mapping for logs folder in IDM and Self Service. [DEVOPS-403]
- Fixed cacerts folder permissions in init-smartid.sh script.
- Added support for docker compose v2 command in init-smartid.sh script.

### Changed

- New properties for CAAS credentials in smartid.env (placeholders must be replaced before using Nexus GO Cards). [CRED-11688]
- Fixed some copy issues in the init-smartid.sh script.
- Changed the default selfservice config to include auth methods params example.
- It is now possible to change IDM language settings via system properties. [DEVOPS-860]
- It is now possible to change Self-Service configuration via `CONFIG_JSON` environment variable. [DEVOPS-945]
- Fixed typo. [DEVOPS-1090]
- Replaced Self-Service `IDM_URL`, `INSTANCE_ID`, `IDM_TENANT` by `APPLICATION_YAML` json. [DEVOPS-1127]
- Set logging driver to json-file (the default one) for all containers explicitly [DEVOPS-1136]
- Fixed YAML format. [DEVOPS-1085]
- IDM and SelfService now support custom translations and do not require mapping the whole translation files again. See doc for more info. [DEVOPS-1118]
- Change Import Logger to correct class [DEVOPS-1143]
- Switched to new image naming for IDM
  - `nexus-prime/explorer` changed to `smartid/identitymanager/operator`
  - `nexus-prime/designer` changed to `smartid/identitymanager/admin`
  - `nexus-prime/tenant` changed to `smartid/identitymanager/tenant`
  - `nexus-prime/updatedb` changed to `smartid/identitymanager/updatedb`
  - `nexus-prime/ussp2` changed to `smartid/selfservice`
- Changed Smart ID version to 21.10.0

### Removed

- Removed Self-Service config.json file. [DEVOPS-945]
- Removed expired Let's Encrypt certificates. [DEVOPS-971]
- Removed translation files for IDM and SelfService. [DEVOPS-1118]

## [Release 21.04.0-2021-05-20]

### Added

- Default values for Selfservice tenant id and instance id. [DEVOPS-738]
- Added example format for MSSQL everywhere we build the DB URL (`${DBHOST}/${XX_DB_NAME}`) because MSSQL requires a different URL format. [DEVOPS-737]
- Include SANs from CSR in bootstrap TLS cert in `bootstrap/conf/ca.conf`.
- Generate tls certificate for non-treafik setup in `bootstrap/createca.sh`.
- Log4j2 config and template for json layout [DEVOPS-758]
- Datadog agent compose file, with some examples, see nexus and datadog documentation if you want to use it [DEVOPS-759]
- Added a check in `init-smartid.sh` that exits the script if user didn't fill the mandatory properties in `smartid.env` (thoose with <XX> value pattern). [DEVOPS-759]
- Added Physical Access Interflex PACS. [DEVOPS-752]

### Changed

- IDM DB will no longer be initialized through init-smartid.sh script. Initialisation has to be done manually by starting container in identitymanager/updatedb. [DEVOPS-739]
- Rename containers to use dash instead of underscore, so containerName can work for DNS lookup (underscore is not allowed in DNS names).
  WARNING! This can cause issues if you use the new config with existing containers using the old names!
- Align idm update db naming to use the name "updatedb" everywhere
  WARNING! This can cause issues if you use the new config with existing containers using the old names!
- Align digital access directory names with service names
- fix bootstrap cert folder permissions in init script
- Changed all HERMOD*\* properties to MESSAGING*\*. [DEVOPS-751]
- Moved each component's respective config into their own config folder. [DEVOPS-751]
- Made all volume mappings static in compose file, no more properties. [DEVOPS-751]
- Reorganized smartid.env to be split by component, making it easier to find component related properties. [DEVOPS-751]
- Internal ports (inside docker) are now static in the compose file. [DEVOPS-751]
- Moved postgres related properties outside smartid.env, because it is a separate tool not meant for production. [DEVOPS-751]
- Renamed service names in compose files to match their container name. [DEVOPS-751]
- Changed traefik version to 2.4.8. [DEVOPS-638]
- Changed file extension of generated certificates from `.base64` to `.cer`.
- Updated translation files for IDM. [DEVOPS-761]
- Updated Messaging config for 21.04 (Hermod version 3.1.1). [DEVOPS-802]
- Changed chmod command to give permission 700 instead of 600, because hermod needs execute permission.
- Updated SmartID version to 21.04

### Fixed

- Fixed typos in the strings that are echoed to the user during the initialisation. [DEVOPS-646]

### Removed

- Removed unused properties in smartid.env. [DEVOPS-751]
- Removed unused ports for Physical Access. [DEVOPS-752]
- Removed Physical Access config files. Configuration is now handled using environment variables. [DEVOPS-752]
- Removed TZ from all docker-compose files. Since it is set in `smartid.env` which is mapped using `env_file`, declaring the variable a second time in `env` was not necessary.

## [Release 20.11.2-2021-03-23]

### Added

- If you say Yes to the question if Digital Access shall be deployed in the host, it will make it possible for the containers to listen on 80 and 443. [DEVOPS-540]

### Changed

- Bump SmartID version to 20.11.2
- Updated IDM translation files with newer ones. [DEVOPS-561]
- Adjust volumes for hermod certificates. [DEVOPS-651]
- Removed Selfservice hotfixes introduced in previous release. [DEVOPS-626]

### Fixed

- Fixed tenant startup by removing mapped sign encrypt configuration, so it uses the default one from inside the container. Since IDM Tenant uses less certificates, the same config as IDM operator or admin cannot be used.[DEVOPS-640]
- Fixed the copy_files.sh script used in IDM operator, admin and tenant [DEVOPS-692] + [DEVOPS-656]

## [Release 20.11.1-2021-02-18]

### Added

- Added issuing and root CA certificates to IDM containers for config signing (These certs should NEVER be used for production). [DEVOPS-549]
- Added hotfix for SelfService -> IDM connection [DEVOPS-626] Has to be removed with 20.11.2+

### Changed

- Update sign-encrypt engine to the newest state. [DEVOPS-549]
- Update version number to 20.11.1

## [Release 20.11.0-2021-02-01]

### Added

- Added mailhog as tool in /tools/mailhog. The tool can be used to test to send emails in Digital Access and Identity Manager. [DEVOPS-482]

### Changed

- Set false on traefik network in the traefik, adminer and mailhog to be enabled in traefik by default. [DEVOPS-486]
- Changed file extension of generated certificates from `.crt` to `.base64`
- Changed so that identity manager Admin and Operator do not require signed configurations/modules for uploading and downloading them by default. [DEVOPS-515]

### Fixed

- Fix environment variable usage inside traefik config file. [DEVOPS-514]

## [Release 20.11.0-2020-12-22]

### Added

- Added support for selfservice branding. [DEVOPS-471]
- Added log4j volume mapping for idm containers. [DEVOPS-470]

### Changed

- Updated traefik version to 2.3.4 [DEVOPS-464]
- Renamed selfservice container from "idm_selfservice" to "selfservice".
- Renamed all environment variables starting with "IDM_SELFSERVICE_x" to "SELFSERVICE_x".
- Changed Hermod config to disable by default some end-points and to hide sensitive data in logs. [DEVOPS-484]
- Improved the `stop-smartid.sh` script to handle dynamically all docker-compose stop commands and to work regardless of where the script is called from.
- Improved the `init-smartid.sh` script to work regardless of where the script is called from.
- Improved the `createca.sh` script to work regardless of where the script is called from.
- Renamed `idm-selfservice-language.json` to `idm-selfservice-config.json`.

### Fixed

- Fixed volume mapping for selfservice tomcat server.xml by using a separate variable than identitymanager.
- Fixed French translations for IDM and Selfservice.

## [Release 20.11.0-2020-12-07]

### Added

- Added `postgres/init/init-smartid-databases.sql` so that Physical Access database is created when starting up postgres. The "pauser" is created, and a default password is set.
- Added LE CA Certificate to cacerts. [DEVOPS-455]
- Added AJP port variables in smartid.env and use them in identitymanager docker-compose files. Also added AJP Connector in `config/idm-tomcat-server.xml`, which has to be enabled manually (and port set accordingly). [DEVOPS-348]
- Add following new features to the identitymanager docker-compose files: [DEVOPS-406]
  - Support for new CA store volume mapping
  - Support for new system properties environment variable
  - Support for new DB properties environment variables
  - Support for new spring bean volume mapping. See `IDM_VOLUME_PATH_SPRING` in `smartid.env`.
  - Support for new jars volume mapping. See `IDM_VOLUME_PATH_LIBS` in `smartid.env`.
  - Support for new class files volume mapping. See `IDM_VOLUME_PATH_CLASSES` in `smartid.env`.
- Add following new features to the selfservice docker-compose file: [DEVOPS-406]
  - Support for new CA store volume mapping
  - Support for new IDM url environment variable
- Added adminer as tool [DEVOPS-407]
- Added maxVersion for TLS to be 1.2 due to compatibility issues with some mobile devices. [DEVOPS-413]

### Changed

- Changed smartid version to 20.11.0.
- Moved "/certs/boostrap" to "/boostrap".
- Changed postgres version in smartid.env from 9.6.18 to 12.5. [DEVOPS-431]
- Split identity manager containers into their own docker-compose files: [DEVOPS-382]
  - Added `identitymanager/admin/docker-compose.yml`
  - Added `identitymanager/tenant/docker-compose.yml`
  - Added `identitymanager/init-db/docker-compose.yml`
  - Added `identitymanager/operator/docker-compose.yml`
- Adapted `init-/stop-smartid.sh`, and paths inside `smartid.env` and some docker-compose files to fit new docker-compose yaml files. [DEVOPS-382]
- Change the ini-smartid.sh script to ask if traefik is going to be used as Ingress/proxy. [DEVOPS-408]
- Changed in `config/hermod-conf.yml` some values to <IDM-HOST-HERE> and <DA-HOST-HERE> on client samples.

### Removed

- Removed MSSQL from deployment package, since Physical Access now support postgres. [DEVOPS-448]
- Removed unnecessary variables in `smartid.env`.
- Removed identitymanager compose docker-compose file. [DEVOPS-382]
- Removed entrypoint definition from identitymanager docker-compose files. [DEVOPS-406]
- Removed pgAdmin and portainer and its variables from smartid.env. [DEVOPS-407]
- Removed modern and old options for tls in `config/traefik/traefik-tls.yml`. [DEVOPS-413]
- Removed TRAEFIK_TLS_OPTION from smartid.env. [DEVOPS-413]
- Removed identitymanager spring beans because we changed how handle them.
- Removed samples.

## [Release 20.06.1-2020-10-27]

### Added

- Added port forwarding to hermod container in the messaging docker-compose file.
- Added spring bean files for identitymanager in `config/idm/spring_operation` and spring_admin.
- Added translation files for identitymanager in `config/idm/translation_id`m and for selfservice in `config/idm/translation_selfservice`.
- It is now possible to enable Strict SNI using TRAEFIK_TLS_STRICTSNI=true

### Changed

- changed smartid version to 20.06.1.
- Changed HERMOD_DOMAIN_PREFIX from "mb" to "messaging".
- Changed the DB init/update script behavior, can be controlled with `IDM_DBUPDATE_SCRIPT` in smartid.env.
- Changed `traefik-tls.toml` file to YAML and used variables from .env file. Possibility to change TLS certificate file names TRAEFIK_TLS_DEFAULT_CERTIFICATE and TRAEFIK_TLS_DEFAULT_CERTIFICATEKEY.
- Improved the `init-smartid.sh` script.
- Moved seflservice to a separate docker-compose file.

### Fixed

- Fixed the jdbc url for `config/da-admin-customize.conf`.

### Removed

- Dropped `restart: always` for identittymanager init-db.
- Removed explicit DBHOST naming in `smartid.env` to force user to set its own value.

## [Release 20.06.0-2020-09-28]

### Added

- Added possibility to add custom-beans for IDM Operator and Admin, in `config/idm`.
- Added possibility to change translation for IDM Operator, Admin, Selfservice and Tenant.
- Added IDM_DB_QUARTZ example for MSSQL, Oracle and DB2.
- Added `container_name` for all containers in:
  - identitymanager/docker-compose.yml
  - traefik/docker-compose.yml
- Added docker hostname for postgresdb DB_HOST in `postgres/docker-compose.yml`, this will make test deployment work from start.
- Added docker hostname for mssqldb PA_DB_HOST in `mssql/docker-compose.yml`.
- Added `restart: always` to all containers. All containers will the start up after re-boot, if they have been started once before.
- Included SAML example files for IDM in `/samples/idm_saml`.

### Changed

- Changed smartid version to 20.06.0.
- Changed explorer/operator url in `idm-selfservice-application.yml`.
- Changed location of Identity Manager SAML samples files from `/docker/compose/examples` to `/samples/idm_saml`.
- Updated `init-smartid.sh`:
  - Now check if docker and docker-compose are installed, if not the script will exit.
  - Now asks if the deployment is a production deployment, if "Yes", the script will complete and deployment configuration can be done. If "No":
    - Ask if postgres and/or mssql shall be deployed and started.

### Fixed

- Moved comments in `smartid.env` file to be on a separate line instead of behind the value. This was breaking the applications since comments would be evaluated as part of the value.
- Fixed `init-smartid.sh` so that it works properly on CentOS.
- Fixed a typo for variable `IDM_DB_QUARTZ`.
- Fixed typo in idm-operator container in `identitymanager/docker-compose.yml`, in the path to the castore.jks.

## Removed

- Removed `init-smartid-test.sh`, it is included in init-smartid.sh. 

Prerequisites

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

Kubernetes is supported, but there is no example configuration available.

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

    CODE
    # 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

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

    Create Smart ID User CentOS

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

    <SMARTIDHOME>

    <SMARTIDHOME> refers to /home/nexus, but this can be different depending on the setup.


  2. Switch to a Smart ID user: 

    Switch to Smart ID user

    CODE
    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

      CODE
      cd <SMARTIDHOME> 
      tar -xzf SmartID-23.04.6-deployment230728.tgz
    5. The structure of sub folders in the Smart ID home directory, <SMARTIDHOME>/, is as follows: 

      Sub folder structure of Smart ID home

      CODE
      .
      └── docker
          └── compose
              ├── bootstrap
              │   ├── cacerts
              │   │   ├── DST-Root-CA-X3-b64.cer
              │   │   └── Lets-Encrypt-Authority-X3-b64.cer
              │   ├── conf
              │   │   ├── ca.conf
              │   │   ├── idm-deviceenc.conf
              │   │   ├── idm-encryption.conf
              │   │   ├── idm-signconfig.conf
              │   │   ├── idm-signemail.conf
              │   │   ├── tls-client.conf
              │   │   └── tls-san.conf
              │   └── createca.sh
              ├── digitalaccess
              │   ├── access-point
              │   │   └── docker-compose.yml
              │   ├── administration-service
              │   │   └── docker-compose.yml
              │   ├── authentication-service
              │   │   └── docker-compose.yml
              │   ├── config
              │   │   ├── da-admin-customize.conf
              │   │   └── da-auth-customize.conf
              │   ├── distribution-service
              │   │   └── docker-compose.yml
              │   └── policy-service
              │       └── docker-compose.yml
              ├── identitymanager
              │   ├── admin
              │   │   └── docker-compose.yml
              │   ├── config
              │   │   ├── translations
              │   │   │   ├── general.properties
              │   │   │   ├── general_de.properties
              │   │   │   ├── general_fr.properties
              │   │   │   └── general_sv.properties
              │   │   ├── log4j2.xml
              │   │   ├── log4j2JsonLayout.json
              │   │   ├── signencrypt.xml
              │   │   └── tomcat-server.xml
              │   ├── operator
              │   │   └── docker-compose.yml
              │   ├── tenant
              │   │    └── docker-compose.yml
              │   └── updatedb
              │      └── docker-compose.yml
              ├── messaging
              │   ├── config
              │   │   └── hermod-conf.yml
              │   └── docker-compose.yml
              ├── physicalaccess
              │   ├── data
              │   │   └── demo
              │   │       ├── AccessGroups.json
              │   │       └── Users.json
              │   └── docker-compose.yml
              ├── postgres
              │   ├── init
              │   │   └── init-smartid-databases.sql
              │   └── docker-compose.yml
              ├── selfservice
              │   ├── config
              │   │   ├── branding
              │   │   │   └── default
              │   │   │       ├── logo.png
              │   │   │       └── theme.css
              │   │   ├── translations
              │   │   │   ├── ar.json
              │   │   │   ├── de.json
              │   │   │   ├── en.json
              │   │   │   ├── fr.json
              │   │   │   └── sv.json
              │   │   ├── config.json
              │   │   ├── log4j2.xml
              │   │   ├── log4j2JsonLayout.json
              │   │   └── tomcat-server.xml
              │   └── docker-compose.yml
              ├── tools
              ├── traefik
              │   ├── config
              │   │   └── traefik-tls.yml
              │   └── docker-compose.yml
              ├── init-smartid.sh
              ├── init-smartid.env
              ├── helperCreateLink.sh
              ├── helperFunctions.sh
              ├── smartid.env
              ├── restart-all.sh
              ├── stop-smartid.sh
              ├── readme-wsl-dev.txt
                └── tools
                  └── adminer
                      └── docker-compose.yml
      
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

    CODE
    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.

    Digital Access

    Digital Access requires its own host and cannot be deployed at the same hosts as the other applications.

    Example: Change timezone and database host

    CODE
    ### 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

    If you are using an MSSQL Database, you need to change the format of the Database URLs at the following places:

    <SMARTIDHOME>/docker/compose/smartid.env

    CODE
    DA_DB_URL=${DBHOST}/${DA_DB_NAME_REPORT}
    # If you are using MSSQL, you need the following DB URL format:
    #DA_DB_URL=${DBHOST};DatabaseName=${DA_DB_NAME_REPORT}
    
    IDM_DB_URL=${DBHOST}/${IDM_DB_NAME}
    # If you are using MSSQL, you need the following DB URL format:
    #IDM_DB_URL=${DBHOST};DatabaseName=${IDM_DB_NAME}
    
    MESSAGING_DB_URL=${DBHOST}/${MESSAGING_DB_NAME}
    # If you are using MSSQL, you need the following DB URL format:
    #MESSAGING_DB_URL=${DBHOST};DatabaseName=${MESSAGING_DB_NAME}

    MSSQL JDBC SSL encryption

    The sqlserver jdbc driver has ssl encryption enabled by default. To disable it, see "Example: cod-hermod.yml" under heading "If needed, edit Hermod configuration" in the Hermod configuration in Install Hermod.

    If you are NOT using certificate authentication with Smart ID Mobile App (the Personal mobile authentication method) but are provisioning users through Digital Access only, you must update this setting:

    <SMARTIDHOME>/docker/compose/digitalaccess/config/da-auth-customize.conf

    YML
    wrapper.java.additional.30=-Dauthentication.personal.challenge_key_id=signer
  5. Change the version of Smart ID if needed: 

    Example: Change Smart ID Version

    CODE
    ### 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

    CODE
    ### 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

    CODE
    # 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
Initialize your deployment

To initialize the deployment:

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

    Make init scripts executable

    CODE
    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

    BASH
    $ ./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 a Postgres database should be deployed.

      Script snippet: ask for Postgres

      BASH
      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

      BASH
      Should PostgreSQL be deployed (Should only be used for non-production systems)? [Y/n] y
      Creating directories for PostgreSQL
      Deploying and starting PostgreSQL
    2. 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

      CODE
      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
      
    3. 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

      BASH
      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
    4. After that, the script finishes and you can proceed to the next step. See Edit environment variables.

      Script snippet: script ran successfully

      BASH
      ----------------------------------------------------------------------------------------
      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

    CODE
    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

    CODE
    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

    CODE
    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

    CODE
    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

    CODE
     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

    CODE
    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

    CODE
    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.

CODE
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

    CODE
    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

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

    1. Location of services

      Example - Location of Identity Manager services

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

      Example - Start Identity Manager Admin

      CODE
      cd <SMARTIDHOME>/compose/identitymanager/admin
      docker-compose up -d
Start Hermod
  • Start Hermod: 

    Start Hermod

    CODE
    cd <SMARTIDHOME>/compose/messaging
    docker-compose up -d
    
Start Self-Service
  • Start Self-Service: 

    Start Self-Service

    CODE
    cd <SMARTIDHOME>/compose/selfservice
    docker-compose up -d
    
Start Physical Access
  1. Give permission to use the logs/rabbitmq directory:

    Give permission

    CODE
    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

    CODE
    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

    CODE
    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

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

    CODE
    <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

    CODE
    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

    CODE
    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

      CODE
      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

      CODE
      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

    CODE
    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

      CODE
      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

      CODE
      docker-compose logs -f

Stop services

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

Stop services
CODE
...
docker-compose stop

Configure Smart ID

Continue with Configure Smart ID.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.