Setting Up Authentication via External Services

To authorize users on logging in to repository, the web application can use the OAuth 2.0 or OpenID Connect protocol. User authentication is executed using accounts of the services that support this protocol. The OpenID Connect protocol is supported only by Google services.

To set up login to the system, follow the steps below.

If required, see the extended scheme of interaction between web application and external service.

Step 1. Setting Up Repository Connection

To connect to the repository under the specific user authorized on the external server, determine the settings described in this step for each user and for each repository. Repeat this step on all work nodes of the cluster, except for the Step 5.

To set up repository connection:

1. Start the PP.Util utility located in the folder with installed Foresight Analytics Platform, using command line as an administrator. Below are commands for setting up repository connection. Use PP.Util_start.sh to execute the command in Linux OS, and PP.Util.exe to execute the command in Windows OS instead of PP.Util.

NOTE. When saving the encrypted password of technological account in Linux OS, the AnalyticsPlatform feature is requested. Study the methods for specifying the LSFORCEHOST or LSHOST system variable before executing PP.Util_start.sh.

2. Save the encrypted password of the technological account to connect to DBMS:

• If it is assumed to authenticate on database server using a common account for all external server users, in the security manager one does not need to ad all external users but one must add the user, whose credentials are used to connect to DBMS. In this case, credentials of one user should be saved using the command:

PP.Util /save_creds /ALG gos "repository identifier" /DC "repository user name"

• If it is assumed to authenticate on database server under the user corresponding to the user who executed authorization on the external server, in the security manager one should add all users, whose credentials are used to connect to DBMS. Credentials of one user should be saved using the command:

PP.Util /save_creds /ALG gos "repository identifier" "repository user name"

After executing the operation, the password to connect to the repository is asked. Enter the password, after which the Password for metabase 'repository identifier' and login 'user name' saved message is displayed.

3. To set up repository connection, one will need a private key and a certificate that present a BI server digital signature. The private key and the certificate are generated in the PEM format using specific software tools, for example, OpenSSL). Unpack or install OpenSSL.

To install OpenSSL in Linux OS, execute the command:

• For Debian-based distributions:

sudo apt-get install

• For RedHat-based distributions and ALT Linux:

sudo yum install openssl

The certificate is generated and saved to the repository database, and the key for this certificate is stored on the cluster work node.

4. Create the openssl.cnf file containing auxiliary information:

[ req ]
default_md = sha1
distinguished_name = req_distinguished_name
 
[ req_distinguished_name ]
countryName = Country
countryName_default = RU
countryName_min = 2
countryName_max = 2
localityName = Locality
localityName_default = Russia
organizationName = Organization
organizationName_default = Foresight
commonName = Common Name
commonName_max = 64
 
