PAM Security Administrator Role

A PAM security team should guide the EM administrator team to build a script and provide the necessary parameters required for the script execution. This script is required to access the PAM provider using REST endpoints to retrieve credentials for databases or hosts at runtime. The script can be written in Shell or Perl.

EM Administrator Role

Step 1: Develop a script to access PAM credentials

As a PAM Security Administrator, work with your Security or PAM team to develop a script for PAM tools such as CyberArk, HashiCorp, and Oracle Key Vault. This custom script connects to a PAM system and retrieves the necessary credentials. The script must meet the following requirements:

• Must be written in Shell or Perl. Binary files are not supported.

• Can use any method to fetch credentials like REST or command line tool.

• Each credential stored in the PAM system can be referred to using a unique identifier, called a Credential Key. The Credential Key should also be passed on as an argument to the script. You can decide how the argument should be passed, for example any of the formats listed below:

  sh getcreds.sh -k CredKey

  
  sh getcreds.sh -credkey CredKey

  
  sh getcreds.sh CredKey

• Credentials or authentication tokens required to authenticate a PAM system should be passed through stdin as key:value pair, not specified in the script. Use one of the ways as shown below:

  1. The script only requires an authentication token to access the PAM system. When the script is run, it should prompt you to input the auth token via stdin:

     sh getcreds.sh -k CredKey
     authtoken:token

  2. The script requires the PAM username and password for the PAM system authentication. Upon running the script, it requests you to provide the PAM username and password, which will be entered through stdin:

     pamuser:user
     pampassword:password

  3. The script requires multiple authentication mechanisms to access the PAM system, including the PAM username, password, certificate path, and certificate key. When executed, the script will prompt you to input the PAM username and password, along with the certificate details:

     pamuser:user
     pampassword:password
     pamcertpath:path
     pamcertkey:key

     A script built to accept certain input parameters securely through stdin can be configured as is in Enterprise Manager, so when EM executes the script it passes the values for such input parameters through stdin.

• The script should fetch and print the credentials in a name:value format as shown below.

  sh getcreds.sh -k EMDB/sysman
  pamuser:user
  pampassword:password

  In the above example, EMDB/sysman is the Credential key and user/password is the credential fetched from the PAM system.

• The script should capture error/exception during execution. The errors should be formatted as string, and should be written to stderr for EM to read and show it in GUI and in calling subsystem processes.

• The script will be run on any of the OMS hosts in a multi-OMS setup, so all the software installation and configuration required for script execution should be done on all the OMS hosts.

Step 2: Register the PAM Provider with EM

As an EM Administrator, register the PAM provider with EM using the EM CLI command emcli config_cred_provider.

This is a new verb that allows the credential provider to be configured with the required attributes.

