Installation and Administration Guide

• Introduction
  • Requirements
• System Installation
  • Enable HTTPs
  • External Authentication
  • Authorization
  • Email
  • Configure Themes
• System Administration
• Sanity Check Procedures
  • End to End testing
  • List of Running Processes
  • Network interfaces Up & Open
  • Databases
• Diagnosis Procedures
  • Resource availability
  • Remote Service Access
  • Resource consumption
  • I/O flows

Introduction

Welcome to the Installation and Administration Guide for the Identity Management - KeyRock Generic Enabler. This section will cover how to install, configure and administrate a working instance of KeyRock.

Requirements

In order to execute Keyrock, it is needed to have previously installed the following software:

• Node.js (http://nodejs.org/download/).
• Node Packaged Modules. It is usually included within Node.js (https://npmjs.org/).
• MySQL (https://www.mysql.com/)

System Installation

The following steps need to be performed to get Keyrock up and running:

• Download the software, using GitHub.

  git clone https://github.com/ging/fiware-idm
  

• Install all required libraries using NPM.

  cd fiware-idm
  npm install
  

• Configure the installation. To configure Keyrock you can copy the file named config.js.template to config.js.

  cp config.js.template config.js
  

• Edit it with the corresponding with basic info. Below you can see an example:

Configure port and host:

    config.host = 'http://localhost:3000';
    config.port = 3000

Configure database:

    config.database = {
        host: 'localhost',
        password: 'idm',
        username: 'root',
        database: 'idm',
        dialect: 'mysql'
    }

Configure session key:

    config.session = {
        secret: 'nodejs_idm'
    }

Configure password encryption:

    config.password_encryption = {
        key: 'nodejs_idm'
    }

• Create database, run migrations and seeders:

  npm run-script create_db
  npm run-script migrate_db 
  npm run-script seed_db 
  

• Launch the server:

  npm start
  

• You can also install forever.js to run it in a production environment:

  sudo npm install forever -g
  

• And then run the server using forever:

  forever start bin/www
  

• To know the status of the process you can run the next command:

  forever status
  

Enable HTTPs

Follow the next steps in order to enable the server to listen to HTTPs requests.

• Generate OpenSSL certificates.

  ./generate_openssl_keys.sh
  

• Enable HTTPs in config.js.

    config.https = {
        enabled: true,
        cert_file: 'certs/idm-2018-cert.pem',
        key_file: 'certs/idm-2018-key.pem',
        port: 443
    }

• Start server with admin rights

  sudo npm start
  

External Authentication

You can also configure the Identity Manager to authenticate users through other database.

• Copy file named custom_authentication_driver.js.template to custom_authentication_driver.js

  cp helpers/custom_authentication_driver.js.template helpers/custom_authentication_driver.js
  

• Edit custom_authentication_driver.js according to your user table schema.

• Enable use of driver in config.js file and customize database attributes.

    config.external_auth = {
        enabled: true,
        authentication_driver: 'custom_authentication_driver',
        database: {
            host: 'localhost',
            database: 'idm',
            username: 'root',
            password: 'idm',
            user_table: 'user',
            dialect: 'mysql'
        }
    }

Authorization

Configure Policy Decision Point (PDP) - IdM can perform basic policy checks (HTTP verb + path) - AuthZForce can perform basic policy checks as well as advanced

If authorization level is advanced you can create rules, HTTP verb+resource and XACML advanced. In addition you need to have an instance of authzforce deployed to perform advanced authorization request from a Pep Proxy. If authorization level is basic, only HTTP verb+resource rules can be created

In order to allow this characteristic you need to edit the config file:

    config.authorization = {
        level: 'basic', // basic|advanced
        authzforce: {
            enabled: false,
            host: 'localhost',
            port: 8080
        }
    }

Email

You can configure the IdM to send emails to users. Follow this tutorial to configure Postfix as a Send-Only SMTP Server on Ubuntu 14.04. Then edit config file:

    config.mail = {
        host: 'idm_host',
        port: 25,
        from: 'noreply@host'
    }

Email

You can configure the IdM to send emails to users. Follow this tutorial to configure Postfix as a Send-Only SMTP Server on Ubuntu 14.04. Then edit config file:

    config.mail = {
        host: 'idm_host',
        port: 25,
        from: 'noreply@host'
    }

Configure themes

You can customize the appearance of the web portal. By default there are two themes: default and fiwarelab.

Figure 1: IdM default view

Figure 2: IdM fiware view

You can change between these themes in config.js

    config.site = {
        title: 'Identity Manager',
        theme: 'default'   // default/fiwarelab
    };

Additionally you can customize your own theme. In order to do that follow these steps:

• Create a new subfolder in themes directory

  mkdir themes/example
  

• Generate _colors.scss, _styles.scss and style.scss

  cd themes/example && touch _colors.scss _styles.scss style.scss
  

• Add these lines to style.scss

/****************************** Default colors */
@import "../default/colors";

/****************************** Custom colors */
@import "colors";

/****************************** Default styles */
@import "../default/styles_call";

/****************************** Custom styles */
@import "styles"

• Edit _colors.scss. For example:

/****************************** Custom colors rewrite */

$brand-primary: purple;
$brand-secundary: orange;

• Change config.site to use the new theme:

    config.site = {
        title: 'Identity Manager',
        theme: 'example'   // default/fiwarelab
    };

Run the Identity manager and you will see the new appearance:

Figure 3: IdM custom view

You can also configure a new logo in _styles.scss.

/****************************** Custom styles rewrite */

.logo-header .brand {
  background-image: url(../img/example.png);
  width: 150px;
  background-size: 150px 37px;
}

.logo-header {
    float: left;
}

.presentation {
    .media {
        height: auto;
        footer {
            margin-top: 15px;
        }
    }
}

Furthermore you can customize the header, footer, presentation and help of your portal. To do that create a folder, generate files and then customize them.

mkdir themes/example/templates
cd themes/example/templates && touch _footer.ejs _header.ejs _presentation.ejs _help_about_items.ejs

System Administration

To manage the mysql database you can access the console running the following command and introducing the mysql password:

mysql -u [mysql_host] -u [username] -p

Sanity Check Procedures

The Sanity Check Procedures are the steps that a System Administrator will take to verify that an installation is ready to be tested. This is therefore a preliminary set of tests to ensure that obvious or basic malfunctioning is fixed before proceeding to unit tests, integration tests and user validation.

End to End testing

1. Verify that the host address of IdM can be reached. By default, web access will show a Login Page.
2. Acquire a valid username and password and access with those credentials. The resulting web page is the landing page of the IdM KeyRock Portal.
3. Verify that you can view the list of applications, organizations, etc.

List of Running Processes

• If you used forever, to know the status of the process you can run the next command:

 forever status

Network interfaces Up & Open

• If your run the server being HTTPs enabled the TCP port 443 should be accessible to the web browsers in order to load the IdM Portal.

Databases

If you have correctly populated the database when installing the GE, the connection with it is up and running.

The databases and tables needed are:

Figure 4: IdM databases table

Diagnosis Procedures

The Diagnosis Procedures are the first steps that a System Administrator will take to locate the source of an error in a GE. Once the nature of the error is identified with these tests, the system admin will very often have to resort to more concrete and specific testing to pinpoint the exact point of error and a possible solution. Such specific testing is out of the scope of this section.

Resource availability

• Verify that 2.5MB of disk space is left using the UNIX command 'df'

Remote Service Access

Please make sure port 443 is accessible.

Resource consumption

Typical memory consumption is 100MB and it consumes almost the 1% of a CPU core of 2GHz, but it depends on user demand.

I/O flows

Clients access the KeyRock Interface through the client’s Web Browser. This is simple HTTP traffic. It makes requests to the local database.