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.

DBMS connection is executed using technological account. Technological account is an account used for communication with DBMS during user authentication via external 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 cluster nodes.

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 technological account for all external server users, in the security manager one does not need to add all external users but one must add the user whose credentials are used to connect to DBMS as a technological account. In this case, credentials of a common technological account should be saved using the command:

PP.Util /save_creds /ALG gos <repository identifier> /DC <repository user name (technological account)>

In this case, before external vice user authentication the system checks if user account is in the security manager:

• If the user account is not in the security manager, after the user is authorized in the external service, a temporary user is created who can connect to the repository and log in to the object navigator. By default, the temporary user is added to the Users built-in group. The user used as a technological account should have the same privileges, as the Users group has.

If OAuth/OpenID Connect protocol settings have the UserRolesAttr parameter set, the temporary user is added to the groups obtained from the external service. The user used as a technological account should have the privileges, which include privileges of corresponding groups of users contained in the security manager.

• If the user account is in the security manager, after the user is authorized in the external service, the system connects to the repository and logs in to the object navigator using the external service user account that is in the security manager. The user used a technological account should have all privileges of the security manager.

• If authentication is assumed on database server under different technological accounts corresponding to each user or group of users, one should add in the security manager external users and users, which credentials will be used as technological accounts for connection to DBMS. In this case data of each technological account for corresponding external users should be saved using the command:

PP.Util /save_creds /ALG gos <repository identifier> <repository user name (technological account)> <repository user password (technological account)> <repository user name (external service)>

For example, a group includes three users - USER1, USER2, USER3, the security manager contains corresponding users and the user used as a technological account and having all user privileges. One of the group users is authenticated via an external service using a common technological account when connecting to DBMS.

The example of saving technological account data for group:

PP.Util /save_creds /ALG gos REPOSITORY_ID TECHNO_NAME TECHNO_PASSWORD USER1
PP.Util /save_creds /ALG gos REPOSITORY_ID TECHNO_NAME TECHNO_PASSWORD USER2
PP.Util /save_creds /ALG gos REPOSITORY_ID TECHNO_NAME TECHNO_PASSWORD USER3

The users used as technological accounts can have different privileges independently of each other.

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.

After executing the operations the repository connection is set up.

Step 2. Setting Up OAuth/OpenID Connect Protocol Parameters

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:

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. BI server works via HTTPS protocol.

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, copy the *.crt root certificate that was used to sign the external service security certificate, to BI server and execute the following operations:

• In Linux OS:

1. Create the fp-extra-certs folder and move the external service root certificate to it:

sudo mkdir /usr/share/ca-certificates/fp-extra-certs
sudo cp <path to folder>/<certificate name>.crt /usr/share/ca-certificates/fp-extra-certs/fp-extra-ca.crt

After executing the operations the folder /usr/share/ca-certificates/fp-extra-certs with the fp-extra-ca.crt external service root certificate is created.

2. Open the /etc/ca-certificates.conf file for edit and add a string to the end of the file:

fp-extra-certs/fp-extra-ca.crt

3. Apply configuration changes:

sudo update-ca-certificates -v

• In Windows OS import the external service root certificate to a trusted root certification authority store using operating system tools:

1. Double-click the *.crt root certificate. The Certificate dialog box opens.

2. Click the Install Certificate button. The certificate import wizard opens.

3. Select the Current User store location and click the Next button.

4. Select the Place All Certificates to the Following Store radio button, select the Trusted Root Certification Authorities certificate store in the Select Certificate Store dialog box and click the Next button.

After executing the operations the root certificate is imported to the trusted root certification authority store.

Step 4. Preparing and Opening Web Application

Web application works via HTTPS protocol. To prepare the web application, use the Metabases.xml file, add the Authentication attribute with the 7 value and fill in the OAuthService section with attributes:

• 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 attribute.

• 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 attribute.

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. Data of the common technological account 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 attribute.

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" CASESENSITIVE="true" 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. Connection to DBMS is executed using the credentials that are determined by means of the UseDefaultUser attribute.

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