JWT Token

When logging in to repository using JWT token, after the user is authenticated in the external service, BI server queries should be added with headers containing JWT token with user information. When the repository connection opens, the user information is obtained from the JWT token.

NOTE. Interaction between the external authentication service and the proxy server, which adds headers to queries, is not described in this help and can be implemented at administrator's discretion. The trust between the BI server and the proxy server, which adds headers to queries, is provided by checking with JWT token signature.

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 attribute of the JWT token. If the attribute containing the list of groups is not set, the temporary user is added to the USERS built-in group.

NOTE. The temporary user cannot be included in the ADMINISTRATORS 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:

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 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 <repository identifier> /DC <repository user (technological account) name> <user password>

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

PP.Util /save_creds 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 <repository identifier> <repository user (technological account) name> <repository user (technological account) password> <repository user (external service) name>

The example of saving data of different technological accounts:

PP.Util /save_creds REPOSITORY_ID TECHNO_NAME1 TECHNO_PASSWORD1 USER1
PP.Util /save_creds REPOSITORY_ID TECHNO_NAME2 TECHNO_PASSWORD2 USER2
PP.Util /save_creds 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 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. Specify JWT 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.
JwtHeader. Header name that will contain JWT token with user identifier. If the parameter is specified, the JWT token is obtained from the header with the specified name. If the parameters is not specified, the JWT token is obtained from the Authorization header. In this case the token in the Bearer format is expected.
UserIdAttr. Attribute name or path to the attribute in JWT token that will contain unique user identifier. For example, the attribute name given_name or the path /path/to/given_name.
UserNameAttr. Attribute name or path to the attribute in JWT token that will contain displayed user name. For example, name of the name attribute or the path /path/to/name. Attribute value will be applied only for temporary users.
UserRolesAttr. Attribute name or path to the attribute in JWT token that will contain the list of groups of users and will add the user temporarily 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. For example, name of the groups attribute or the path /path/to/groups. 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.

SignaturePublicKey. The public key that will be used to check token signature. A signature is created based on the RS256 algorithm. The key is set in the PEM format encoded in BASE64.
UPN. Attribute name or path to the attribute in JWT token that will contain user name in the UPN format. For example, the attribute name "upn" or the path /path/to/upn.
Email. Attribute name or path to the attribute in JWT token that will contain user email. For example, the attribute 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 attribute name in JWT token, 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 attribute name in upper case.

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

Step 3. 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 2.

The example of the Metabases.xml file:

<PP>
    <Metabases>
        <REPOSITORY_JWT Name="REPOSITORY_JWT" Authentication="8" Driver="POSTGRES" Package="STANDARDSECURITYPACKAGE">
            <ExtService Provider="JWT_PROVIDER"/>
        </REPOSITORY_JWT>
    </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 4. 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 headers containing JWT token with user information on the proxy server.

The appended query is sent to the BI server. The BI server checks token signature, obtains user information, and opens a repository connection. After the repository connection is opened, the web application page is displayed, to which the user was redirected.