emcli config_cred_provider
[-provider_name=\"provider name\"]
[-provider_type=\"provider type\"]
[-access_cred_type=\"cred type\"]
-params="params"
[-refparams="params"]
[-input_file="FILE:file_path"]
[-separator="separator:attribute_name:character"]
[-subseparator="subseparator:attribute_name:character"]

Options:

• -provider_name: Name of the provider to configure and should contain only alphabets, numbers, hyphen(-) and underscore(_) and not exceed 64 characters.

• -provider_type: Credential provider type. The current allowed value is ScriptProvider.

• -access_cred_type: The type of credential that is required to authenticate against this credential provider.

  Example: In case of using PAM user credentials to authenticate with PAM system then create named credentials of type "Host Credentials using the PAM user and password and provide -access_cred_type="HostCreds" and then map the named credential to PAM provider created using set_credprovider_cred.

• -params : Comma separated set of name=value pairs. It can be used in conjunction with - input_file to specify tags to file paths that contain longer content.

  Example:

  -params="Command:sh %ScriptFile% -key %CredKey%;StdInVars:CACertLoc,AuthToken;ScriptFileExt:sh;Script:getCyberArkPassword" 

  • Example commands that need to be run to fetch credential from PAM depending on the script type being used:

    • sh %ScriptFile% -key %CredKey%

    • perl %ScriptFile% -k %CredKey%

    ScriptFile and CredKey are mandatory keywords, while %ScriptFile% will be replaced by the script file name (in OMS file system), and %CredKey% will be replaced by the credential key provided while creating the named credential.

  • StdInVars: list of input parameters separated by comma that needs to be passed through standard input

    Example:

    StdInVars:AuthToken;
    StdInVars:CACertLoc,AuthToken;

  • ScriptFileExt: supported script file extensions:

    • sh
    • pl
  • Script: tag pointing to the actual script file path which will be defined in the parameter input_file.

• -input_file: to specify tag pointing to actual file path.

  Example:

  -input_file="getCyberArkPassword:/u01/app/pam_scripts/getcreds.sh" 

• -refparams: Comma separated set of name=value pairs. Can be used to map input parameters to integration script to any of three below mentioned OMS properties:

  • "oracle.sysman.core.security.auth.cred_provider_prop1"
  • "oracle.sysman.core.security.auth.cred_provider_prop2"
  • "oracle.sysman.core.security.auth.cred_provider_prop3"

Example:

sh getcreds.sh -k CredKey
pamuser:user
pampassword:password
authtoken:token

./emcli config_cred_provider
-provider_name="CyberArk"
-provider_type=ScriptProvider \
-params="Command:sh %ScriptFile% -k %CredKey%;StdInVars:CACertLoc,AuthToken;ScriptFileExt:sh;Script:getCyberArkPassword"\
-input_file="getCyberArkPassToken:/u01/app/pam_scripts/getcreds.sh"\
-refparams="AuthToken:oracle.sysman.core.security.auth.cred_provider_prop1,CACertLoc:oracle.sysman.core.security.auth.cred_provider_prop2"

Once the script is registered in EM, it is stored in the repository table EM_NC_CREDPROVIDER_PARAMS and you can run a select query to see the data. Here is an example of a query:

SELECT * FROM EM_NC_CREDPROVIDER_PARAMS;

Step 3: Create the Credentials Attributes Mappings

Credentials mappings map the keys in the script output (user and password in this example) to credential attributes like HostUserName and HostPassword. Store an attribute mapping to convert stored attributes to those required by credential type. In order to find the credential type attribute names, run the following command:

emcli get_credtype_metadata -authtargettype=<authenticating target type> -credtype=<credential type>

For example, the following command lists the attribute names for HostCreds credential type and host target type.

emcli get_credtype_metadata -authtargettype=host -credtype=HostCreds

Run the following command to create the credentials mappings:

emcli store_cred_mapping
-mapper_name="mapper name" 
-mapper_desc="mapper description" 
-cred_type="cred type" 
-attributesmap="attributes map"

Options:

• -mapper_name: Name of the mapper.
• -mapper_desc: Description of the mapper
• -cred_type: Type of credential that this mapping is intended for.
• -attributesmap: Comma separated set of name=value pairs that maps attributes stored in the credential provider to attributes of the specified credential type.

Here are some examples of mappings for a host and a database:

• Host

  emcli store_cred_mapping 
  -mapper_name="PAMtoHostCreds" 
  -mapper_desc="Map PAM credential attributes to HostCreds type" 
  -auth_target_type=host -cred_type="HostCreds" 
  -attributesmap="user:HostUserName;pass:HostPassword"

• Database

  emcli store_cred_mapping 
  -mapper_name="PAMtoDBCreds" 
  -mapper_desc="Map PAM credential attributes to DBCreds type" 
  -auth_target_type=oracle_database 
  -cred_type="DBCreds" 
  -attributesmap="user:DBUserName;pass:DBpassword"

Once the credential mapping is created this information is stored in the EM repository tables EM_NC_CRED_MAPPERS and EM_NC_CRED_MAPPER_COLUMNS.

Here is an example to check in repository database:

SELECT m.mapper_name, m.cred_type_name, mc.storage_attr, mc.cred_attr
FROM EM_NC_CRED_MAPPERS m, EM_NC_CRED_MAPPER_COLUMNS mc 
WHERE mc.mapper_guid = m.mapper_guid
ORDER BY m.mapper_name;

./emcli create_named_credential 
-cred_name=OEM_SYSPAM -auth_target_type=oracle_database
-cred_type=DBCreds 
-alt_cred_storage 
-cred_provider=PAM360 
-cred_key="HRDB/sys"
-cred_mapping=PAM360toDBCreds 
-attributes="DBRole:SYSDBA"

./emcli store_cred_mapping 
-mapper_name="PAM360toDBCreds" 
-mapper_desc="Map PAM 360 credential attributes to DBCreds type" 
-auth_target_type=oracle_database
-cred_type="DBCreds"
-attributesmap="user:DBUserName;pass:DBpassword"

./emcli create_named_credential 
-cred_name=OEM_SYSPAMD 
-auth_target_type=oracle_database
-cred_type=DBCreds 
-alt_cred_storage 
-cred_provider=PAM360 
-cred_key="HRDB/sys"
-cred_mapping=PAM360toDBCreds
-attributes="DBUserName:sys;DBRole:SYSDBA"

./emcli store_cred_mapping 
-mapper_name="PAM360toDBCreds" 
-mapper_desc="Map PAM 360 credential attributes to DBCreds type" 
-auth_target_type=oracle_database
-cred_type="DBCreds" 
-attributesmap="pass:DBpassword"

Step 4: Create or Modify the Named Credentials

Starting with Oracle Enterprise Manager 13c Release 5 Update 20 (13.5.0.20) credentials can be created using the CLI or the UI.

To create credentials using the UI, from the Settings drop-down menu, go to Security, and click Named Credentials. Click Create, and select the PAM radio button for the Credential Properties options.

Follow the steps bellow to create the credentials as an EM Administrator, using the CLI:

1. Use an EM CLI verb to create the new credentials in EM with an alternate credential storage type. The following example creates the named credential ssh1 based on the SSH key named credentials for host myhost.example.com. It indicates that the credential attributes are stored in the OracleKeyVault credential provider at the location emssh1 and that the mapping named OKVSSHCreds can map the attributes required for the HostSSHCreds credential type.

   emcli create_named_credential 
   -cred_name=ssh1
   -auth_target_type=host 
   -cred_type=HostSSHCreds 
   -target_name="myhost.example.com" 
   -target_type=host
   -cred_scope=instance
   -alt_cred_storage
   -cred_provider=<PAM Provider> 
   -cred_key=emssh1
   -cred_mapping=OKVSSHCreds

2. Modify the Named Credentials as needed. Similar to create_named_cred, the modify_named_credential verb also takes the additional parameters : alt_cred_storage, cred_provider, cred_key, cred_mapping

   The following example modifies the named credential ssh1 based on the SSH key named credentials for host myhost.example.com. It indicates that the credential attributes are stored in the OracleKeyVault credential provider at the location emssh1 and that the mapping named OKVSSHCreds can map the attributes required for the HostSSHCreds credential type.

   emcli modify_named_credential
   -cred_name=<credential name> 
   -auth_target_type=host
   -cred_type=HostSSHCreds 
   -target_name="myhost.example.com"
   -target_type=host
   -cred_scope=instance
   -alt_cred_storage
   -cred_provider=OracleKeyVault-cred_key=emssh1
   -cred_mapping=OKVSSHCreds

   Examples:

   emcli modify_named_credential 
   -cred_name=ORACLE 
   -cred_type=HostCreds 
   -target_type=host 
   -cred_scope=global 
   -alt_cred_storage 
   -cred_provider=PAM360 
   -cred_key="DBHost/oracle" 
   -cred_mapping=PAM360toHostCreds
   

   emcli modify_named_credential 
   -cred_name=OEM_SYS 
   -cred_type= DBCreds 
   -auth_target_type=oracle_database 
   -cred_scope=global 
   -alt_cred_storage 
   -cred_provider=PAM360 
   -cred_key="HRDB/sys" 
   -cred_mapping=PAM360TODBCREDS

   The credential name, type and owner, and storage provider and key, and mapper name are stored in the EM repository tables EM_NC_CRED_MAPPERS and EM_NC_CREDS.

   Here is an example of a query of this data:

   SELECT c.cred_owner, c.cred_type_name, c.cred_name, c.storage_provider, c.storage_key, m.mapper_name
   FROM EM_NC_CREDS c, EM_NC_CRED_MAPPERS m
   WHERE c.cred_name IN ('MANIDB_SYSMAN', 'DBSNMP_LOCAL')
   AND c.storage_cred_mapper_guid = m.mapper_guid (+)

3. Validate the stored credential by querying the registered and configured PAM provider. The list_cred_mappings is a new verb that shows the result of the earlier store_cred_mapping requests. The list_credential_providers is a new verb that shows the result of the earlier config_cred_provider request.

   emcli list_credential_providers

   Lists the configured credential providers.

   emcli list_cred_mappings 
   -cred_type="cred_type" [-cred_owner="cred_owner"]

   Lists the configured credential mappings for a given credential type (and optional credential owner).

   Options:

   • -cred_type: lists the credential type for which the mappings are requested

   At the completion of these steps, the PAM provider is registered with EM and either a new credential or a modified existing named credential is set up to use the external storage type.

Case 1

Use global OMS properties to store script input parameters for PAM system authentication. This is useful when you have a dedicated PAM user for the PAM system access.

• "oracle.sysman.core.security.auth.cred_provider_prop1"
• "oracle.sysman.core.security.auth.cred_provider_prop2"
• "oracle.sysman.core.security.auth.cred_provider_prop3"

Example:

sh getcreds.sh -k CredKey
pamuser:user
pampassword:password
authtoken:token

./emcli config_cred_provider-provider_name="CyberArk"\
-provider_type=ScriptProvider\
-params="Command:sh %ScriptFile% -k %CredKey%;StdInVars:CACertLoc,AuthToken;ScriptFileExt:sh;Script:getCyberArkPassword"\
-input_file="getCyberArkPassToken:/u01/app/pam_scripts/getcreds.sh"\
-refparams="AuthToken:oracle.sysman.core.security.auth.cred_provider_prop1,CACertLoc:oracle.sysman.core.security.auth.cred_provider_prop2"

Case 2

Use a named credential to store the PAM authentication details like the PAM user credentials. This is useful when you use individual PAM credentials for the PAM system access.

1. The script that prompts you to enter PAM user details:

   sh getcreds.sh 
   -k CredKey
   pamuser:user
   pampassword:password

2. Create a config cred provider with access to the credential type HostCreds:

   ./emcli config_cred_provider-provider_name="CyberArk"\
   -provider_type=ScriptProvider\
   -access_cred_type="HostCreds"\
   -params="Command:sh %ScriptFile% -k %CredKey%;StdInVars:CACertLoc,AuthToken;ScriptFileExt:sh;Script:getCyberArkPassword"\
   -input_file="getCyberArkPassToken:/u01/app/pam_scripts/getcreds.sh"\
   -refparams="AuthToken:oracle.sysman.core.security.auth.cred_provider_prop1"

3. Create a named credential to store PAM user details:

   emcli create_named_credential 
   -cred_name="PAMCreds" 
   -auth_target_type=host
   -cred_type=HostCreds
   -attributes="HostUserName:pam_username;HostPassword:pam_password"

4. Set credential to be used for cred provider:

   emcli set_credprovider_cred 
   -provider_name= CyberArk 
   -cred_name="PAMCreds"

Patching with Fleet Maintenance

Here are some examples of use cases you can try using Fleet Maintenance. For more information, see Database Fleet Maintenance