Edit on GitHub

Installing GrantID on Rocky Linux

Follow these steps to install an on-premises instance of GrantID on Rocky Linux.

Tip

Before you start, make sure you have completed the steps outlined on Planning before installation

Prerequisites

  • Rocky Linux 8.x or greater
[!include[Install ASP.NET Core Runtime 8.0](../../../includes/linux/rocky/install-aspnetcore-80.md)]

Install Nginx

Note

If you prefer to use Apache instead of Nginx, see this article.

Install Nginx (if not already installed):

yum install nginx
systemctl enable nginx.service
systemctl start nginx.service

Test that Nginx is running:

curl -I http://localhost/

Check the first lines of the output, which should be similar to:

HTTP/1.1 200 OK
Server: nginx/...
...

Edit the Nginx configuration:

nano /etc/nginx/nginx.conf

Delete or comment out (with #s) the entire server section, located right below the clause include /etc/nginx/conf.d/*.conf;. After commenting out the section, the configuration file should look similar to this:

...

http {
    ...

    # Load modular configuration files from the /etc/nginx/conf.d directory.
    # See http://nginx.org/en/docs/ngx_core_module.html#include
    # for more information.
    include /etc/nginx/conf.d/*.conf;

#    server {
#        listen       80 default_server;
#        listen       [::]:80 default_server;
#        server_name  _;
#        root         /usr/share/nginx/html;
#
#        # Load configuration files for the default server block.
#        include /etc/nginx/default.d/*.conf;
#
#        location / {
#        }
#
#        error_page 404 /404.html;
#            location = /40x.html {
#        }
#
#        error_page 500 502 503 504 /50x.html;
#            location = /50x.html {
#        }
#    }

    ...
}

Install GrantID

GrantID is composed of three components:

  • Identity Service: contains the business logic and encapsulates access to the database
  • Auth Server: accessed by end-users during logins, redirects and sign-ups
  • Console: allows administrators to manage the system

We'll first do some initial setup, then we'll install each component.

Initial setup

Download and extract the distribution package to its own directory, then enter it:

curl -O https://cdn.lacunasoftware.com/grantid/grantid-5.0.1.tar.gz
tar -xzf grantid-5.0.1.tar.gz --one-top-level
cd grantid-5.0.1

Create a local user to run the components:

mkdir /var/grantid
useradd --system --home-dir /var/grantid grantid
chown grantid:grantid /var/grantid
chmod 750 /var/grantid

Create the folder that will contain the binaries for each component and copy the binary files over:

mkdir /usr/share/grantid
cp -r components/* /usr/share/grantid/
chmod -R a=,u+rwX,go+rX /usr/share/grantid
Note

Component binaries can be read by any user and can only be changed by root users. This means that the application user (grantid) can read but not change the files, which is intentional.

Create the folder that will contain the configuration files and copy over the configuration file templates:

mkdir /etc/grantid
cp config-templates/* /etc/grantid/
chown -R root:grantid /etc/grantid
chmod -R a=,u+rwX,g+rX /etc/grantid
Note

Configuration files can only be read by members of the grantid group and can only be changed by the root user. This is important to protect sensitive data stored on the configuration files from unauthorized access.

Generate a self-signed certificate to sign the JSON Web Tokens. Provide the information below, pressing ENTER on the remaining questions. Avoid using diacritics ("accents" e.g. á, ã, ç etc).

  • Country Name: enter the two-letter code of your country, e.g.: BR
  • State or Province Name: enter the name of your organization's state, e.g.: Sao Paulo
  • Organization Name: enter the name of your organization, e.g. Patorum Inc
  • Common Name: enter the name of your GrantID instance, e.g. Patorum ID
openssl genrsa -out key.pem 2048
openssl req -x509 -new -days 36500 -key key.pem -out cert.pem

Merge the key and certificate into a single PFX file. When asked for a password, simply press ENTER twice.

openssl pkcs12 -export -in cert.pem -inkey key.pem -out /etc/grantid/issuer.pfx

Do some housekeeping:

chown root:grantid /etc/grantid/issuer.pfx
chmod 640 /etc/grantid/issuer.pfx
rm key.pem cert.pem

Generate a key used to encrypt "tokens" sent on emails:

openssl rand -base64 -out /etc/grantid/temp-token-key 32
chown root:grantid /etc/grantid/temp-token-key
chmod 640 /etc/grantid/temp-token-key

Edit the common configuration file:

nano /etc/grantid/common.json

Fill the following settings:

  • Section Application
  • Section PkiSuite
    • SdkLicense: your license for the PKI SDK, in Base64 format
    • WebLicense: your license for the Web PKI component in binary (Base64) format. Required if you intend to enable login with X.509 certificates.
Note

As mentioned on the planning section, you should ideally have a valid SSL certificate for the domains. If you don't have a certificate yet, use URLs with http:// above and set UseSSL to false.

Identity Service

We'll now install the Identity Service component. Edit the configuration file:

nano /etc/grantid/identity-service.json

Fill the following settings:

  • Section ConnectionStrings
  • Section SMS: configures the SMS sending. The setting Type defines which provider should be used, and the remaining settings depend on the provider chosen:
    • Twilio
      • Type: set this setting to Twilio to send SMS messages using Twilio
      • MessageFrom: the sender phone number provided by Twilio (e.g.: +12125550000)
      • AccountSid: the account SID, provided by Twilio
      • AuthToken: the authentication token, provided by Twilio
    • TotalVoice
      • Type: set this setting to TotalVoice to send SMS messages using TotalVoice
      • AccessToken: the access token, provided by TotalVoice (e.g.: 0123456789abcdef0123456789abcdef)
    • Simulator (for debugging purposes only)
      • Type: set this setting to Simulator to simulate sending SMS messages (but instead only log the messages that would be sent)
Note

If you don't intend to configure SMS sending at this time, disable phone verification for console users by editing the common configuration file common.json, under the Application section set RequirePhoneVerification to false.

  • Section Email: configures email sending through SMTP
    • ServerHost: hostname of the SMTP server
    • Username and Password: if the SMTP server requires authentication, set these settings
    • SenderAddress: email address to be used as sender (from field)
    • SenderName: name to be used as the sender name (optional)
    • EnableSsl: by default, the SMTP conversation is performed over SSL. To disable SSL, set this setting to false
    • ServerPort: by default, the SMTP conversation is performed over port 587. Set this setting to use a different port
    • Support: Address written on the footer of outgoing e-mails, e.g. support@patorum.com
    • LogoUrl (optional): Public URL of the image that is used on the header of outgoing emails. If omitted, the GrantID logo will be used.
Note

If you don't intend to configure email sending at this time, disable email verification for console users by editing the common configuration file common.json, under the Application section set RequireEmailVerification to false.

Create the service, then enable and start it:

cp service-defs/grantid-identity-service.service /etc/systemd/system/
systemctl enable grantid-identity-service
systemctl start grantid-identity-service
systemctl status grantid-identity-service

The expected output is similar to:

* grantid-identity-service.service - GrantID Identity Service
   Loaded: loaded (/etc/systemd/system/grantid-identity-service.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2020-01-21 14:45:34 UTC; 3h 46min ago
 Main PID: 776 (dotnet)
    Tasks: 26 (limit: 3527)
   CGroup: /system.slice/grantid-identity-service.service
           └─776 /usr/bin/dotnet Grant.Id.Service.dll

Jan 21 14:45:34 ubuntu1804 systemd[1]: Started GrantID Identity Service.
Jan 21 14:45:44 ubuntu1804 grantid[776]: Signing certificate PFX path: '/etc/grantid/grantid.pfx', password: ''
Jan 21 14:45:44 ubuntu1804 grantid[776]: Audit is enabled
Jan 21 14:45:50 ubuntu1804 grantid[776]: Hosting environment: Linux
Jan 21 14:45:50 ubuntu1804 grantid[776]: Content root path: /usr/share/grantid/identity-service
Jan 21 14:45:50 ubuntu1804 grantid[776]: Now listening on: http://localhost:5010
Jan 21 14:45:50 ubuntu1804 grantid[776]: Application started. Press Ctrl+C to shut down.

If necessary, restart the service: systemctl restart grantid-identity-service. If something seems wrong, check the logs: journalctl -u grantid-identity-service

Note

If the logs show an exception stating that an error occurred during the pre-login handshake or that the remote certificate was rejected, add ;TrustServerCertificate=True to your connection string on the file /etc/grantid/identity-service.json as a workaround

To test that the service is running, run:

curl http://localhost:5010/api/version

The version of the component should be outputted.

Note

The Identity Service component does not need to be publicly accessible. If your applications don't call GrantID's APIs directly, you can skip the remainder of this section and go to the Auth Server installation

Create a site configuration file for the component:

nano /etc/nginx/conf.d/grantid-identity-service.conf

Enter the following, replacing the server_name entry with your API domain:

server {
    listen        80;
    listen        443 ssl;  # comment if you don't have an SSL certificate yet

    # Replace with your API domain
    server_name   api.id.patorum.com;

    # Path of the SSL certificate and key (comment if you don't have an SSL certificate yet)
    ssl_certificate      /etc/ssl/certs/grantid.pem;
    ssl_certificate_key  /etc/ssl/private/grantid.key;

    location / {
        proxy_pass         http://localhost:5010;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Allow services to make network requests:

setsebool -P httpd_can_network_connect on

Test the Nginx configuration and reload it:

nginx -t
nginx -s reload

Test the site (replace api.id.patorum.com with your API domain):

curl -H "Host: api.id.patorum.com" http://localhost/

Auth Server

We'll now install the Auth Server component.

Note

Typically, the Auth Server does not need any additional configuration, so there's nothing to fill on /etc/grantid/auth-server.log

Create the service, then enable and start it:

cp service-defs/grantid-auth-server.service /etc/systemd/system/
systemctl enable grantid-auth-server
systemctl start grantid-auth-server
systemctl status grantid-auth-server

The expected output is similar to:

* grantid-auth-server.service - GrantID Auth Server
   Loaded: loaded (/etc/systemd/system/grantid-auth-server.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2020-01-21 14:45:35 UTC; 4h 28min ago
 Main PID: 868 (dotnet)
    Tasks: 24 (limit: 3527)
   CGroup: /system.slice/grantid-auth-server.service
           └─868 /usr/bin/dotnet Grant.Id.AuthServer.dll

Jan 21 14:45:35 ubuntu1804 systemd[1]: Started GrantID Auth Server.
Jan 21 14:45:44 ubuntu1804 grantid[868]: Signing certificate PFX path: '/etc/grantid/grantid.pfx', password: ''
Jan 21 14:45:47 ubuntu1804 grantid[868]: Hosting environment: Linux
Jan 21 14:45:47 ubuntu1804 grantid[868]: Content root path: /usr/share/grantid/auth-server
Jan 21 14:45:47 ubuntu1804 grantid[868]: Now listening on: http://[::]:5011
Jan 21 14:45:47 ubuntu1804 grantid[868]: Application started. Press Ctrl+C to shut down.

If necessary, restart the service: systemctl restart grantid-auth-server

To test that the service is running, run:

curl -H "X-Forwarded-Proto: https" http://localhost:5011/

The source for an HTML document should be outputted.

Create a site configuration file for the component:

nano /etc/nginx/conf.d/grantid-auth-server.conf

Enter the following, replacing the server_name entry with your base and login domains:

server {
    listen        80;
    listen        443 ssl;  # comment if you don't have an SSL certificate yet

    # Replace with your base domain and your login domain
    server_name   id.patorum.com  login.id.patorum.com;

    # Path of the SSL certificate and key (comment if you don't have an SSL certificate yet)
    ssl_certificate      /etc/ssl/certs/grantid.pem;
    ssl_certificate_key  /etc/ssl/private/grantid.key;

    location / {
        proxy_pass         http://localhost:5011;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_buffer_size       16k;
        proxy_busy_buffers_size 16k;
    }
}

Test the Nginx configuration and reload it:

nginx -t
nginx -s reload

Test the site (replace id.patorum.com with your base domain):

curl -H "Host: id.patorum.com" http://localhost/

Console

We'll now install the Console component.

Note

Typically, the Console does not need any additional configuration, so there's nothing to fill on /etc/grantid/console.log

Create the service, then enable and start it:

cp service-defs/grantid-console.service /etc/systemd/system/
systemctl enable grantid-console
systemctl start grantid-console
systemctl status grantid-console

The expected output is similar to:

* grantid-console.service - GrantID Console
   Loaded: loaded (/etc/systemd/system/grantid-console.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2020-01-21 19:25:56 UTC; 13s ago
 Main PID: 28519 (dotnet)
    Tasks: 24 (limit: 3527)
   CGroup: /system.slice/grantid-console.service
           └─28519 /usr/bin/dotnet Grant.Id.Console.dll

Jan 21 19:25:56 ubuntu1804 systemd[1]: Started GrantID Console.
Jan 21 19:25:57 ubuntu1804 grantid[28519]: info: Grant.Id.Console.Startup[0]
Jan 21 19:25:57 ubuntu1804 grantid[28519]:       Console has started.
Jan 21 19:25:57 ubuntu1804 grantid[28519]: Hosting environment: Linux
Jan 21 19:25:57 ubuntu1804 grantid[28519]: Content root path: /usr/share/grantid/console
Jan 21 19:25:57 ubuntu1804 grantid[28519]: Now listening on: http://[::]:5012
Jan 21 19:25:57 ubuntu1804 grantid[28519]: Application started. Press Ctrl+C to shut down.

If necessary, restart the service: systemctl restart grantid-console

To test that the service is running, run:

curl -H "X-Forwarded-Proto: https" http://localhost:5012/

The source for an HTML document should be outputted.

Create a site configuration file for the component:

nano /etc/nginx/conf.d/grantid-console.conf

Enter the following, replacing the server_name entry with your console domain:

server {
    listen        80;
    listen        443 ssl;  # comment if you don't have an SSL certificate yet

    # Replace with your console domain
    server_name   console.id.patorum.com;

    # Path of the SSL certificate and key (comment if you don't have an SSL certificate yet)
    ssl_certificate      /etc/ssl/certs/grantid.pem;
    ssl_certificate_key  /etc/ssl/private/grantid.key;

    location / {
        proxy_pass         http://localhost:5012;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Test the Nginx configuration and reload it:

nginx -t
nginx -s reload

Test the site (replace console.id.patorum.com with your console domain):

curl -H "Host: console.id.patorum.com" http://localhost/

Post-installation

Follow the steps on GrantID post-installation to complete the installation procedure.