HTTP Headers

When logging in to repository using HTTP headers, after the user is authenticated in the external service, BI server queries should be added with HTTP headers with user information.

An mTLS connection should be set up between the proxy server that establishes BI server connection and adds includes headers to queries and the BI server.

NOTE. Interaction between the external authentication service and the proxy server is not described in this help and can be implemented at administrator's discretion.

Trust between the BI server and the proxy server is established by comparing certificate's digital fingerprint specified in the description of external service settings in the ExtService section of the settings.xml file/in the registry and certificate's digital fingerprint obtained from the proxy server during establishing mTLS connection with the BI server.

If the external service's user account is contained in the security manager, the repository connection is established and the object navigator opens using this user account.

If the external service's user account is not contained in the security manager, a temporary user is created and added to groups from the list specified in the corresponding header. If the header containing the list of groups is not set, the temporary user is added to the USERS built-in group.

DBMS connection is executed using technological account.

The interaction scheme is given in the Foresight Analytics Platform Authentication section.

Step 1. Save Technological Account to Connect to DBMS

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)> <user password>
		

The example of saving data of a common technological account for all users of the external service:

PP.Util /save_creds /ALG gos REPOSITORY_ID /DC TECHNO_ACCOUNT TECHNO_PASSWORD

• If authentication is assumed on database server using different technological accounts corresponding to external server user, in the security manager one does not need to add all external users but one must add the users whose credentials will be used to connect to DBMS as corresponding technological accounts. 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)>		
		

The example of saving data of different technological accounts:

PP.Util /save_creds /ALG gos REPOSITORY_ID TECHNO_NAME1 TECHNO_PASSWORD1 USER1
PP.Util /save_creds /ALG gos REPOSITORY_ID TECHNO_NAME2 TECHNO_PASSWORD2 USER2
PP.Util /save_creds /ALG gos REPOSITORY_ID TECHNO_NAME2 TECHNO_PASSWORD2 USER3		

The TECHNO_NAME1, TECHNO_NAME2 users, whose credentials are used as technological accounts, must be added in the security manager. The USER1, USER2, USER3 external service users can be added in the security manager and can be temporary users.

NOTE. The user used as a technological account should have the privileges, which include privileges of corresponding external service users, for which it was saved.

When connecting to repository the system searches for the saved technological account to connect to DBMS:

• First, the system searches for the saved technological account corresponding to the external service user.

• If such account is not found, the uniform account saved with the /DC parameter by default is used to connect to DBMS.

• If there is no uniform account saved with the /DC parameter and the account corresponding to external service user, a connection error occurs.

After executing the operations the repository connection is set up.

Step 2. Set Up BI Server

An mTLS connection should be set up between the proxy server, which establishes BI server connection and appends queries with HTTP headers, and the BI server.

Steps for BI server installation differ depending on the operating system in use.

Step 3. Set Up External Service Parameters

For the external service add a section with service name in the registry key [HKLM\SOFTWARE\Foresight\Foresight Analytics Platform\10.0\PP\BIS\System\ExtService\<service name>] or in the corresponding section of the settings.xml file. Determine the following settings:

• Type. External service type. Set HttpHeaders as a value.

• AuthUrl. URL of external service authentication page. If the parameter is specified, clicking the Login and Exit buttons opens the external service's authentication page. If the AuthUrl parameter is not specified, after clicking the Login button and successful user authentication the object navigator or the repository object opens. Clicking the Exit button opens the web application authorization page.

• UserIdAttr. Header name that will contain unique user identifier.

• UserNameAttr. Header name that will contain displayed user name. Header value will be applied only for temporary users.

• UserRolesAttr. Header name that will contain the list of groups of users and for temporary adding a user to the obtained groups. It is used if the user account is not created in the security manager, and the required groups of users are created in the security manager. If the UserRolesAttr parameter is not specified, the temporary user is added to the USERS built-in group.

IMPORTANT. The list of groups of users must not contain the ADMINISTRATORS built-in group. If this group is in the list, an exception is thrown during the connection.

• CertificateHash. Certificate's digital fingerprint of the proxy server that establishes BI server connection and appends queries with HTTP headers. Trust between the BI server and the proxy server is established by comparing certificate's digital fingerprint specified in the parameter and certificate's digital fingerprint obtained from the proxy server during establishing mTLS connection with the BI server.

The value specified in the CertificateHash parameter should be created after issuing the certificate used for establishing an mTLS connection with the external service.

• UPN. Header name that will contain user name in the UPN format.

• Email. Header name that will contain user email. For example, the header name "mail" or the path /path/to/mail.

To set session values of global variables, after the repository connection is successfully established, one can create the AdditionalAttributes section in external service settings description. Name of each child element of this subsection should match the header name, which value will be set in global variable. The child element can contain the IdVariable parameter, in which one specifies identifier of repository global variable. If the IdVariable parameter is not specified, the system searches for the global variable with the identifier equal to header name in upper case.

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

Step 4. Set Up Repository Connection

To set up repository connection, use the Metabases.xml file, add the Authentication attribute with the 8 value and fill in the ExtService section with the Provider attribute. As an attribute value, specify name of the subsection created for the external service at Step 3.

The example of the Metabases.xml file:

<PP>
    <Metabases>
        <REPOSITORY_HTTP Name="REPOSITORY_HTTP" Authentication="8" Driver="POSTGRES" Package="STANDARDSECURITYPACKAGE">
            <ExtService Provider="HTTP_PROVIDER"/>
        </REPOSITORY_HTTP>
    </Metabases>
</PP>		

An alternative method of repository connection setup 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 all changes restart the BI server.

Step 5. Prepare External Service and Open Web Application

The web application should work via the HTTPS protocol. The external service after user authentication should be able to open the web application page by the following URL:

https://<web application URL>/fp10.x/r/#/app/navigator?repo=<repository identifier>

One can open the object navigator or open a repository object via the URL. The URL should contain the repo parameter including repository identifier.

The web application redirects queries to the proxy server. Queries are appended with HTTP headers with user information on the proxy server. The appended query is sent to the BI server. The BI server checks the proxy server certificate's digital fingerprint, obtains user information from HTTP headers, and opens a repository connection. After the repository connection is opened, the web application page is displayed, to which the user was redirected.