Service Account Authentication Web Part


For some applications, such as external user access, it is desirable to use a single user id to log into Cognos, without disclosing the user id and password to users. This can be achieved using Service Account Authentication.

The QueryVision Service Account Authentication web part acts like a combination of the Single Sign on part and the standard authentication part:

  • The user is logged into Cognos using a user id, password and Cognos namespace.
  • The application administrator selects which user and credentials, through defining available “Service Accounts” in the QvtConfig.xml file, plus selecting which Service Account to use the web part setup.
  • For users, the logon will act like the Single Sign on part as the part will transparently logon using the selected Service Account credentials.

For this web part to function correctly you must configure Cognos Server properties and add a ServiceAccountCredentials section to the QvtConfig.xml configuration file.

Service Account Credentials are defined once and can be re-used across multiple Cognos Servers and Cognos Server Namespaces.

Defining Service Accounts for a Cognos Server

ServiceAccounts are added to a Cognos Server Namespace in QvtConfig.xml. A service accounts section is required for each Cognos Server Namespace for which you wish to configure to use Service Accounts.

For example:


Each Service Account has up to 3 sub-elements:

  • Default – optional – can be True or False. The first Default = True will be used as the default if there are multiple
  • Name – this is the display name that will be shown in the Service Account Web Part tool panel when selecting which credential to be used as the Service Account Credentials.
  • ServiceAccountCredentialName – references which Service Account Credential to use from the ServiceAccountCredentials section (See below)

Defining Service Account Credentials

The Service Account Credentials are added to the following QvtConfig.xml section:


The ServiceAccountCredentials section is structured as follows:


How Credentials are encrypted is governed by the Encrypted element. The possible values for EncryptedOption are:

  • False – UserName (user id) and Password are in plain text
  • PwdOnly – only Password is encrypted
  • UidPwd – Username and Password are encrypted

The Name is the logical name assigned to the credential and is the one referenced by the CrnServer/Namespace/ServiceAccount

If Username or Password are encrypted, the encrypted value will be the value of the Username and Password xml elements, respectively.

QueryVision Service Account Generation Tool

The ServiceAccountCredentials section of the QvtConfig.xml file can be generated by the QueryVision Service Account Generation Tool (QvtServiceAccountGenerator.exe), which is installed by the QueryVision Web Parts installer. The tool can be used on any Windows configuration.

This command line tool can be used in two ways

  • Single Credential – where the ServiceAccountCredential Name, Username and Password are included on the command line along with encryption options. The following example encrypts the password only for a single credential.

QvtServiceAccountGenerator –n someName –u someUserId, -p somePassword –e PwdOnly

  • Multiple Credentials – where a csv file and encryption options are provided on the command line, where each row in the csv file provides a Name, Username and Password. The following example encrypts both user id and password for credentials in the csv file someFile.csv.

QvtServiceAccountGenerator –f someFile.csv –e UidPwd

The following is the usage:


Note: the option to provide an encryptionKey should not be used. A default key is used which is also embedded in the QueryVision Web Parts application. Specifying the encryptionKey with the current release will result in decryption errors on loading QvtConfig.xml.

The output of the QvtServiceAccountGenerator is an XML file (ServiceAccountCredentials.xml) which contains the XML “snippet” for the ServiceAccountCredentials section which needs to be inserted into the QvtConfig.xml file. Example below:

SvcAcntWebPart_2015-04-14_15-30-24Copy paste the contents of this file – but WITHOUT the first line

SvcAcntWebPart_2015-04-14_15-31-37to the following location in QvtConfig.xml (highlighted in yellow, below). If an existing ServiceAccountCredentials section exists, replace it.

SvcAcntWebPart_2015-04-14_15-30-49Configuring a Service Account Web Part

Below is the Web Part configuration panel for the Service Account Web Part.

A typical application using Service Account Authentication will configure QueryVision “viewer” web parts on SharePoint pages to redirect to a page containing the Service Account Authentication Web Part. The Service Account Web Part will define the Cognos Server and Service Account to use with Prompt On Redirect (disabled) and Automatically Logon (enabled).

On accessing a SharePoint page with QueryVision components for the first time in a browser session, the browser will briefly redirect to the page containing the Service Account web part, the user will be automatically logged on with the Service Account credentials and redirected back to the original page. Unless the user is logged out (e.g. Cognos logon timeout), the user will not be redirected to the Service Account page for the remainder of their session.




  • Selecting the Service Account The QvtConfig.xml configuration file will first be scanned for those Cognos Servers which have at least one Namespace which has at least one Service Account defined. These Cognos Servers and their Namespaces (that have Service Accounts defined) and their Service Accounts will be presented in the “Select the Cognos Server”, “Select the Cognos Namespace” and “Select the Service Account” fields.
    • Use Defaults – Of those Cognos Servers with Namespaces with Service Accounts, the selection will be the default (or first if Default not defined) Cognos Server, it’s default (or first) Namespace (with Service Accounts) and it’s (or first) default Service Account
    • Select Service Account – allows selection of the Server, Namespace and Service Account
  • Prompt on Redirect – the typical workflow is to define QueryVision Web Parts such as the Report Viewer to redirect to a defined logon page if the user is not logged in. The option “Prompt on Redirect” will pause after logon and request the user to confirm that they want redirected back to the original page (e.g. the one with the Report Viewer). If not enabled, the user will automatically be redirected after logon. The default is disabled.
  • Automatically Logon – if enabled, the Service Account Web Part will automatically log the user with the Service Account on accessing the page where the Service Account Web Part is included. The default is enabled.

You should only turn this checkbox on once you have tested that the Service Account logon web part works correctly.