With increased security rules from the IT industry best practices, some customers are not allowed to store the Database credentials, such as password, in GoldenGate's local wallet, i.e., credentialstore. The password needs to be stored in a Vault outside of GoldenGate. Hence they need an integration method to allow GoldenGate to retrieve the password when it needs to connect to a Database. GoldenGate V23.5+ has provided a user-friendly plugin that enables the customer to write their own code to retrieve the credential from a 3rd party Vault and then return it in a pre-defined API to GoldenGate.
Here are the details on how to use this new feature.
The plugin component is under <GG Service Manager Home>/var/lib/plugins/. By default, there is no library under this location. The user must write their own code and create a shared user library, then copy or move the library file to this location. At the time this blog is being written, GoldenGate has no restrictions on the library file name. However, only the plugin will pick up the first library file that exists in this location.
A minimum of two function APIs need to exist in this plugin.
It returns a JSON style string that has the following content:
{"$schema": "ogg:plugin", "version": "23.4" }
The version number could be equal or lower to or lower than the GG version number. Say if you are running GG V23.6, it could be 23.4, 23.5, or 23.6.
It returns an integer value. 0 means success. Any non-zero value is a failure. oggDomain, oggAlias and oggUserid are the input parameters to identify the Database user info. oggPassword is the output parameter that returns the password fetched from the vault.
This is where you can write your own code to retrieve the secret from any 3rd party Vault using SDKs provided by the vendors.
The sample code for using with OCI Vault is under OGG_HOME/src/PluginExamples/OCIVault/OCIVault.go
This code is written in GoLang using the Oracle OCI SDK to demonstrate how to retrieve a secret from OCI Vault. The secret is the password that will be used to login to the Oracle Database with the specified userid. GoldenGate stores that userid as an alias in its credentialstore under <domain_name>.<alias_name>. The domain_name and alias_name are used as input parameters to call the plugin, which is later used as the secret name identifier to retrieve the secret (password) from the OCI Vault.
A make file has been provided under OGG_HOME/src/PluginExamples/OCI/Makefile. If you are using Linux, just run make, it will compile the code from OCIVault.go and generate a user library, named libOCIVault.so
Copy the compiled user library, in the sample, named as libOCIVault.so, to <GG Service Manager Home>/var/lib/plugins/
Issue the RestAPI to activate this plugin as a new service under Service Manager.
Assuming your Service Manager is running locally on port 9011, here is what the command will look like:
shell>OGG_ADMIN_PASSWORD="xxxx"
shell>curl -svu "oggadmin:${OGG_ADMIN_PASSWORD}" http://127.0.0.1:9011/services/v2/deployments/ServiceManager/services/pluginsrvr \
-XPOST --data '{"$schema":"ogg:service", "config":"external", "enabled":true, "critical":true, "status":"running"}'
If you are using nginx or a secured deployment, please make sure you use https instead of http, and the appropriate CA certificate path in the command line.
Once it is successfully enabled, you will find the service will show up as ServiceManager.pluginsrvr under the Service Manager Service
The password needs to be stored as a secret in the vault. The secret name must match the GoldenGate credentialstore domain_name.alias_name where the Database login was stored. Typically, the domain name is OracleGoldenGate, and the alias is your chosen name for creating it.
For example,
(** Please don't execute this ALTER CREDENTIALSTORE comm; it is just for illustrating the naming convention here. This command will be executed later once everything is in place)
OGG (http://127.0.0.1:9011 Deployment) 2> ALTER CREDENTIALSTORE ADD USER ggadmin@//dbms:1521/ORCLPDB1 ALIAS ggadmin NOPASSWORD
2024-04-02T18:34:14Z INFO OGG-15114 Credential store altered.
The secret name in this case will be OracleGoldenGate.ggadmin
Password plugins are used when an ALIAS is created in GoldenGate Credentialstore with the `NOPASSWORD` option and without a leading '/' character (which indicates Kerberos authentication).
Verify the secret is created in the vault that holds the password for this Database user ggadmin. Make sure the secret name matches the expected naming convention.
The plugin from the sample code will support the following authentication for the vault access depending on the value of the environmental variable OCI_AUTH
In this blog, we are using the Instance Principal. So we have to set OCI_AUTH=instance_principal
Also, we need to provide the vault OCID with the environmental variable OCI_VAULT_OCID.
Both must be set up correctly in the environmental variable section under the Service Manager's Configuration.
Once the change is made, bounce the Service Manager to make sure the setting will be activated.
To make instance principal authentication work, the VM instance needs to be added to a dynamic group. This dynamic group needs a policy to use the secret in that vault.
When I created my VM instance, I assigned a tag, Werner.Usage = VaultTest, to it, It makes the dynamic group creation easier by using that tag. Details can be found in OCI Documentation Managing Dynamic Groups
Now we need to create a policy to allow this dynamic group to use the secret resource. More details can be found in OCI documentation Vault Service Details
Once the above steps are completed, we can use the GoldenGate adminclient to create the Database login alias with the NOPASSWORD option and test it out.
❯ $OGG_HOME/bin/adminclient
Oracle GoldenGate Administration Client for Oracle
Version 23.5.1.24.07 OGGCORE_23.5.0.0.0OGGRU_LINUX.X64_240728.2258_FBO
Copyright (C) 1995, 2024, Oracle and/or its affiliates. All rights reserved.
Linux, x64, 64bit (optimized) on Jul 29 2024 04:39:15
Operating system character set identified as US-ASCII.
OGG (not connected) 1> CONNECT http://127.0.0.1:9011 AS oggadmin
Using default deployment 'Deployment'
OGG (http://127.0.0.1:9011 Deployment) 2> ALTER CREDENTIALSTORE ADD USER ggadmin@//dbms:1521/ORCLPDB1 ALIAS ggadmin NOPASSWORD
2024-04-02T18:34:14Z INFO OGG-15114 Credential store altered.
OGG (http://127.0.0.1:9011 Deployment) 3> DBLOGIN USERIDALIAS ggadmin
Successfully logged into database.
OGG (http://127.0.0.1:9011 Deployment as ggadmin@ORCLCDB) 4>
The library could be written in any language as long as it could be compiled into a shared user library. The most popular languages will be GoLang, C/C++, and Python.
It also helps to use the OCI CLI to test whether the instance principal authentication works on the VM first to verify that all the dynamic group and policy settings are correct.
shell>oci secrets secret-bundle get-secret-bundle-by-name --secret-name OracleGoldenGate.ggadmin --vault-id ocid1.vault.oc1.us-sanjose-1.xxxxxxxxxxxxp4mfxwta --auth instance_principal
{
"data": {
"metadata": null,
"secret-bundle-content": {
"content": "R0dTUjBja3Mh",
"content-type": "BASE64"
},
"secret-id": "ocid1.vaultsecret.oc1.us-sanjose-1.xxxxxxxxxxx5vsup5lz5knta",
"stages": [
"CURRENT",
"LATEST"
],
"time-created": "2024-08-26T05:35:18.435000+00:00",
"time-of-deletion": null,
"time-of-expiry": null,
"version-name": null,
"version-number": 1
}
}
Product Manager for Oracle GoldenGate.
Working in Oracle GoldenGate for 20+ years. Covering from the very original GoldenGate Mainframe product to the latest OCI GoldenGate Services. Focusing on OCI GoldenGate Service promotion in Oracle Applications. In-depth knowledge of Oracle GoldenGate architecture in various use cases. Specialized in GoldenGate TLS/SSL for distribution path, Trail encryption, IdP with IAM.
Previous Post
Next Post