In this section we will guide you through the setup and configuration of the lightweight OAuth2 server.
Before you continue installing i-refactory server please make sure the following prerequisites are met.
You should have system administrator access to a host system on which NodeJS is supported. The host system should have at least the following minimal resources.
The OAuth2 server runs as HTTPS server. You need to have a valid SSL certificate and SSL key file available. The server needs read access to these files. You should check with your security officer regarding the policies of generating SSL certificates.
For development and testing you could create a self signed certificate. If you have openssl available here is an example how to create a certificate for the localhost domain.
openssl req \
-newkey rsa:2048 \
-x509 \
-nodes \
-keyout server.key \
-new \
-out server.crt \
-subj /CN=localhost \
-reqexts SAN \
-extensions SAN \
-config <(cat /System/Library/OpenSSL/openssl.cnf \
<(printf '[SAN]\nsubjectAltName=DNS:localhost')) \
-sha256 \
-days 365
This command generates two files server.key
and server.crt
.
The client operating system or browser now needs to have the CA certificate added to its list of trusted root authority certificates. The instructions vary by operating system and browser but instructions for a few major clients are listed below. For all these steps the 'certificate' referred to is the 'server.crt'.
Client | Instruction |
---|---|
Windows | Right click the server.crt certificate file and select 'Install Certificate'. Follow the prompts to add the certificate to the trust store either for the current user only or all users of the computer. |
Mac | Open KeyChain and drag the file server.crt into KeyChain. Set the certificate to trusted. |
Linux - Ubuntu | sudo cp ~/server.crt/usr/local/share/ca-certificates/ sudo update-ca-certificates See Ubunbtu help for more information. |
If you will be using your own OAuth2 server you will need to have the following information available:
If you are going to use our i-refactory OAuth2 server we need to have read access to a private and public RSA key pair.
There are many ways to create RSA keys. OpenSSL is one of the most popular libraries for key creation and management:
# Generate a private key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
# Derive the public key from the private key
openssl rsa -pubout -in private_key.pem -out public_key.pem
The private key file private_key.pem
will be used in our OAuth2 server to sign the JWT token.
The publicy key file public_key.pem
will be used in our i-refactory server to check if the generated JWT token is not tampered with.
The i-refactory OAuth2 server is build in NodeJS. NodeJS applications can be run on almost any platform. All of these components run as HTTPS servers.
The i-refactory servers always run against a Long Term Support release of NodeJS. In our Release Notes Overview you can see which NodeJS version is required for the given i-refactory server release.
You can download the LTS version of NodeJS at Download NodeJS. To download a previous LTS version check this Download Previous Releases of NodeJS.
Follow the install instructions for your platform.
You can check if NodeJS is available by entering the following command in your terminal:
node --version
It should return the installed LTS version, for example: v12.14.1
.
You should create a folder on your host filesystem where we are going to install the OAuth2 server software and where you can store your configuration files and optionally store your SSL certificates and required key files.
The folder structure we suggest:
i-refactory-oauth2\
config\
crypto\
dist\
In the config folder you should store you configuration files which will be explained in Step 4: Create a configuration file.
In the crypto folder you should store the SSL certificate and key file and the private and public RSA key file.
From the provided installation zip file unpack the folder i-refactory-oauth2
to the folder i-refactory-oauth2\dist
.
Our OAuth2 server requires a configuration file. The configuration file is a JSON document which contains mandatory and optional configuration settings.
We have provided a sample configuration files which you can find in i-refactory-oauth2\dist
.
config.example.json
: This configuration file can be used as a template. Copy it to the config directory and name it for example: config.json
.With a text editor of choice edit your configuration file.
{
"https": {
"host": "localhost",
"port": 3003,
"key": "",
"cert": ""
},
"privateKey": "",
"publicKey": "",
"clients": [
{
"clientId": "i-refactory-ui",
"clientSecret": null,
"redirectUri": "https://localhost:3002",
"grants": [
"authorization_code",
"refresh_token"
]
},
{
"clientId": "exampleNonWebClient",
"clientSecret": "12345",
"grants": [
"password",
"client_credentials",
"refresh_token"
],
"roles": [
"DataViewer",
"SystemManager",
"DataManager",
"DataOperator",
"Developer"
]
}
],
"users": [
{
"id": "info@i-refact.com",
"username": "administrator",
"password": "abcd123",
"email": "info@i-refact.com",
"roles": [
"DataViewer",
"SystemManager",
"DataManager",
"DataOperator",
"Developer"
]
},
{
"id": "exampleUser@i-refact.com",
"username": "exampleUser",
"password": "12345",
"email": "exampleUser@i-refact.com",
"roles": [
"DataViewer",
"SystemManager",
"DataManager",
"DataOperator",
"Developer"
]
}
]
}
Change the following configuration settings:
parameter | instruction |
---|---|
host |
Set the hostname of the authorization server. Defaults to localhost . |
port |
Set the port number of the authorization server. Defaults to 3002 . |
key |
Specify the file location including the filename of the SSL key. You should use your generated or provided SSL key filename. You can use the same SSL key as for the i-refactory Rest API server or opt for a different one. |
cert |
Specify the file location including the filename of the SSL certificate. You should use your generated or provided SSL certificate filename. You can use the same SSL key as for the i-refactory Rest API server or opt for a different one. |
privateKey |
Specify the file location including the filename of the private key. |
publicKey |
Specify the file location including the filename of the public key. |
clients |
Contains a list of clients who are allowed to issue requests. |
clients[].clientId |
For each client create a unique clientId. The i-refactory UI application is an example of a client. |
clients[].clientSecret |
If the client is required to authenticate with a password set a password value otherwise set the value to null. |
clients[].grants |
The supported OAuth2 grants the client is allowed to issue. |
clients[].roles |
The i-refactory server roles assigned to the client. Only applicable for clients which are allowed to issue requests. |
users |
A list of users that are granted access. |
users[].id |
Unique identifier for a user. |
users[].username |
The username with which a user should authenticate. |
users[].password |
The password with which a user should authenticate. |
users[].email |
The email address of a user. Added for backwards compatibility as the email address might be used as the modifierId which we log in the metadata. |
users[].roles |
The i-refactory server roles assigned to the client. Only applicable for clients which are allowed to issue requests. |
For more details regarding the configuration and use of OAuth2: OAuth2