OpenMetabaseResult OpenMetabase(MbDef tDef, UserCreds tCreds, [OpenMetabaseArg tArg])
tDef. Description of the repository, the user is connecting to.
tCreds. User credentials used for connection.
tArg. Connection parameters.
The OpenMetabase operation connects to the repository and returns the moniker of the repository connection.
The operation enables the user to execute the following operations:
Connect to an existing repository and get access to its objects.
Create a new repository at DBMS server.
Connection to a repository can be established in various ways. To connect to a repository, specify the repository information and user authentication parameters. For specifying a repository to connect, the following variants are available:
Determine identifier of the repository description in the tDef.id field. On operation executing the specified description is searched in the operating system registry of the server, where the BI server is located. If the description is not found, its settings will be used to connect to the repository.
In the tDef.logonData field specify the parameters of the security module that are used to connect to the repository (DBMS driver used for connection, name or server IP address, scheme/database identifier). In this case an empty string must be set as an identifier of description in thetDef.id field.
To authenticate the user, use the following methods (a more detailed description is provided below):
With direct indication of credentials.
With domain user authentication.
Using SAML protocol.
Using OAuth protocol.
Using a digital signature.
Authentication parameters are specified in the tCreds field.
The operation results in the following objects:
The repository connection moniker (the id field).
The session key (the sessKey field).
The session identifier (the sessCookie field).
The repository version (the version field).
NOTE. Session parameters are stored in the BI server memory or at the state server if configuration defined a group of StateServer settings. If the StateServer group of settings is defined, the state server is disconnected, the session identifier is not generated.
The obtained moniker is further used in the following cases:
On executing various operations to specify the repository, within which the user is working.
In the id field when creating identifier of the object, with which the user is working.
On closing the repository connection by means of the CloseMetabase operation.
The sessKey session key can be used, for example, to work with access protocol to get a list of operations executed in the session.
The sessCookie identifier, unlike the moniker, is not used to work with the repository, and is used only to identify existing server sessions. If the obtained identifier is saved and on a new connection is further specified as a value of the tArg.sessCookie field, BI server checks if a session with the same identifier exists. If such a session exists, it is checked if it can be reused. The necessary conditions for reuse of the session:
Correct user login and password.
The list of active sessions still contains a session with the specified identifier.
The existing session was created only for the specified user.
The credentials are specified in the tCreds.user and tCreds.pass fields.
To connect to repository using a digital signature, prepare the repository in the following way:
The user needs to save an encrypted password to the registry. This password will be further used to connect to the repository database. To do this, run the PP.Util.exe utility with the key /save_creds <repository description identifier> <user name>. The utility is located in the folder with installed Foresight Analytics Platform. After the successful startup the password for entering the repository is requested. Enter the password. The following message appears: Password for metabase “Repository description identifier” and login “user name” saved.
Save the certificate to the repository using the following command: PP.Util.exe /save_cert "path to the certificate" <repository description identifier> <user name>. After this the utility requires password of the specified user. The entered account data is used to connect to the repository. If the authentication is successful and the certificate has been saved, the following message appears: Certificate from file "path to certificate" with identifier "certificate identifier" saved to metabase "repository description identifier".
Save the private key to the registry using the following command: PP.Util.exe /save_private_key "path to the key" <certificate identifier> <encryption algorithm := gos|pro, if not specified, then pro>. After the private key is successfully saved, the following message appears: "Certificate from file "path to the key" with identifier "certificate identifier" saved".
NOTE. If the BI server is deployed on the IIS server, the BI server pool must be started using credentials of the same user who started the PP.Util.exe utility.
Before connection execute the GetVerifierCode operation to get the data block the client must sign with the digital signature. The signed data must be specified in the tCreds.verifier.signature field, and in the tCreds.verifier.cookie field specify the random number that also will be obtained as the result of executing the GetVerifierCode operation. In the tCreds.verifier.user field specify the user who connects to the repository. This user may be not available in the repository DBMS or in the security manager.
NOTE. If the specified user does not exist anywhere, it is created in the security manager of the repository. If the tCreds.verifier.role field was defined, the user is included into the specified group and granted respective permissions. If this field is not defined, the user is included into the Built-in Users Group. If required, permissions of the created user can be edited with the SetMbSec operation.
In the tCreds.verifier.mbUser field specify the user whose credentials will be used for actual connection to the repository database. This user must exist in the repository and have permissions to enter the repository. Also, in the tCreds.verifier.certificate field specify identifier of the certificate to be used to verify the digital signature. This certificate must be saved to the repository as described above. An empty string is set as the value of the tCreds.pass field, and this field is not used when connecting to the repository using a digital signature.
To use integrated domain user authentication, the tCreds.user field is not specified, specify empty value in the tCreds.pass field. In this case the current operating system user credentials are sent for connection.
Various methods of using this operation are given in the following examples:
| Example name |
Connecting to Repository Using Direct Transfer of Credentials |
Connecting to Repository Using Integrated Domain Authentication |
See also: