Using Oracle Enterprise Manager 12c Command Line Interface Part 3 – Credential Management Commands

Many of the activities that DBAs do through the Oracle Enterprise Manager 12 Cloud Control GUI interface can also be accomplished via the Command Line Interface (EM CLI).  Last month, we explored how to install and configure the EM CLI.  This article will explore the commands used for managing credentials for Cloud Control.

A Review of OEM 12c Cloud Control Credentials

Credentials are used to access most of the targets managed in EM12c, in particular database and host targets.  In many cases the credentials are a combination of username and password and are encrypted and stored in Enterprise Manager.

There are five categories of credentials in 12c Cloud Control:  Named Credentials, Job Credentials, Monitoring Credentials, Collection Credentials and Preferred Credentials. 

Named Credentials

Named credentials are stored as their own independent objects in EM.  Administrators can define and store credentials with an object name. EM Administrators are granted access to a named credential to be used to do activities against a target.  What is extremely powerful about named credentials is the fact that the user who is accessing a target or running a job using a named credential in EM12c, never actually sees the sensitive information (such as the password) associated with the named credential. 

Job Credentials

In EM12c Cloud Control, the job system uses the credential subsystem to get the appropriate information to submit a job to a target.  When submitting a job, the administrator can configure the job to use preferred credentials, named credentials or new credentials set up for the job.

Monitoring Credentials

The monitoring credentials are used by Management Agents on certain targets.  The most common example would be database targets.  In order to monitor a database there has to be a connection to that database that includes a username, password and generally a role. 

Monitoring credentials stored in EM12c Cloud Control can be also be used by other applications to connect to the target from the OMS. 

Collection Credentials

These are the credentials associated with metric extensions and their precursors, user defined metrics.  For many metrics to be collected, analyzed and tested, a connection to the target via credentials is required.

Preferred Credentials

Preferred credentials simplify access to the targets by storing the login credentials for a target in EM.  Administrators can use the preferred credentials to connect to a target without being prompted to log into the target each time they try to access that object.  Preferred credentials are set on a per user basis.

Using EM CLI to Manage Credentials

Clearing Credentials

The following commands clear credential information using the EM CLI.

clear_credential

This command clears preferred or monitoring credentials for a specified user.

emcli clear_credential
	-target_type=”type”
	-target_name=”name”
	-credential_set=”set_name”
	-user=”username”
	-oracle_homes=”ohome1;ohome2”

• Target type – must be host if oracle_homes are included
• Target name – name of the target in EM
• Credential set – name of credential set to be cleared
• User – EM user name (if none specified the current user is assumed)
• Oracle homes – credentials are cleared for all homes listed

For example:  I want to clear the named credential called NM_CRED1 from user Karen on the database called “Payroll”

emcli clear_credential
	-target_type=oracle_database
	-target_name=payroll
	-credential_set=NM_CRED1
	-user=Karen

clear_default_pref_credential

This command clears the credential set as the default preferred credential for that user for that target.  The actual named credential itself is not deleted, only the use of that named credential as the default preferred credential.

emcli clear_default_pref_credential
	-set_name=”name”
	-target_type=”type”

Set Name = name of credential set to clear as the default

For example: I want to clear any host target that uses the named credential MyHostCred as the default preferred credential.

emcli clear_default_pref_credential
	-set_name=MyHostCred
	-target_type=host

clear_monitoring_credential

This command only clears the monitoring credential set associated with a target.

emcli clear_monitoring_credential
	-set_name=”name”
	-target_name=”name”
	-target_type=”type”

For example: to clear the monitoring credential called MyMonCred for the database called payroll.

emcli clear_monitoring_credential
	-set_name=MyMonCred
	-target_name=payroll
	-target_type=oracle_database

clear_preferred_credential

This command clears the credential set as the named preferred credential for that user for that target.  The actual named credential itself is not deleted, only the use of that named credential as the preferred credential.

emcli clear_preferred_credential
	-set_name=”name”
	-target_name=”name”
	-target_type=”type”

Creating Credentials

The following commands are used to create and store credential sets.

create_credential_set

This command is used to create a credential set; it can only be executed by a super administrator account.

emcli create_credential_set
	-set_name=”name”
	-target_type=”type”
	-supported_cred_types=”supported type”
	-monitoring
	-auth_target_type=”authenticating target type”
	-description

• Set name – the name to assign to the credential set
• Target type – the type of target
• Supported Cred Types –  a list of credential types that this credential set can be used for (use the show_credential_type_info command to see a list of valid types)
• Monitoring – creates this as a monitoring credential set
• Auth Target Type – list of target types that can use this credential set – this defaults to the value of Target Type
• Description – an optional description of the credential set

For Example: to create a host credential set that can be used as both regular and ssh host credentials.

emcli create_credential_set
	-set_name=MyCredSet
	-target_type=host
	-supported_cred_types=HostCreds;SSHHostCreds
	 

create_named_credential

This command is used to create a named credential.  The tags can be specified in the command, or placed into a properties file.  We can also use the input_file option for specifying passwords and parameter values.

