Storing Secrets for Scripts

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search

Secrets provide a method to store passwords and other confidential data in QPR ProcessAnalyzer, and use them without being able to see the stored secret values. For example in scripts, SAP, Salesforce and ODBC passwords can be stored as secrets, which can be referred by their names in the script commands.

There are project-specific and global secrets. To use a secret, the user needs to have GenericRead permission to the project (or global GenericRead to use global secrets). To define a secret, the ManageProject permission to the project is needed (or global ManageProject to define global secrets). If both a global and a project-specific secret with the same name and type are set, the project-specific secret will be used in that project, and thus the global secret is unavailable for that project.

Each secret has a type which defines in which command the secret can be used. The purpose of the type is to improve security, so that the secret can only be used in the intended command.

Setting secrets

Secrets can be set by calling the SetSecret function for the project, or the corresponding generic context SetSecret function. Project secrets can also be defined in the Project Properties Dialog.

Example: Set a project secret (for project id 1): 

ProjectById(1).SetSecret("sap", "SapAdminPassword", "I l0ve 5AP!");

Example: Set a global secret: 

SetSecret("sap", "SapReaderPassword", "I l0ve 5AP!");

Listing secrets

To list all secrets in the project, use the Secrets property for the project. For the global secrets, there is the corresponding global Secrets property. Note that the secret value cannot be retrieved even by system administrators.

Example: List project secrets (for project id 1): 

ToJson(ProjectById(1).Secrets);

Example: List global secrets: 

ToJson(Secrets);

Using secrets

Secrets can be used in the following commands:

Note: Currently ImportSqlQuery and ImportOleDbQuery don't support secrets.

QPR MEA connection string

The secret type QprMea is used to store a connection string for connecting and authenticating to QPR Suite (MEA) Web Service (https://wiki.onqpr.com/mea/index.php/QPR_Suite_Wiki).

The connection string is a JSON object with the following fields:

  • url: QPR Suite webservice url. The url typically ends with /QPR.Isapi.dll/wsforward/MainService.svc/webHttp.
  • logOnName: QPR Suite username.
  • password: QPR Suite user password.

Example: 

{ "url": "https://hostname/QPR/Portal/QPR.Isapi.dll/wsforward/MainService.svc/webHttp", "logOnName": "qpr", "password": "demo" }

OAuth 2.0 client credentials secret

The secret type OAuth20ClientCredentials is used to define all required parameters to authenticate using the OAuth 2.0 client credentials flow.

The secret value is a JSON object that can contain the following fields:

  • tokenEndpoint: The url of the OAuth token endpoint. Only https urls's are accepted.
  • clientId: OAuth client identifier.
  • clientSecret: OAuth client secret.
  • scope: Scope sent to Entra v2 and other OAuth v2 token endpoints.
  • resource: Resource sent to Entra v1 token endpoints.
  • audience: Pptional stored property that is not sent in the token request.

Example: 

{
  "tokenEndpoint": "...",
  "clientId": "...",
  "clientSecret": "...",
  "scope": "...",
  "resource": "...",
  "audience": "..."
}

Stores an OAuth 2.0 client-credentials configuration for product functions that support this secure value type. OpenAIChatCompletion (#71769#) is the first currently supported function and is used as an example below. 2. The value must be a JSON object with the following properties: 

  1. `tokenEndpoint` (string): Required absolute HTTPS URL of the OAuth 2.0 token endpoint.
  2. `clientId` (string): Required OAuth client identifier.
  3. `clientSecret` (string): Required OAuth client secret. The value must not be written to logs.
  4. `resourceServerEndpoint` (string): Required absolute HTTPS URL of the resource server for which the access token is issued. Each product function that supports this secure value type defines how the endpoint is used.
  5. `scope` (string): Optional OAuth scope. Must not be specified together with `resource`.
  6. `audience` (string): Optional audience value retained in the configuration. It is not sent in the token request.
  7. `resource` (string): Optional OAuth resource value. Must not be specified together with `scope`.

3. The property names are case-insensitive. Unknown properties are ignored. 4. An access token is requested using the `client_credentials` grant type. The request includes `client_id` and `client_secret`, and includes `scope` or `resource` when configured. 5. The token endpoint response must be a successful JSON response containing a non-empty `access_token` property. 6. The `resourceServerEndpoint` binds the access token to its intended resource server. For the first supported function, OpenAIChatCompletion, it identifies the OpenAI-compatible Chat Completions API endpoint and overrides both the `openAiUrl` parameter and the configured OpenAIUrl value. 7. OAuth access tokens used for implicit authentication by OpenAIChatCompletion are cached per client-credentials configuration and refreshed once when the API reports that the token has expired. Other product functions may define their own access-token handling requirements.

Retrieved from "https://wiki.onqpr.com/pa/index.php?title=Storing_Secrets_for_Scripts&oldid=29006"