Installing IdStory HUB

IdStory HUB is the new user dashboard. It can be used as a basis of user’s application catalog or company intranet page. HUB administrators can interactively configure list of applications and necessary authorization. For more information about HUB administration, see here.

Installation prerequisites

Installation prerequisites.

Package versions

IdStory HUB depends on following packages. Packages will be upgraded during HUB installation if you do not have sufficient versions already.

iam-app-cas >= 0.7
iam-app-czechidm >= 0.8
iam-app-directory-server >= 0.3

Service hostname

IdStory HUB utilizes OIDC protocol for user authentication and authorization and, as OIDC client, must be bound to some URL. For that, HUB needs to know its own hostname. You will be configuring the HUB’s hostname in later steps of the installation.

HTTPS certificates

IdStory HUB requires you to have proper certificate setup in the appliance. The default self-signed server certificate does not suffice.

If you use the appliance with default certificate, you have to replace it with proper server certificate signed with some certificate authority. The CA may be an internal or a mock one but the server certificate must not be self-signed.

You can replace server certificates manually using this howto.

Alternatively, you can instruct the HUB setup utility to generate new CA and server certificate for you during the HUB configuration.

CAS services

The HUB will put its own service registration hub-201.json into /data/volumes-shared/cas-services/. Make sure there is no other registered service with id 201.

Install the IdStory HUB

Install the HUB package

Install the HUB package using the OS package manager.

[root@localhost ~]# dnf install iam-app-hub

In case other packages were upgraded as dependencies, complete their upgrade. This means:

Resolving their configuration conflicts according to package update guide.
Restarting the updated services afterwards. Start the services one by one and ensure all of them started correctly.
- The dependent services consist of (but are not limited to) iam-directory-server, iam-cas and iam-czechidm. If this is your case, restart the iam-directory-server service as the first one.

Configure the HUB

The HUB comes with its own configuration utility iam-hub-first-setup. The utility will ask few questions and creates appropriate config files.

At this step, you must supply the hostname the HUB will run under. Fill in only the hostname, the /hub/ URL fragment is hardcoded and cannot be changed. If you do not supply the hostname, the utility will use system hostname instead.

The utility checks if the appliance HTTPS certificate is self-signed (Subject and Issuer are the same). If the certificate is self-signed, the script offers you to generate new set of certificates. This is useful mainly for development/testing purposes.

As for the remaining steps, do as instructed by the script.

Running the iam-hub-first-setup without hostname specified

[root@localhost ~]# cd /data/volumes/hub/
[root@localhost hub]# ./iam-hub-first-setup
# Generating MongoDB password.
Use hostname 'localhost.localdomain' to configure the HUB service? [y/n]: n
Hostname not confirmed. Exiting.
Please specify desired hostname as ./iam-hub-first-setup -n yourhostname.yourdomain when invoking the script.

Running the iam-hub-first setup with the hostname specified (and with certificate generation)

[root@localhost ~]# cd /data/volumes/hub/
[root@localhost hub]# ./iam-hub-first-setup -n iam.appliance.tld
# Generating MongoDB password.
Will generate config using 'iam.appliance.tld' hostname.
Use hostname 'iam.appliance.tld' to configure the HUB service? [y/n]: y
# Generating HUB's config files.
  Making backup : /data/volumes/hub/config/env.1706012860.bak
  Processing template env.tpl
  Making backup : /data/volumes/hub/config/AdminOidcTrustedDomains.js.1706012860.bak
  Processing template AdminOidcTrustedDomains.js.tpl
  Making backup : /data/volumes/hub/config/HubOidcTrustedDomains.js.1706012860.bak
  Processing template HubOidcTrustedDomains.js.tpl
  Making backup : /data/volumes/hub/config/hub-201.json.1706012860.bak
  Processing template hub-201.json.tpl
# Checking HUB's CAS service configuration...
  Creating new CAS service file /data/volumes-shared/cas-services/hub-201.json ...
  If you want to modify the configuration, please, do so manually.
  Config file: /data/volumes-shared/cas-services/hub-201.json .
  Last auto-generated version of config: /data/volumes/hub/config/hub-201.json
# Checking web-proxy configuration.
  HUB is already configured.
  If you want to modify the configuration, please, do so manually and restart the web proxy afterwards.
  Config file: /data/volumes/web-proxy/config/reverse_proxy.conf .
  HUB configuration snippet: /data/volumes/hub/config/reverse_proxy.snip .
# Checking web-proxy certificates.
  Web proxy certificate Subject and Issuer are the same. HUB does not work with self-signed certificates.
Do you want to replace current web-proxy certificates? This will create new local CA and server certificates. [y/n]: y
 Variables for certificate:
        hostname=iam.appliance.tld
        ipdev=ens18
        ipaddr=10.0.1.147
Generating RSA private key, 2048 bit long modulus (2 primes)
............................................................................................+++++
.........................................................+++++
e is 65537 (0x010001)
Signature ok
subject=CN = CA-iam.appliance.tld
Getting Private key
Generating RSA private key, 2048 bit long modulus (2 primes)
......+++++
......................................................+++++
e is 65537 (0x010001)
Signature ok
subject=CN = iam.appliance.tld
Getting CA Private Key
  CA and server certificates created.
  Making backup of current web certificate chain /data/volumes/web-proxy/secrets/current_web_cert.crt.1706012860.bak .
  Making backup of current web certificate key /data/volumes/web-proxy/secrets/current_web_cert.key.1706012860.bak .
  Deploying new certificates.
!!! Certificates deployed. Please restart following services: iam-web-proxy, iam-cas, iam-czechidm !!!
!!! For everything to work correctly, please import CA certificate /data/volumes-shared/cacerts/current_web_cert.crt into your browser. !!!

At this point, the IdStory HUB should be configured properly. Do all the steps as the script told you.

Start HUB services

Start the HUB service.

[root@localhost ~]# systemctl start iam-hub

The service takes some time to download docker images and boot up. When it boots up, it becomes accessible at https://yourhostname/hub. The HUB automatically redirects user to CAS to log in.

If the HUB is working properly, enable automatic start of necessary services.

[root@localhost ~]# systemctl enable --now iam-hub.service iam-hub-backup.timer

Giving users access to HUB

Please, consult the IdStory HUB admin documentation.