emcli create_named_credential
	-cred_name=”name”
	-auth_target_type=”auth type”
	-cred_type=”credential type”
	-cred_scope=”scope”
	-cred_desc=”description”
	-target_name=”name”
	-target_type=”type”
	-test
	-test_target_name=”name”
	-test_target_type=”type”
	-input_file=”tag:value”
	-input_bfile=”tag:value”
	-properties_file=”filename”
	-attributes=”param1:value1;param2:value2....”

• Cred Name – name of the credential
• Auth Target Type – the type of target for this credential
• Cred Type – the type of credential being created (use the show_credential_type_info command to see a list of valid types)
• Cred Scope – is this a global or instance credential (default is global)
• Cred Desc – a description
• Target Name – the specific target name for an instance credential
• Target Type – the target type for an instance credential
• Test – test the credential before saving
• Test Target Name – the target to test the credential on, required for global credentials where test is specified
• Test Target Type – the type of target to test, required for global credentials where test is specified
• Input File – use this file to specify sensitive data
• Input Bfile – supply data using a binary file
• Properties File – use this file to provide all parameters (any parameters specified on the command line will take precedence)
• Attributes – specific values used to set the credential

For example: to create a named credential called KR_OS_CRED that logs into a host with the username Karen and password of Ron – with the ability to sudo as root we can use the following:

emcli create_named_credential
	-cred_name=KR_OS_CRED
	-auth_target_type=host
	-cred_type=HostCreds
	-attributes=”HostUserName:Karen;HostPassword=Ron;PDTYPE:SUDO;
	 RUNAS:root”

Deleting Credentials

The following commands are used to delete credential sets, only a super administrator can delete credential sets and any out-of-the-box credential sets cannot be deleted.

delete_credential_set

Deletes the credential set.

emcli delete_credential_set 
	-set_name=”name”
	-target_type=”type”

delete_named_credential

Deletes a named credential.

emcli delete_named_credential_set
	-cred_owner=”owner”
	-cred_name=”name”

Retrieving Credential Information

get_credtype_metadata

This command prints the information for a credential type, it prints the column names to be used as parameter names for the create_named_credential and modify_named_credential commands.

emcli get_credtype_metadata
	-auth_target_type=”type”
	-cred_name=name

For example – to see all the parameters for HostCreds:

emcli get_credtype_metadata
	-auth_target_type=host
	-cred_name=HostCreds 

get_duplicate_credential

This command provides a list of credentials with the same values as the one that you provide.

emcli get_duplicate_credential
	-cred_name=”name”
	-cred_owner=”owner”

For example – to see if there are other named credentials with the exact same settings as MyDBCred owned by Karen:

emcli get_duplicate_credential
	-cred_name=MyDBCred
	-cred_owner=Karen

get_named_credential

This command displays the information for a specific credential to an output file.

emcli get_named_credential
	-cred_owner=”owner”
	-cred_name=”name”
	-out=”filename”

Merging Credentials

merge_credentials

This command is used to merge credentials into one – it is useful after running the get_duplicate_credential command and discovering that we have more than one credential essentially doing the same thing.

emcli merge_credentials
	-destination_credential=”merge into here”
	-source_credential_list=”list of credentials to merge”
	-merge_all
	-merge_without_testing

• Destination Credential – name and owner of the credential to merge into
• Source Credential List – list of source credentials to be merged
• Merge All – find all duplicates and merge them
• Merge Without Testing – merge without testing the destination credential

For example – to merge MyCred2 and MyCred3 (owned by Karen) into MyCred1

emcli merge_credentials
	-destination_credential=”MyCred1:Karen”
	-source_credential_list=”MyCred2:Karen;MyCred3:Karen”

To merge all duplicates of MyCred1

emcli merge_credentials
	-destination_credential=”MyCred1:Karen”
	-merge_all

Modifying Existing Named Credentials

modify_named_credential

This command modifies the settings of a named credential.  Only specify the particular option you wish to modify.

emcli create_named_credential
	-cred_name=”name”
	-auth_target_type=”auth type”
	-cred_type=”credential type”
	-cred_scope=”scope”
	-cred_desc=”description”
	-target_name=”name”
	-target_type=”type”
	-test
	-test_target_name=”name”
	-test_target_type=”type”
	-input_file=”tag:value”
	-input_bfile=”tag:value”
	-properties_file=”filename”
	-attributes=”param1:value1;param2:value2….”
	-remove_old_attributes

• Cred Name – name of the credential
• Auth Target Type – the type of target for this credential
• Cred Type – the type of credential being created (use the show_credential_type_info command to see a list of valid types)
• Cred Scope – is this a global or instance credential (default is global)
• Cred Desc – a description
• Target Name – the specific target name for an instance credential
• Target Type – the target type for an instance credential
• Test – test the credential before saving
• Test Target Name – the target to test the credential on, required for global credentials where test is specified
• Test Target Type – the type of target to test, required for global credentials where test is specified
• Input File – use this file to specify sensitive data
• Input Bfile – supply data using a binary file
• Properties File – use this file to provide all parameters (any parameters specified on the command line will take precedence)
• Attributes – specific values used to set the credential
• Remove Old Attributes – unsets any existing credential column values