[ certauth ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always,issuer:always
basicConstraints = CA:true
crlDistributionPoints = @crl
 
[ server ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
nsCertType = server
crlDistributionPoints = @crl
 
[ crl ]
URI=http://testca.local/ca.crl

5. Create a root certificate using the command:

openssl req -config ./openssl.cnf -newkey rsa:2048 -nodes -keyform PEM -keyout ca.key -x509 -days 3650 -extensions certauth -outform PEM -out ca.cer

Additional data is requested on executing the command: PEM password and certificate owner data. When requesting the "Common name" specify name of the issuing certification authority, for example, Test CA.

6. Generate a key for server certificate using the command:

openssl genrsa -out server.key 2048

Create a request to sign server certificate:

openssl req -config ./openssl.cnf -new -key server.key -out server.req

Issue server certificate that is valid for 1 year:

openssl x509 -req -in server.req -CA ca.cer -CAkey ca.key -set_serial 100 -extfile openssl.cnf -extensions server -days 365 -outform PEM -out server.cer

If it is required to change certificate expiration date, edit the -days parameter before issuing the certificate.

The certificate will be generated as a *.cer file, the private key will be generated as a *.key file. The certificate and the key can have any name, for example, server_name.cer and server_name.key.

NOTE. Certificate and key names should be unique for each cluster work node.

7. Save the generated certificate with the *.cer extension in the repository:

PP.Util /save_cert "path to certificate" <repository identifier> <user name>

After executing the operation, the password of the specified user is asked. The obtained credentials are used to connect to the repository. If the authorization and certificate saving are successful, the Certificate from file 'path to certificate' with identifier 'certificate identifier' saved to metabase 'repository identifier' message is displayed.

8. Save the generated private key with the *.key extension in the registry:

PP.Util /save_private_key "path to key file" <certificate identifier> <encryption 
algorithm := gos|pro, if it is not specified, then pro>

Identifier of the certificate that is required to execute the command is displayed in the previous command result.

After executing the operation, the Certificate from file 'path to key' with identifier 'certificate identifier' saved message is displayed.

After executing the operations the repository connection is set up.

Step 2. Setting Up OAuth/OpenID Connect Protocol Parameters

In the registry editor in Windows OS or in the registry.reg file in Linux OS, for OAuth or OpenID Connect protocol add subsections with names of services and determine appropriate registry settings in the key [HKLM\SOFTWARE\Foresight\Foresight Analytics Platform\10.0\PP\BIS\System\OAuth\<service name>], or create the System section in the settings.xml file with the following parameters:

The example of filling in parameters is given in the System section for the settings.xml file.

NOTE. In the designer of business applications one can set up automatic redirection to user authorization via the OAuth/OpenID Connect protocol when logging in the web application. To do this, in the DBA.config.json file set the OAuth value in the authentication field and specify authorization services determined on setting up parameters for the OAuth or OpenID Connect protocol, in the allowOauthProviders field.

Step 3. Preparing BI Server

Interaction between BI server and external services is executed by means of the libcurl third-party library. To read about library purpose, functions and constraints, see the official website.

To prepare BI server, check if Internet access is allowed on the server with installed BI server, and make sure that access to services websites is allowed.

If proxy server is used for internet connection, create the system variables:

• CURLOPT_PROXY. Set the proxy.sever.ru:8080 value to the variable where proxy server URL and port used for connection are specified.

• CURLOPT_PROXYUSERPWD. Set the login:password value to the variable where user name and password for internet connection are specified.

In Linux OS environment variables are contained in the file /opt/foresight/fp10.x-biserver/etc/envvars and are added in the format: <variable name>=<value>.

The environment variables are read on BI server startup with the Apache2 instance. For details about adding environment variables in Linux OS, see the Configuration and Setup section.

NOTE. If required, to track executed operations and get debug info, create the PP_LOG and CURLOPT_VERBOSE environment variables with the 1 value.

If an external service is available via the HTTPS protocol, use the security certificate in the PEM format:

• In Linux OS execute one of the operations:

• Add certificate contents in the file /etc/ssl/certs/ca-certificates.crt.

• Add the certificate with the *.pem extension to the /etc/ssl/certs folder.

• In Windows OS:

1. Start the Microsoft Management Console built-in application.

2. Add the certificate to the Trusted Root Certification Authorities > Certificates folder.

Step 4. Preparing and Opening Web Application

To prepare the web application, use the Metabases.xml file and add the Authentication attribute with the 7 value, and fill in the OAuthService attribute with the parameters:

The example of the Metabases.xml file:

<PP>
    <Metabases>
        <REPOSITORY_ID Name="REPOSITORY_ID" Authentication="7" Package="STANDARDSECURITYPACKAGE" DebugMode="1">
            <OAuthService AutoStartProvider="1" Providers="Google" UseDefaultUser="1"/>
            <LogonData DATABASE="DATABASE_NAME" SERVER="SERVER_DATABASE"/>
        </REPOSITORY_ID>
    </Metabases>
</PP>

An alternative method of preparing the web application is adding identical parameters to the registry section:

• [HKEY_CURRENT_USER\SOFTWARE\Foresight\Foresight Analytics Platform\10.0\Metabases\<repository identifier>] - specific repository settings for the current user, regardless of the system bitness.

• [HKEY_LOCAL_MACHINE\SOFTWARE\Foresight\Foresight Analytics Platform\10.0\Metabases\<repository identifier>] - specific repository settings when bitness of Foresight Analytics Platform matches with that of the operating system. For all users.

After making changes restart BI server and open the web application. The login dialog box will display system authorization buttons using by means of the OAuth or OpenID Connect protocol:

Select the repository and click the button of one of the authorization services. Then the corresponding service account page opens, for example, Google. Enter user name and password on the service page. If authorization is successful, the object navigator opens in the web application.

Extended Scheme of Interaction between Web Application and External Service

Scheme of interaction between web application and external service:

1. The user selects the repository configured to work with an external service:

BI server handles the request to send external service settings and to display corresponding buttons in the login dialog box.

2. The user clicks the buttons of corresponding external service in the login dialog box, and the authorization page opens. The user enters login and password.

If the user is successfully authenticated, the user is redirected to the web application, and the client gets authorization confirmation code. The user is redirected using the RequestCallbackParam parameter.

3. The client sends the request to BI server to get external service authorization token. The request contains the authorization confirmation code and web application URL.

4. The BI server sends request to the external service to get the authorization token. The request is executed via the authorization service URL specified in the RequestTokenUrl parameter. The external service handles the request using the authorization confirmation code and returns the data:

• access_token. Authorization token.

• id_token. Identification token, if the scope additional parameter is set in the AuthUrl parameter for the OpenID Connect protocol.

• refresh_token. Token for periodic refresh of the authorization token.

• expires_in. Authorization token expiration time. During the opened repository session, a request to refresh access_token and refresh_token is executed after the authorization token is expired. If the user session is inactive on the external service or the server is unavailable, the repository connection will be interrupted.

The obtained data determines the current authorization state. The following is used as the authorization states storage:

• State server. The saved data is automatically deleted after server records store time is expired.

• BI server RAM. The saved data is automatically deleted on BI server restart.

5. The BI server creates a unique key of the current authorization state in the storage and sends its to the client. The client sends request to the BI server to connect to repository. The BI server sends the unique key of the current authorization state.

6. The BI server sends request to the external service to get authorized user data. The external service handles request based on the value of the UserDataUrl parameter and returns information about the user, including user name that will be displayed in the object navigator and in the security manager.

7. The private key and certificate that present BI server digital signature are checked. If the private key does not correspond to the certificate in the database or is not found, the BI server returns error, and the repository connection is interrupted. If the private key corresponds to the certificate, DBMS connection is executed using the credentials that are determined by means of the UseDefaultUser parameter.

8. The BI server returns session moniker to the client. The user is redirected to the object navigator.