GoldenGate Password Plugin

September 10, 2024 | 6 minute read
Werner He
Senior Director of Oracle GoldenGate Product Management
Text Size 100%:

GoldenGate Password Plugin

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.

1. Where to find the plugin component

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.

2. The Plugin API interface

A minimum of two function APIs need to exist in this plugin.

a. getManifest()

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.

b. getUseridAliasPassword(oggDomain *C.char, oggAlias *C.char, oggUserid *C.char, oggPassword *C.char)

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. 

3. A sample code for OCI Vault

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.  

4. How to compile

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

5. How to enable it

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

Plugin Service

6. How to use it

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.

Vault and Secret

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

  • instance_pricinpal, Instance Principal authentication
  • DEFALT, Default profile in the OCI config file
  • Any customized name, Customized profile in the OCI config file

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.

Environmental Variable Setting in Service Manager

 

Once the change is made, bounce the Service Manager to make sure the setting will be activated.

Restart Service Manager

 

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

Dynamic Group

 

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

Policy to use Secret

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>
 

Additional Information

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

  }

}

Werner He

Senior Director of Oracle GoldenGate Product Management

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.  

Show more

Previous Post

How to connect to GoldenGate with IDCS Federation using adminclient

Adriano Tanaka | 3 min read

Next Post


A Step-by-Step Guide to Setting Up GoldenGate DAA 23ai for MongoDB and Oracle JSON Database Integration

Carmelo Millan Rosales | 6 min read