For example: To change the password associated with the named credential KR_OS_CRED:

emcli modify_named_credential
	-cred_name=KR_OS_CRED
	-attributes=”HostPassword:monkey”

Setting credentials for users

These commands are used to set the credentials for the EM users.

set_credential

emcli set_credential
	-target_type=”type”
	-target_name=”name”
	-credential_set=”set”
	-user=”user”
	-columns=”col1:val1;col2:val2…”
	-input_file=”tag:file”
	-oracle_homes=”home list”
	-monitoring

• Target Type- if host is specified, oracle_homes must also be specified
• Target Name – name of target
• Credential Set – name of credential set to be assigned
• User – EM user’s whose credentials will be set (defaults to the current user)
• Columns – name and new value of every column to be set, every column that is part of the credential set must be specified
• Input File – optional
• Oracle Homes – must be specified if target type is host
• Monitoring – indicates if monitoring credentials should be affected (defaults to preferred)

For example: to set the username, password and role for the credential set called MyDBCred for user Karen:

emcli set_credential
	-target_type=oracle_database
	-target_name=payroll
	-credential_set=MyDBCred
	-user=Karen
	-column=”username:Karen;password:Ron;role:myrole”

set_default_pref_cred

This command assigns a named credential as a default preferred credential for a target.

emcli set_default_pref_credential
	-set_name=”name”
	-target_type=”type”
	-credential_name=”name”
	-credential_owner=”owner”
	-test
	-test_target_name=”name”

For example: To set the MyHostCred as the default preferred credential for hosts:

emcli set_default_pref_credential
	-set_name=HostCredsNormal
	-target_type=host
	-credential_name=MyHostCred
	-credential_owner=Karen

set_monitoring_credential

This command sets a monitoring credential set for a target.

emcli set_monitoring_credential
	-target_name=”name”
	-target_type=”type”
	-set_name=”name”
	-cred_type=”type”
	-auth_target_type=”type”
	-test
	-input_file=”tag/value”
	-propeties_file=filename
	-attributes=”param1:val1;param2:val2...”

For example: To set the monitoring credentials for the payroll database:

emcli set_monitoring_credential
	-target_name=payroll
	-target_type=oracle_database
	-set_name=MyDBMonCred
	-cred_type=DBCreds
	-attributes=”DBUserName:Karen;DBPassword:Ron;
	 DBRole:DBNormal”

set_preferred_credential

This command is used to set the preferred credentials for a target for a user.

emcli set_preferred_credential
	-set_name=”name”
	-target_type=”type”
	-target_name=”name”
	-credential_name=”name”
	-credential_owner=”owner”
	-test

Displaying Credential Information

The following commands are used to display credential information.

emcli show_credential_set_info
-target_type=”type”
-set_name=”name”

emcli show_credential_type_info
	-target_type=”type”
	-type_name=”name”

Testing Credentials

The following command can be used to test named credentials.

emcli test_named_credential
	-cred_names=”name list”
	-target_type=”type” (required for global credentials)
	-target_name=”name” (required for global credentials)

General Update Commands for Credentials

update_host_password

This command updates a changed host password in the credential system – for monitoring credentials the password change is propagated to the EM Agents.  You will be prompted to enter the old password, the new password and retype the new password.

emcli update_host_password
	-target_name=”name”
	-user_name=”name”
	-change_all_references=”yes|no”
	-input_file
update_monitoring_creds_from_agent

This command finds all targets for the agent, retrieves the monitoring passwords and then updates them in the EM repository.

emcli update_monitoring_creds_from_agent
	-emd_list=”list of agents” (if not using update_all)
	-update_all
	 

For example – to update monitoring credentials based on the agent on host01:

emcli update_monitoring_creds_from_agent
	-emd_list=”host01:1832”

update_password

This command updates passwords for a given target.

emcli update_password
	-target_type=”type”
	-target_name=”name”
	-credential_type=”type”
	-key_column=”col_name:col_val”
	-non_key_column=”col1:old_val:new_val;col2:old_val:new_val…..”
	-input_file

·         Key Column – name and value of the key column (generally the user name)

·         Non Key Column – name and value of the non-key column(s) – generally the password

For example – to change the password for database credentials for user Karen from Ron to monkey.

emcli update_password
	-target_type=oracle_database
	-target_name=payroll
	-credential_type=DBCreds
	-key_column=”DBUserName:Karen”
	-non_key_column=”DBPassword:Ron:Monkey”

update_target_password

This command updates a changed target password in the credential system – for monitoring credentials the password change is propagated to the EM Agents.  You will be prompted to enter the old password, the new password and retype the new password.

emcli update_target_password
	-target_type=”type”
	-target_name=”name”
	-key_column=”col:val”
	-change_all_references=”yes|no”

For example – to change the target passwords for the payroll database for user Karen:

emcli update_target_password
	-target_type=oracle_database
	-target_name=payroll
	-key_column=”DBUserName:Karen”
	-change_all_references=yes

As you can see – we have a very comprehensive list of commands available in the Enterprise Manager Command Line Interface for working with the credential sub-system of EM.

See all articles by Karen Reliford