In this article:
Step 1. Setting Up Repository Connection
Step 2. Setting Up OAuth/OpenID Connect Protocol Parameters
Step 4. Preparing and Opening Web Application
Extended Scheme of Interaction between Web Application and External Service
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.
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:
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.
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.
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.
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
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.
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.
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.
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.
If authentication via external services is used, one should set up connection between the client and the BI server via HTTPS protocol. The "state" parameter is checked by default to protect from potential CSRF attacks on getting authorization code. If the connection between the client and the BI server is set up via HTTP protocol, create the StateCheckOff parameter and set it to 1 in the registry key [HKLM\SOFTWARE\Foresight\Foresight Analytics Platform\10.0\PP\BIS\System\OAuth] or in the corresponding section of the settings.xml file to disable the check.
For the OAuth or OpenID Connect protocol set subsections with service names and determine registry settings in the key [HKLM\SOFTWARE\Foresight\Foresight Analytics Platform\10.0\PP\BIS\System\OAuth\<service name>] or in the corresponding section of the settings.xml file with the following parameters:
AuthUrl. Authorization service URL that will be used in the web application for the RequestTokenUrl containing additional URL parameters. Specify the profile+openid values for the OpenID Connect protocol in the scope parameter.
ConsumerKey. Registered application key.
ConsumerSecret. Secret code of the registered application.
Icon. An icon that will be displayed on the login button for OAuth/OpenID Connect server authorization. If the parameter is not set, the icon will be loaded from resources of Foresight Analytics Platform. The string with the image in the base64 format is specified as a parameter value.
PPUserNameFormat. User name format, for example, "oa-ggl-%s".
RequestCallbackParam. Attribute name that will be used to send URL to redirect the user to the web application after authorization in an external service, for example, "redirect_uri". Web application URL should be contained in the external service authorization settings.
RequestTokenUrl. Authorization service URL, by which access token will be requested.
UserDataUrl. Data service URL that will be used to request user data after authorization in the web application. The token decryption service should be specified for the OpenID Connect protocol, from which user data will be obtained.
UserIdAttr. Path to the field in the requested data that will be used as unique user identifier, for example, "/path/to/id".
UserNameAttr. Path to the field in the requested data that will be used as displayed user name, for example, "/path/to/displayName".
When setting up repository connection under the specific user authorized on the external server, values of the UserIdAttr and the UserNameAttr parameters may match.
Unique identifier and user name obtained on working with external service using the UserIdAttr and UserNameAttr attributes are recorded:
To the file /var/log/apache2-fp10.x/error.log for Astra Linux.
To the file /var/log/httpd/error-fp10.x.log for RED OS and Rocky Linux.
To the file /var/log/httpd2/error-fp10.x.log for ALT Linux.
Values specified in the ConsumerKey and ConsumerSecret parameters will be obtained after registering developed application on the required OAuth/OpenID Connect authentication server. These parameters are required in order that BI server can check after authorization on OAuth/OpenID Connect server and authorize the corresponding user in the repository.
If the ConsumerKey and ConsumerSecret parameters are not specified, internal settings of the BI server are used; the OAuth/OpenID Connect server must contain registered application based on Foresight Analytics Platform.
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.
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:
Start the Microsoft Management Console built-in application.
Add the certificate to the Trusted Root Certification Authorities > Certificates folder.
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:
Providers. The array of authorization service names, which accounts can be used to log in to the web application. Allowed values are determined by the services specified on setting up OAuth/OpenID Connect protocol parameters and are specified via a semicolon. Mandatory parameter.
AutoStartProvider. The number of the authorization service specified in the Providers parameter array. On an attempt to log in to the web application using the OAuth or OpenID Connect protocol, the system automatically redirects to the selected service. Optional parameter.
If the service that is not contained in the Providers parameter is used as a parameter value, automatic redirection is not executed.
UseDefaultUser. Indicates which user credentials are used to connect to DBMS during authorization via the OAuth or OpenID Connect protocol:
1. Default value. DBMS connection is established using a common technological account for all external server users. Credentials should be saved using the PP.Util utility with the /DC parameter.
NOTE. When the user logs in to the system user name obtained from the external service is checked taking into account the format specified in the PPUserNameFormat parameter. If the user with the specified name is not found in the security manager, a temporary user is created in the Users group. The temporary user has privileges of the Users group and is deleted after the current session is timed-out. In this case DBMS connection is established using a common technological account.
0. DBMS connection is established using the technological account corresponding to the user who executed authorization on the external server. Credentials of each user should be saved using the PP.Util utility without the /DC parameter.
Optional parameter.
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.
Scheme of interaction between web application and external service:
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.
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.
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.
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.
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.
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.
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.
The BI server returns session moniker to the client. The user is redirected to the object navigator.
See also: