12 Managing Oracle Key Vault Endpoints

Oracle Key Vault endpoints are computer systems like database or application servers, where keys and credentials are used to access data.

• Overview of Managing Endpoints
  You can manage endpoints in standalone, primary-standby and multi-master clusters in mostly the same way, except that multi-master clusters have more restrictions.
• Managing Endpoints
  You can enroll, reenroll, suspend, rotate, and delete endpoints.
• Managing Endpoint Details
  Endpoint details refers to endpoint name, type, description, platform, and email, and adding the endpoint to a group, or upgrading the endpoint software.
• Managing Global and Per-Endpoint Configuration Parameters and Settings
  Oracle Key Vault provides global and per-endpoint configuration parameters and settings that you can set in the Oracle Key Vault management console.
• Default Wallets and Endpoints
  You can use a default wallet, which is a type of virtual wallet, with an endpoint.
• Managing Endpoint Access to a Virtual Wallet
  You can grant an endpoint access to a virtual wallet, and revoke or modify access when it is no longer necessary.
• Managing Endpoint Groups
  An endpoint group is a named group of endpoints that share a common set of wallets.

12.1 Overview of Managing Endpoints

You can manage endpoints in standalone, primary-standby and multi-master clusters in mostly the same way, except that multi-master clusters have more restrictions.

• About Managing Endpoints
  You must register and enroll an endpoint to communicate with an Oracle Key Vault server.
• How a Multi-Master Cluster Affects Endpoints
  You should be aware of how a multi-master cluster affects endpoints, both in the way an endpoint connects to it and with restrictions.

12.1.1 About Managing Endpoints

You must register and enroll an endpoint to communicate with an Oracle Key Vault server.

Afterward, keys in the endpoint can be uploaded to Oracle Key Vault and be shared with other endpoints and then downloaded from these endpoints so that users can access their data. Only a user with the System Administrator role or the Create Endpoint privilege can add an endpoint to Oracle Key Vault. After the endpoint is added, the endpoint administrator can enroll the endpoint by downloading and installing the endpoint software at the endpoint. The endpoint can then use the utilities packaged with the endpoint software to upload and download security objects to and from Oracle Key Vault.

All users can create virtual wallets but only a user with the Key Administrator role can grant endpoints access to security objects contained in virtual wallets. A Key Administrator user can grant access on any wallet to an endpoint. A user with the Key Administrator role or Create Endpoint Group privilege can also Create Endpoint Groups to enable shared access to virtual wallets. Any user (including users who created the endpoint) who has the manage wallet permission on a wallet can grant access to that wallet to an endpoint. When you grant an endpoint group access to a virtual wallet, all the member endpoints will have access to the virtual wallet. For example, you can grant all the nodes in an Oracle Real Application Clusters (Oracle RAC) database access to a virtual wallet by putting them in an endpoint group. This saves you the step of granting each node access to the virtual wallet. As an added layer of security, the Key Administrator user can enable or disable the extraction of symmetric keys from Oracle Key Vault.

If you have a large deployment, Oracle recommends that you install at least four Oracle Key Vault servers, and when you enroll the endpoints, balance them across these four servers to ensure high availability. For example, if a data center has 1000 database endpoints to register, and you have four Oracle Key Vault servers to accommodate them, then enroll 250 endpoints across each of the four servers.

When you name an endpoint, you cannot use an Oracle Key Vault server user name as the endpoint name.

Ensure that the system clocks of the endpoint host and the Oracle Key Vault server are in sync. For Oracle Key Vault server, setting up NTP is recommended. Drift between endpoint time and Oracle Key Vault server time may result in issues during endpoint enrollment. When Oracle Key Vault issues the endpoint certificate, the endpoint certificate time is set on the Oracle Key Vault server. Endpoint enrollment becomes an issue if the Oracle Key Vault server time is ahead of the endpoint certificate enrollment time.

Note:

Ensure that the system time on the endpoint host and the Oracle Key Vault server is in sync for successful endpoint enrollment.

When a user with Create Endpoint or Endpoint Group privilege creates an endpoint or endpoint group, Oracle Key Vault indirectly grants the Manage Endpoint or Endpoint Group to the user.

The administrative roles and privileges as they pertain to endpoints are as follows:

• Endpoint creation: A user with either the System Administrator role or the Create Endpoint privilege can create endpoints in Oracle Key Vault. A user with the Create Endpoint privilege is automatically granted the Manage Endpoint privilege on any endpoints that they create.
• Endpoint management: A user with the System Administrator role can Manage Endpoints anywhere in the Oracle Key Vault system. A user with the Manage Endpoint privilege can manage only his or her own endpoints. This includes endpoints that the user was explicitly granted the Manage Endpoint privilege on, or endpoints that the user created and continues to have the Manage Endpoint privilege on. This management includes the following duties:
  • Managing the endpoint metadata such as the name, type, platform, description, and email notifications
  • Managing the endpoint life cycle, which consists of enrolling, suspending, re-enrolling, rotating, and deleting endpoints
• Endpoint group creation: A user with the Key Administrator role or Create Endpoint Group privilege can create endpoint groups in Oracle Key Vault. A user with the Create Endpoint Group privilege is automatically granted the Manage Endpoint Group privilege on any endpoint groups that they create.
• Endpoint group management: A user with the Key Administrator role can manage endpoint groups anywhere in the Oracle Key Vault system. A user with the manage endpoint group privilege can manage only his or her own endpoint groups. The endpoint groups that a user can manage include those that the user was explicitly granted the manage endpoint group privilege on, or those that the user created and continues to have the manage endpoint group privilege on. This management includes the following duties:
  • Managing the endpoint group lifecycle, which consists of creating, modifying, and deleting endpoint groups
  • Managing the life cycle of security objects, which consists of creating, modifying and deleting security objects

12.1.2 How a Multi-Master Cluster Affects Endpoints

You should be aware of how a multi-master cluster affects endpoints, both in the way an endpoint connects to it and with restrictions.

In a multi-master configuration, when an endpoint attempts to make a connection to Oracle Key Vault, it performs the following actions:

• First, it obtains the list of server IPs from its configuration file (okvclient.ora).
• Next, it picks one at random, preferentially from those in the same cluster subgroup as the endpoint.

Be aware of the following restrictions with how endpoints work in multi-master clusters:

• An endpoint can only be enrolled from the same node where it was most recently created or reenrolled.
• You can assign a default wallet to an endpoint if one or both of them (wallet and endpoint) is in the PENDING state, but not if the assignment is attempted from a non-creator node. After both the endpoint and wallet are in the ACTIVE state, this restriction ends.

12.2 Managing Endpoints

You can enroll, reenroll, suspend, rotate, and delete endpoints.

• Types of Endpoint Enrollment
  The first step in enrolling an endpoint is to add the endpoint to Oracle Key Vault.
• Endpoint Enrollment in a Multi-Master Cluster
  Endpoints of a cluster are the client systems of the multi-master cluster.
• Adding an Endpoint as an Oracle Key Vault System Administrator or Create Endpoint User
  A user who has been granted the System Administrator role or the Create Endpoint privilege can add an endpoint by using the Endpoints tab.
• Adding Endpoints Using Self-Enrollment
  The self-enrollment process immediately sends the endpoint to the Enrolled status without the intermediate Registered status.
• Deleting, Suspending, Reenrolling, or Rotating Endpoints
  When endpoints no longer use Oracle Key Vault to store security objects, you can delete them. You can also suspend, and later resume them when they are needed. You can also re-enroll or rotate endpoints when necessary.

12.2.1 Types of Endpoint Enrollment

The first step in enrolling an endpoint is to add the endpoint to Oracle Key Vault.

There are two methods for adding, also known as registering, an endpoint:

• Initiated by an administrator

  An Oracle Key Vault user who has the System Administrator role initiates the enrollment from the Oracle Key Vault side by adding the endpoint to Oracle Key Vault. When the endpoint is added, a one-time enrollment token is generated. This token can be communicated to the endpoint administrator in two ways:

  • Directly from Oracle Key Vault by email. To use email notification you must configure SMTP in email settings.
  • Out-of-band method, such as email or telephone.

  The endpoint administrator uses the enrollment token to download the endpoint software and complete the enrollment process. In a multi-master cluster, the same node that is used to add the endpoint must be used to enroll the endpoint.

  After the enrollment token is used to enroll an endpoint, it cannot be used again for another enrollment. If you are reenrolling an endpoint, then the reenrollment process will generate a new one-time enrollment token for this purpose.

• Self-enrolled

  Endpoints may enroll themselves during specific times without human administrative intervention. Endpoint self-enrollment is useful when the endpoints do not share security objects, and use Oracle Key Vault primarily to store and restore their own security objects. Another use for endpoint self-enrollment is testing.

  A self-enrolled endpoint is created with a generic endpoint name in this format: ENDPT_001. In a cluster, a self-enrolled endpoint is created with a generic endpoint name in this format: ENDPT_xx_001, where xx is a 2-digit node identifier or node number. Initially, a self-enrolled endpoint has access only to the security objects that it uploads or creates. It does not have access to any virtual wallets. You can later grant the endpoint access to virtual wallets after verifying its identity.

  Endpoint self-enrollment is disabled by default, and must be enabled by a user with the System Administrator role. Oracle recommends that you enable self-enrollment for short periods, when you expect endpoints to self enroll, and then disable it when the self-enrollment period ends.

12.2.2 Endpoint Enrollment in a Multi-Master Cluster

Endpoints of a cluster are the client systems of the multi-master cluster.

Endpoint enrollment is divided into two steps. First you create the endpoint and then you enroll it.

The Oracle Key Vault server that becomes the controller node can have endpoints already enrolled, especially if it was upgraded from a previous release. These existing endpoints initialize, or seed, the cluster. During induction, information about the endpoints that were enrolled in the cluster is replicated to the newly added node. Oracle Key Vault also removes information about the endpoints that were previously enrolled in all candidate nodes added to the cluster.

Endpoints can only be enrolled on a read-write node.

After you enroll the endpoint, the new endpoint will have a cluster-wide presence. You can add endpoints of the Oracle Key Vault multi-master cluster to any read-write node.

Note:

An endpoint must be enrolled on the same node where it was most recently added or reenrolled.

New endpoints added concurrently to the multi-master cluster on different nodes could have name conflicts. Oracle Key Vault automatically resolves the endpoint name conflicts, and then displays the conflicts in a Conflicts Resolution page. From here, a system administrator can choose to rename them.

12.2.3 Adding an Endpoint as an Oracle Key Vault System Administrator or Create Endpoint User

A user who has been granted the System Administrator role or the Create Endpoint privilege can add an endpoint by using the Endpoints tab.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Create Endpoint privilege.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.

   
   Description of the illustration 21.5_endpoint_page.png

   The Endpoints page displays the list of registered and enrolled endpoints with the following endpoint details: name, type, description, platform, status, enrollment token, alert, endpoint certificate expiration, common name of certificate issuer, and last active time. This listing of endpoints depends on who is logged in. The endpoint information listing depends on who is logged-in, some details such as the enrollment token, and the buttons listed above the table on Endpoints page may be visible depending on the user's role or privilege status. For example, a user with the System Administrator role can see buttons related to all operations such as Add, Suspend, and Resume, while one with only the Create Endpoint privilege can see only the Add button. The endpoint status can be either Registered or Enrolled:

   • Registered Status: The endpoint has been added and the one-time enrollment token has been generated. This token will be displayed in the corresponding Enrollment Token column.
   • Enrolled Status: The one-time enrollment token has been used to download the endpoint software. The Enrollment Token column displays a dash (-) to indicate that the enrollment token has been used. If you do not have the System Administrator role (that is, you have the Manage Endpoint privilege), then you can only view enrollment tokens for those endpoints that you can manage.
   • Created By: The user who created the endpoint. If the user no longer exists, or if the endpoint was created in a version before this information was stored, then this field will show ANONYMOUS.
   • Creator Node: The node on which the endpoint was created. This is specific to multi-master cluster environments.
   • Name Status: The state of the endpoint. The state will be either ACTIVE or PENDING. This is specific to multi-master cluster environments.
   • Cluster Subgroup: The subgroup on which the endpoint was created. This is specific to multi-master cluster environments.
3. On the Endpoints page, click Add.
   The Register Endpoint page appears. The Make Unique check box and Cluster Subgroup drop-down only appears in multi-master cluster mode.

   
   Description of the illustration 21_add_endpoint.png

4. In the Endpoint Name field, enter a name for the endpoint.
   See Naming Guidelines for Objects.
5. If you are using a multi-master cluster, then choose whether to select the Make Unique checkbox.

   Make Unique helps to control naming conflicts with names across the multi-master cluster environment. Endpoints that were created before an Oracle Key Vault conversion to a cluster node are not affected by naming conflicts.

   • If you select Make Unique, then the endpoint will be active immediately and users can use this endpoint.
   • If you do not select Make Unique, then the endpoint will be created in the PENDING state. Oracle Key Vault will then begin a name resolution operation and may rename the endpoint to a name that is unique across the cluster. If there is a naming collision, then the collision will be reported on the Conflicts page on any node in the cluster. The endpoint will then be renamed to a unique name. You will need to go to a read-write node of the cluster and either accept the renamed endpoint or change the endpoint name. If you change the endpoint name, then this will restart the name resolution operation and the endpoint will return to a PENDING state. An endpoint in the PENDING state cannot be used to perform most operations.
6. From the Type drop-down list, select the type of endpoint.
   Supported types are Oracle Database, Oracle Database Cloud Service, Oracle (non-database), Oracle ACFS, MySQL Database, SSH Server, and Other. An example of Other is a third-party KMIP endpoint. If you are using Oracle Advanced Security Transparent Data Encryption (TDE) and want to use Oracle Key Vault to manage a TDE master encryption key or wallet, then you must set Type to Oracle Database.
7. Complete the following endpoint information:
   • Platform: Supported platform choices are Linux, Solaris SPARC, Solaris x64, AIX, HP-UX, and Windows.
   • Description: Optionally, enter a useful identifying description such as the host name, IP address, function, or location of the endpoint.
   • Administrator Email: Optionally, enter the email address of the endpoint administrator to have the enrollment token and other endpoint-related alerts sent directly from Oracle Key Vault. You must have SMTP configured to use the email notification feature.
   • Cluster Subgroup: For a multi-master cluster environment, select a subgroup for the endpoint. If you select No Cluster Subgroup, then the endpoint will not be a part of any cluster subgroup. If you select the option suffixed with (from Creator Node), the endpoint will be a part of the cluster subgroup to which its creator node belongs, even if the creator node's cluster subgroup changes. All other options assign an endpoint to an existing cluster subgroup, to which it will belong regardless of its creator node's cluster subgroup.
   • SSH Server Hostname: For type SSH Server, enter the hostname or the IP address of the SSH server host on which the Oracle Key Vault Secure Shell (SSH) endpoint will be deployed.
8. Click Register.
   The Endpoints page appears listing the new endpoint with a status of Registered. The Enrollment Token column displays the one-time enrollment token.

   
   Description of the illustration 21.5_endpoint_page.png

9. Click the endpoint name to see details for the endpoint.
   The Endpoint Details page appears.

   
   Description of the illustration 21.5_endpoint_details_updated.png

   The Send Enrollment Token button on the Endpoint Details page only appears for an endpoint whose Status is Registered. The users with the System Administrator role or the Manage Endpoint privilege for the endpoint can view an Endpoint's enrollment token, or Send Enrollment Token button.

   There are two ways to send the one-time enrollment token to the endpoint administrator:

   • If you did configure SMTP and entered the email address, you can have Oracle Key Vault send the enrollment token directly to the endpoint administrator, shown in the next step, where you click the Send Enrollment Token button.
   • If you did not configure SMTP or enter the email address, then you must use an out-of-band method to send the enrollment token to the endpoint administrator.

   The endpoint must be enrolled and the endpoint jar file must be downloaded from the node on which the endpoint was most recently created or reenrolled.

10. Click Send Enrollment Token.
    At this stage, the endpoint’s administrator can complete the enrollment process for the endpoint. When the enrollment token is used to download and install the endpoint software on the endpoint side, the endpoint status changes from Registered to Enrolled.

12.2.4 Adding Endpoints Using Self-Enrollment

The self-enrollment process immediately sends the endpoint to the Enrolled status without the intermediate Registered status.

• About Adding Endpoints Using Self-Enrollment
  Oracle Key Vault associates a self-enrolled attribute with all endpoints that are enrolled through endpoint self-enrollment.
• Adding an Endpoint Using Self-Enrollment
  You can configure the self-enrollment process for endpoints from the Oracle Key Vault management console.

12.2.4.1 About Adding Endpoints Using Self-Enrollment

Oracle Key Vault associates a self-enrolled attribute with all endpoints that are enrolled through endpoint self-enrollment.

Self-enrolled endpoints go directly to Enrolled status without the intermediate Registered status when a user downloads the endpoint software. You can recognize self-enrolled endpoints by their system generated names in the format ENDPT_001. In a multi-master cluster, system generated endpoint names are in the format ENDPT_node_id_sequential_number, where node_id is a value such as 01 or 02. For example, ENDPT_01_001 can be the generated name of an endpoint.

Endpoint self-enrollment is disabled by default and must be enabled by a user who has the System Administrator role.

A best practice is to enable endpoint self-enrollment for limited periods when you expect endpoints to enroll. After the expected endpoints have been enrolled, you should disable endpoint self-enrollment.

12.2.4.2 Adding an Endpoint Using Self-Enrollment

You can configure the self-enrollment process for endpoints from the Oracle Key Vault management console.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab, and then Settings from the left navigation bar.
   The Endpoint Settings page appears.

   
   
   Description of the illustration 21_endpoint_settings.png
   

3. Check the box to the right of Allow Endpoint Self-Enrollment.
4. Click Save.

12.2.5 Deleting, Suspending, Reenrolling, or Rotating Endpoints

When endpoints no longer use Oracle Key Vault to store security objects, you can delete them. You can also suspend, and later resume them when they are needed. You can also re-enroll or rotate endpoints when necessary.

• About Deleting Endpoints
  Deleting an endpoint removes it permanently from Oracle Key Vault.
• Deleting One or More Endpoints
  The Endpoints page enables you to delete a group of endpoints from Oracle Key Vault at one time.
• Deleting One Endpoint (Alternative Method)
  The Endpoint Details page provides a consolidated view for the selected endpoint including a mechanism to delete the endpoint from Oracle Key Vault.
• Suspending an Endpoint
  You can suspend an endpoint temporarily for security reasons, and then reinstate the endpoint once the threat has passed. You can choose to suspend unused endpoints during the CA certificate rotation process to allow the CA certificate rotation process to complete.
• Reenrolling an Endpoint
  When you reenroll an endpoint, the enrollment process automatically upgrades the endpoint software and also generates new endpoint certificates.
• Rotating Endpoint Certificates
  Rotating an endpoint's certificate extends its certificate validity without incurring downtime for the endpoint.

12.2.5.1 About Deleting Endpoints

Deleting an endpoint removes it permanently from Oracle Key Vault.

However, security objects that were previously created or uploaded by that endpoint will remain in Oracle Key Vault. Similarly, security objects that are associated with that endpoint also remain. To permanently delete or reassign these security objects, you must be a user with the Key Administrator role or authorized to merge these objects by managing wallet privileges. The endpoint software previously downloaded at the endpoint also remains on the endpoint until the endpoint administrator removes it.

You cannot delete an endpoint that is in the PENDING state unless you are the user who created it. You must delete it on the node on which it was created.

12.2.5.2 Deleting One or More Endpoints

The Endpoints page enables you to delete a group of endpoints from Oracle Key Vault at one time.

You can also delete a single endpoint from this page.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Manage Endpoint privilege on that endpoint.
   A user who has the Manage Endpoint privilege can only delete endpoints on which this user has been granted the Manage Endpoint privilege. To see which endpoints that a user can manage, select the Users tab, then select Manage Users. Check the User Details page for the user in question, and scroll down to the Access to Endpoints area.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page lists all the endpoints currently registered or enrolled.
3. In the Endpoints page, select the check boxes to the left of the endpoints that you want to delete.
4. Click Delete.
5. In the confirmation window, click OK.

   Note:

   To uninstall the endpoint software for the deleted endpoint, remove the endpoint software installation directory or the OKV_HOME. You should also delete the links from $ORACLE_HOME/okv/$ORACLE_SID and $ORACLE_BASE/okv/$ORACLE_SID, if they exist. If there is no other database using Oracle Key Vault on this machine, then consider removing the liborapkcs.so also from /opt/oracle/extapi/64/hsm/oracle/1.0.0 directory on Linux x86-64, Solaris, AIX, and HP-UX (IA) installations and from C:\oracle\extapi\64\hsm\oracle\1.0.0 directory on Windows installations.

12.2.5.3 Deleting One Endpoint (Alternative Method)

The Endpoint Details page provides a consolidated view for the selected endpoint including a mechanism to delete the endpoint from Oracle Key Vault.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Manage Endpoint privilege on that endpoint.
   A user who has the Manage Endpoint privilege can only delete endpoints on which this user has been granted the Manage Endpoint privilege. To see which endpoints that a user can manage, select the Users tab, then select Manage Users. Check the User Details page for the user in question, and scroll down to the Access to Endpoints area.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. Click the endpoint name that you want to delete.
   The Endpoint Details page appears.
4. Click Delete.
5. In the confirmation window, click OK.

12.2.5.4 Suspending an Endpoint

You can suspend an endpoint temporarily for security reasons, and then reinstate the endpoint once the threat has passed. You can choose to suspend unused endpoints during the CA certificate rotation process to allow the CA certificate rotation process to complete.

When you suspend an endpoint, its status will change from Enrolled to Suspended. You cannot suspend an endpoint that is in the PENDING state unless you are the user who created it.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Manage Endpoint privilege.
   A user with the Manage Endpoint privilege can only suspend endpoints that they can manage.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, select the check boxes to the left of the endpoints that you want to suspend.
4. Click Suspend.
5. In the confirmation window, click OK.
   When you suspend an endpoint, its Status on the Endpoints page will be Suspended.
6. To enable the endpoint, perform Steps 1-3.
   From the Endpoint Details pane click Enable. The endpoint Status on the Endpoints page will now read Enrolled.

The following rules apply to suspending an endpoint in a multi-master cluster:

• For regular endpoints, the endpoint will continue to operate until all suspend operation requests have reached all nodes in the cluster.
• You can suspend the endpoint on any node.
• For cloud-based endpoints, the endpoint will continue to operate until the suspend operation has reached all nodes from where the reverse SSH tunnel is established.
• You can potentially suspend the endpoint on any node from the cloud-based endpoint from where the reverse SSH tunnel is established.

12.2.5.5 Reenrolling an Endpoint

When you reenroll an endpoint, the enrollment process automatically upgrades the endpoint software and also generates new endpoint certificates.

You must also reenroll an endpoint to accommodate changes such as pairing a primary Oracle Key Vault server with a new secondary server in a primary-standby configuration. The action of reenrolling an endpoint will immediately disallow any connections from the endpoint's old deployment. If you are reenrolling an endpoint, Oracle recommends that you immediately download okvclient.jar and deploy it in a directory that is separate from the existing deployment. When you deploy the software, use the -o option to overwrite the symbolic link pointing to the old okvclient.ora. You cannot reenroll an endpoint that is in the PENDING state unless you are the user who created the endpoint.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Manage Endpoint privilege.
   A user who has the Manage Endpoint privilege can only reenroll endpoints that he or she created.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, check the boxes to the left of the endpoints that you want to reenroll.
4. Click Reenroll.

   A new enrollment token will be generated for each reenrolled endpoint and appear in the corresponding Enrollment Token column. You can use this one-time token to reenroll the endpoint. You must download the endpoint jar file from the same node on which the endpoint was reenrolled.

   Note:

   After you deploy the okvclient.jar file, the message 
The endpoint software for Oracle Key Vault installed successfully 

should appear. If, instead, the message 
The endpoint software for Oracle Key Vault upgraded successfully 

appears, then the re-enrollment was performed in the old deployment directory, and as a result, the endpoint software was upgraded but not successfully re-enrolled.

   You can overwrite the symbolic link reference that points to okvclient.ora in the new directory by using the okvclient.jar option -o.

   A new enrollment token will be generated for each reenrolled endpoint and appear in the corresponding Enrollment Token column. You can use this one-time token to reenroll the endpoint. You must download the endpoint jar file from the same node on which the endpoint was reenrolled.

12.2.5.6 Rotating Endpoint Certificates

Rotating an endpoint's certificate extends its certificate validity without incurring downtime for the endpoint.

Endpoints communicate with Oracle Key Vault using TLS certificates. When an endpoint’s certificate is close to expiration, you can rotate the endpoint so that it is issued with a new certificate without incurring downtime.

Note:

You can determine the remaining time to expiration of the endpoint certificate from the Oracle Key Vault Management console, by navigating to the Endpoints page and checking the Endpoint Certificate Expiration field.

See Also:

Finding the Expiration Date of the CA Certificate

You can also monitor the expiration of an endpoint certificate by configuring the Endpoint Certificate Expiration alert so as to receive a reminder when an endpoint certificate is due to expire.


See Also:

Configuring Oracle Key Vault Alerts

If an endpoint is not rotated before its certificate expires, it will experience downtime. You must re-enroll the endpoint when that happens. 
You can rotate a single endpoint, or multiple endpoints at once. Rotating an endpoint generates a new certificate on Oracle Key Vault. The endpoint must then reach out to Oracle Key Vault to receive this new certificate, and subsequently acknowledge receipt of the certificate back to Oracle Key Vault to fully complete the certificate rotation.

To rotate the endpoint certificates, perform the following steps.

1. Log into the Oracle Key Vault management console as a user with the System Administrator role, or the Manage Endpoint privilege on the given endpoint(s).
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, check the boxes to the left of the endpoints that you want to rotate.
4. Click Rotate.

   This process can take several minutes to complete, depending on the number of endpoints that are being rotated. After a few minutes, the message “One or more endpoints rotated successfully” appears. For each rotated endpoint, the Common Name of Certificate Issuer field on the Endpoints page is changed to Updating to Current Certificate Issuer. In the backend, Oracle Key Vault has generated a new certificate for each rotated endpoint.

   An endpoint that has been rotated will receive its new certificate the next time that it reaches out to Oracle Key Vault. In a multi-master cluster, the endpoint must reach out to the Oracle Key Vault cluster node on which the endpoint certificate was rotated in order to receive the new certificate. After the endpoint has received its new certificate, it must acknowledge receipt back to Oracle Key Vault. When that happens, the endpoint is considered to have completed rotation, and its Common Name of Certificate Issuer is changed from Updating to Current Certificate Issuer to the Common Name of the Current Oracle Key Vault CA Certificate. Its Endpoint Certificate Expiration field should show the new expiration date of its certificate.

   • When one or more endpoints are rotated, a banner with the message Certificate Rotation In Progress is displayed on the Endpoints page. In a multi-master cluster, this banner is displayed on the Endpoints page of all cluster nodes. It remains until all rotated endpoints successfully receive and acknowledge receipt of their new certificate, that is, complete certificate rotation. You can check how many endpoints are still being rotated through the Common Name of Certificate Issuer field on the Endpoints page. For any endpoints that have not yet completed the rotation, this field will continue to display Updating to Current Certificate Issuer.
   • In a multi-master cluster environment, the endpoint will receive its new certificate only when it reaches out to the cluster node on which its certificate was rotated. Since the endpoint can communicate with any node in the endpoint node scan list, the endpoint may run many operations before it reaches the creator node and receives its certificate. The endpoint also has to acknowledge the receipt of the new certificates by reaching out to a node in the cluster.
   • The endpoint certificate rotation times increases with the number of nodes in the cluster. The endpoints prioritize the nodes in the local subgroup, hence consider rotating the endpoint certificate on a node in its cluster subgroup.


   • In a multi-master cluster environment, endpoint certificate rotation can take a long time because the endpoint must reach out to the issuing node to receive its new certificate. Oracle recommends that you rotate the endpoint certificate well ahead of its expiration in order to avoid re-enrolling the endpoint (which would incur downtime).
   • When an endpoint is rotated, the validity of its new certificate depends on the Endpoint Certificate Validity configuration parameter of the Oracle Key Vault deployment, and on the remaining time to expiration of the Oracle Key Vault CA certificate.




• Guidelines for Rotating Endpoint Certificates
  Consider these Oracle Key Vault guidelines before you rotate an endpoint certificate.

12.2.5.6.1 Guidelines for Rotating Endpoint Certificates

Consider these Oracle Key Vault guidelines before you rotate an endpoint certificate.

Guidelines for Endpoint Certificate Rotation

• Do not rotate an endpoint certificate while a CA certificate rotation is in progress.
• Do not rotate an endpoint certificate rotation while a server or node certificate rotation is in progress.
• Do not alter the Endpoint Certificate Validity parameter while an endpoint certificate rotation is in progress.
• Consider rotating an endpoint from a node in the cluster subgroup that the endpoint is associated with.
• Do not rotate an endpoint if its certificate has already expired. Consider re-enrolling it instead.
• Consider re-enrolling an endpoint if it does not receive its new certificate due to network or other issues.
• Ensure that the endpoint software has been upgraded to version 21.5.0.0.0 or later before rotating the endpoint.

12.3 Managing Endpoint Details

Endpoint details refers to endpoint name, type, description, platform, and email, and adding the endpoint to a group, or upgrading the endpoint software.

• About Endpoint Details
  The Endpoint Details page provides a consolidated view of the endpoint.
• Modifying Endpoint Details
  You can modify the endpoint name, endpoint type, description, platform, and email.

12.3.1 About Endpoint Details

The Endpoint Details page provides a consolidated view of the endpoint.

To access this page, you can select the Endpoints tab and then click the name of an endpoint. From here you can modify endpoint details and complete endpoint management tasks. (The following screen shows a partial view.)

Description of the illustration 21.5_endpoint_details.png

12.3.2 Modifying Endpoint Details

You can modify the endpoint name, endpoint type, description, platform, and email.

In a multi-master cluster, endpoint details can only be modified while the endpoint is in the PENDING state by the creator on the node on which it was created.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Manage Endpoint privilege.
   A user who has the Manage Endpoint privilege can only modify endpoints that this user has created. To see which endpoints that a user can manage, select the Users tab, then select Manage Users. Check the User Details page for the user in question, and scroll down to the Access to Endpoints area.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, click the name of the endpoint.
   The Endpoint Details page appears.
   Description of the illustration 21.5_endpoint_details.png
4. In the Endpoint Details page, modify any of the following: Endpoint Name, Type, Description, Platform, Administrator Email, Cluster Subgroup (for multi-master cluster environments only), or Strict IP Check.
   The Strict IP Check setting is enabled by default for any endpoint that was created in Oracle Key Vault. If you select this check box, then Oracle Key Vault checks if the endpoint is connecting to it using the same IP that was used when the endpoint software was first deployed. If you disable this check box, then Oracle Key Vault allows the endpoint to connect to it using any IP address. Oracle recommends that you enable this setting unless otherwise required.
   See Naming Guidelines for Objects.
5. Click Save.

12.4 Managing Global and Per-Endpoint Configuration Parameters and Settings

Oracle Key Vault provides global and per-endpoint configuration parameters and settings that you can set in the Oracle Key Vault management console.

• About Managing Global and Per-Endpoint Configuration Parameters and Settings
  Users who have the System Administrator role or the Key Administrator role can centrally update certain endpoint configuration parameters and settings in the Oracle Key Vault management console. 
• Global Endpoint Configuration Parameters and Settings
  You can set endpoint configuration parameters and settings globally for all endpoints in the Oracle Key Vault management console.
• Per-Endpoint Configuration Parameters and Settings
  You can set different endpoint configuration parameters and settings for individual endpoints in the Oracle Key Vault management console.

12.4.1 About Managing Global and Per-Endpoint Configuration Parameters and Settings

Users who have the System Administrator role or the Key Administrator role can centrally update certain endpoint configuration parameters and settings in the Oracle Key Vault management console. 

Setting endpoint configuration parameters and settings globally (for all endpoints) or on a per-endpoint basis simplifies the process of managing multiple endpoints for system and key administrators.

You can perform the following types of global endpoint and per-endpoint settings:

• Endpoint configuration parameters: These include settings that control features such as the length of time that a certificate is valid, timeouts for various PKCS 11 settings, and the timeout in seconds for a client's attempt to connect to an Oracle Key Vault server. Only a user who has the System Administrator role or the Manage Endpoint privilege for a specific endpoint can modify these parameters. Users who have the System Administrator role can modify endpoint configuration parameters for all endpoints. Users who have the Manage Endpoint privilege can modify the configuration parameters individually for each endpoint to which they have access. To do so, this user must go to the Details page for the endpoint, scroll to the bottom, and then modify the endpoints from there.
• Keys and secrets: This includes setting the extractable attribute value for symmetric keys. Only a user who has the Key Administrator role can modify this setting.

When Changes in Global and Per-Endpoint Values Take Effect

The configuration parameter values that are set in the Oracle Key Vault management console are applied to endpoints dynamically. The next time that the endpoint contacts Oracle Key Vault server, the updated configuration parameters are applied to the endpoint. If there is an error, then the update is not applied.

If you use the RESTful services utility, then Oracle Key Vault does not update the endpoint configuration. In this case, use okvutil, C SDK, JAVA SDK, or the PKCS11 library to apply the endpoint configuration updates.

In a multi-master cluster, replication of configuration parameters and settings depends on the replication lag. It is possible that an endpoint will not be able to get an update immediately because the node to which it is connected may not yet have received the new values of the parameters or settings. The endpoint will refresh its configuration when it connects to a node that has new values or if it has not refreshed its configuration in the past hour.

Precedence and Inheritance of Global and Per-Endpoint Values

Values that are set for an individual endpoint take precedence over the same values that are set globally. Global parameters and settings take effect when endpoint-specific parameters and settings are cleared. Oracle Key Vault uses the default system parameters and settings if both the global and endpoint specific parameters are cleared or not set from Oracle Key Vault management console.

In the case of keys and secrets, suppose you create a new symmetric key or private key but do not specify an extractable attribute value at the time of the symmetric or private key's creation. The key will inherit the default value that has been set for the individual endpoint in which the symmetric or private key was created. If the default extractable attribute value has not been set for this endpoint, then the key will inherit the global endpoint value for the extractable attribute. If this global endpoint value has not been set, then the extractable attribute value defaults to true. Suppose later on, you change the global endpoint extractable attribute value so that future endpoints will use this value. Similar to configuration parameters, the values set in the individual endpoint that already exists take precedence over the same value that is set globally.

12.4.2 Global Endpoint Configuration Parameters and Settings

You can set endpoint configuration parameters and settings globally for all endpoints in the Oracle Key Vault management console.

• Setting Global Endpoint Configuration Parameters
  You can set global endpoint configuration parameters in the Oracle Key Vault management console.
• Configuring Global Endpoint Settings for Keys and Secrets
  You can set the default extractable attribute value for new symmetric keys that you create or register in the endpoint configuration.

12.4.2.1 Setting Global Endpoint Configuration Parameters

You can set global endpoint configuration parameters in the Oracle Key Vault management console.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the Endpoints tab, and then Settings from the left navigation bar.

   The Endpoint Settings page appears.

   
   Description of the illustration 21_endpoint_settings.png

3. In the Global Endpoint Configuration Parameters section, configure the following settings:
   • Endpoint Certificate Validity ( in days ): Specify the number of days for which the current endpoint certificate is valid. Valid settings are 365 through 1095. The default is 365. When the endpoint enrolled, the endpoint certificate validity period will always be less than the CA certificate validity period.
   • PKCS 11 In-Memory Cache Timeout ( in minutes ): Specify the duration in minutes for which the master encryption key is available after it is cached in the in-memory cache.

     PKCS 11 Persistent Cache Timeout ( in minutes ): Specify the duration in minutes for which the master encryption key is available after it is cached in the persistent master encryption key cache.

   • PKCS 11 Persistent Cache Refresh Window ( in minutes ): Specify the duration in minutes to extend the period of time for which the master encryption key is available after it is cached in the persistent master encryption key cache.
   • PKCS11 Configuration Parameter Refresh Interval ( in minutes ): Specify the frequency at which a long-running process will re-read the okvclient.ora configuration file.
   • Server Poll Timeout ( in milliseconds ): Specify a timeout in seconds for a client's attempt to connect to an Oracle Key Vault server, before trying the next server in the list. The default value is 300 (milliseconds). In Oracle Key Vault clients first establish a non-blocking TCP connection to Oracle Key Vault to quickly detect unreachable servers. After the first attempt, the client makes a second and final attempt to connect to the server but this time waits for twice as long as the duration specified by the SERVER_POLL_TIMEOUT parameter. This is done to overcome possible network congestion or delays.
   • PKCS 11 Trace Directory Path: Specify a directory to save the trace files.
   • Expire PKCS11 Persistent Cache on Database Shutdown: Enables or disables the PKCS#11 persistent cache for a given endpoint database to automatically expire upon shutdown of the endpoint database.

   Note:

   If the Global Endpoints Configuration Parameters values are empty, it indicates that the manually customized values in the okvclient.ora file are in effect. After you set these values in the Oracle Key Vault management console, you must edit these values from the Oracle Key Vault management console only. You cannot set empty values.
4. Click Save.

12.4.2.2 Configuring Global Endpoint Settings for Keys and Secrets

You can set the default extractable attribute value for new symmetric keys that you create or register in the endpoint configuration.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role.
2. Select the Endpoints tab, and then Settings from the left navigation bar.
   The Endpoint Settings page appears.
3. Scroll down to the Global Endpoint Settings for Keys & Secrets section.

   
   
   Description of the illustration 216_global_ep_settings_keys_secrets.png
   

4. From the Symmetric Key menu, select one of the following choices:

   • True (default) allows the object value to be extracted from Oracle Key Vault.

   • False prevents the object value from being extracted from Oracle Key Vault.

5. From the Private Key menu, select one of the following choices:

   • True (default) allows the object value to be extracted from Oracle Key Vault.

   • False prevents the object value from being extracted from Oracle Key Vault.
6. Save these settings using the following choices:
   • Save Defaults sets the default value (of TRUE) which is used as the default value or the extractable attribute.
   • Save sets a value that is used as the default value for the extractable attribute.

12.4.3 Per-Endpoint Configuration Parameters and Settings

You can set different endpoint configuration parameters and settings for individual endpoints in the Oracle Key Vault management console.

• Modifying Configuration Parameters for an Individual Endpoint
  A user who has the System Administrator role or the Manage Endpoint privilege can set configuration parameters for individual endpoints.
• Configuring Endpoint Settings for Keys and Secrets for an Individual Endpoint
  A user who has the Key Administrator role can set values for keys and secrets in an individual endpoint.

12.4.3.1 Modifying Configuration Parameters for an Individual Endpoint

A user who has the System Administrator role or the Manage Endpoint privilege can set configuration parameters for individual endpoints.

1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role or the Manage Endpoint privilege.
   A user with the System Administrator role can set configuration parameters for any endpoint. A user with the Manage Endpoint privilege can only set configuration parameters for the endpoints for which the user has the Manage Endpoint privilege.
2. Select the Endpoints tab, and then Endpoints from the left navigation bar.
3. In the Endpoints page, select the endpoint that you want to modify.
4. In the Endpoint Details page, scroll down to the Endpoint Configuration Parameters area.
5. Modify the configuration parameters as necessary.
   The configuration parameters are the same as the configuration parameters that can be modified globally.

   Note:

   If the Endpoints Configuration Parameters values are empty, it indicates that the manually customized values in the okvclient.ora file are in effect. After you set these values in the Oracle Key Vault management console, you must edit these values from the Oracle Key Vault management console only. You cannot set empty values.
6. Click Save.

12.4.3.2 Configuring Endpoint Settings for Keys and Secrets for an Individual Endpoint

A user who has the Key Administrator role can set values for keys and secrets in an individual endpoint.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role.
2. Select the Endpoints tab, and then Endpoints from the left navigation bar.
3. In the Endpoints page, select the endpoint that you want to modify.
4. In the Endpoint Details page, scroll down to the Endpoint Settings for Keys & Secrets area.
5. Select one of the following settings from the Symmetric Key menu:
   • True allows the object value to be extracted from Oracle Key Vault.
   • False prevents the object value from being extracted from Oracle Key Vault.
   • Use Global Settings (default) uses the global endpoint setting for the Extractable attribute.
6. Select one of the following settings from the Private Key menu:
   • True allows the object value to be extracted from Oracle Key Vault.
   • False prevents the object value from being extracted from Oracle Key Vault.
7. Click Save.

12.5 Default Wallets and Endpoints

You can use a default wallet, which is a type of virtual wallet, with an endpoint.

• Associating a Default Wallet with an Endpoint
  A default wallet is a type of virtual wallet to which security objects are uploaded when a wallet is not explicitly specified.
• Setting the Default Wallet for an Endpoint
  Setting a default wallet for an endpoint automatically uploads the endpoint's security objects to the wallet if another wallet is not explicitly specified.

12.5.1 Associating a Default Wallet with an Endpoint

A default wallet is a type of virtual wallet to which security objects are uploaded when a wallet is not explicitly specified.

Default wallets are useful for sharing with other endpoints such as nodes in an Oracle Real Application Clusters (Oracle RAC), or primary and standby nodes in Oracle Data Guard by having all endpoints use the same default wallet.

If you want to use the default wallet, then you must set this wallet after you register the endpoint before you enroll it. If you decide to use a default wallet after enrollment, then you must remove the default wallet and subsequently reenroll the endpoint.

An enrollment status of registered means that the endpoint has been added to Oracle Key Vault, but the endpoint software has not yet been downloaded and installed. When the status is registered, then you must associate the default wallet with the endpoint.

The endpoint's enrollment status becomes enrolled when you download and install the endpoint software to the endpoint. If you set the default wallet after you enroll the endpoint, then you must reenroll the endpoint to ensure that all future security objects created by the endpoint are automatically associated with that wallet.

In a multi-master cluster, you can only assign the default wallet on the same node where the endpoint and wallet were created when either are still in the PENDING state. After both are in the ACTIVE state, then there are no restrictions. After the default wallet is assigned and the endpoint is enrolled, the default wallet can be accessed from any node, as long as both are in the ACTIVE state and the information has been replicated to that node.

12.5.2 Setting the Default Wallet for an Endpoint

Setting a default wallet for an endpoint automatically uploads the endpoint's security objects to the wallet if another wallet is not explicitly specified.

Oracle requires that you set the default wallet right after registering the endpoint, and before downloading the endpoint software.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role or the Manage Endpoint privilege.
   If you are logging on as a user with the Manage Endpoint privilege, then you must have full wallet access (Read/Write/Manage Wallet) on the wallet that you want to set as the endpoint's default wallet.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, click the name of the endpoint that you want.
4. In the Default Wallet pane, select Choose Wallet.

   
   Description of the illustration 21_wallet_default_none.png

   The Add Default Wallet page appears displaying a list of available wallets.

   
   Description of the illustration 21_wallet_default_select.png

5. Select a wallet from the list to be the default wallet by clicking the option to the left of the wallet, and then click Select.
   The selected wallet name appears in the Default Wallet pane.

   
   Description of the illustration 21_wallet_default_selected.png

6. Click Save.

12.6 Managing Endpoint Access to a Virtual Wallet

You can grant an endpoint access to a virtual wallet, and revoke or modify access when it is no longer necessary.

• Granting an Endpoint Access to a Virtual Wallet
  An endpoint must have the Read, Modify, and Manage Wallet privileges on the wallet before security objects can be uploaded or downloaded.
• Revoking Endpoint Access to a Virtual Wallet
  You can revoke access to a virtual wallet for an endpoint by using the Endpoints tab.
• Viewing Wallet Items Accessed by Endpoints
  The term wallet items refers to the security objects to which the endpoint has access.

12.6.1 Granting an Endpoint Access to a Virtual Wallet

An endpoint must have the Read, Modify, and Manage Wallet privileges on the wallet before security objects can be uploaded or downloaded.

You can grant an endpoint access to a virtual wallet as soon as the endpoint has been added to Oracle Key Vault, when it is still in registered status.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role or the Manage Endpoint privilege on the endpoint.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
3. On the Endpoints page, select the endpoint that must have access to the virtual wallet.
   The Endpoint Details page appears. Scroll down the page to the Access to Wallets pane.

   
   Description of the illustration 217_access_to_wallets1.png

4. In the Access to Wallets pane, which lists the wallets the endpoint already has access to, click Add to add another wallet to this list.
   The Select Wallet page appears. A user with the Manage Endpoint privilege can only view the wallets to which this user has access.

   
   Description of the illustration 21_wallet_default_select.png

5. Select a wallet from the available list of wallets shown on the Add Access to Endpoint page.
6. In the Select Access Level pane, select the appropriate level of access.
7. Click Save.

12.6.2 Revoking Endpoint Access to a Virtual Wallet

You can revoke access to a virtual wallet for an endpoint by using the Endpoints tab.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role or the Manage Endpoint privilege.
   If you have the Manage Endpoint privilege on the given endpoint, then you must have the same or a higher level of access to the wallet.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
3. On the Endpoints page, select the endpoint name, which will display the Endpoint Details page.
   Locate the Access to Wallets pane on this page. The Access to Wallets pane shows a list of wallets that the endpoint has access to.
4. Select the wallet that you want to revoke access to.
5. Click Remove.
6. In the confirmation window, click OK.

12.6.3 Viewing Wallet Items Accessed by Endpoints

The term wallet items refers to the security objects to which the endpoint has access.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role or the Manage Endpoint privilege.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears listing all the Oracle Key Vault endpoints.
3. In the Endpoints page, click the name of the endpoint to access the Endpoint Details page, and then scroll down to the Access to Wallet Items pane.
   The Access to Wallet Items pane lists the wallet items that the endpoint has access to.

   
   Description of the illustration 217_access_to_wallets.png

12.7 Managing Endpoint Groups

An endpoint group is a named group of endpoints that share a common set of wallets.

• How a Multi-Master Cluster Affects Endpoint Groups
  You can create endpoint groups on any node and they will have a cluster-wide presence.
• Creating an Endpoint Group
  Endpoints that must share a common set of security objects stored in wallets can be grouped into an endpoint group.
• Modifying Endpoint Group Details
  You can add endpoints and access mappings to an endpoint group after creating the endpoint group.
• Granting an Endpoint Group Access to a Virtual Wallet
  You can grant an endpoint group access to a virtual wallet.
• Adding an Endpoint to an Endpoint Group
  You can add an endpoint to a named endpoint group.
• Removing an Endpoint from an Endpoint Group
  When you remove an endpoint from an endpoint group, this removes access to wallets that are associated with that endpoint group.
• Deleting Endpoint Groups
  You can delete endpoint groups if their member endpoints no longer require access to the same virtual wallets.

12.7.1 How a Multi-Master Cluster Affects Endpoint Groups

You can create endpoint groups on any node and they will have a cluster-wide presence.

You can add, update, or delete endpoint groups in any node, but in read-write mode only.

The Oracle Key Vault server that becomes the initial node can have endpoint groups already created. These endpoint groups are used to initialize, or seed, the cluster. During induction, the endpoint groups in the cluster are replicated to a newly added node. Endpoint groups previously created in all other nodes added to the cluster will be removed during induction.

New endpoint groups added concurrently to the multi-master cluster on different nodes may have name conflicts. Oracle Key Vault automatically resolves any endpoint group name conflicts. These conflicts are displayed in a Conflicts Resolution page and key administrators can choose to rename them.

12.7.2 Creating an Endpoint Group

Endpoints that must share a common set of security objects stored in wallets can be grouped into an endpoint group.

For example, endpoints using Oracle Real Application Clusters (Oracle RAC), Oracle GoldenGate, or Oracle Active Data Guard may need to share keys for access to shared data.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege will only be able to manage the endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.

   
   Description of the illustration 21_endpoint_groups.png

3. Click Create.
   The Create Endpoint Group page appears.

   
   Description of the illustration 21_create_endpoint_group.png

4. Enter the name of the new group and a brief description.
   Ensure that you follow the correct naming guidelines for objects.
5. If you are using a multi-master cluster, then choose whether to select the Make Unique check box.
   Make Unique helps to control naming conflicts with names across the multi-master cluster environment. Endpoint groups that were created before an Oracle Key Vault conversion to a cluster node are not affected by naming conflicts.

   • If you select Make Unique, then the endpoint group will be active immediately and users can use this endpoint group. Clicking Make Unique also displays a list of endpoints that you can add to the endpoint group.
   • If you do not select Make Unique, then the endpoint group will be created in the PENDING state. Oracle Key Vault will then begin a name resolution operation and may rename the endpoint group to a name that is unique across the cluster. If there is a naming collision, then the collision will be reported on the Conflicts page on any node in the cluster. The endpoint group will then be renamed to a unique name. You will need to go to a read-write node of the cluster and either accept the renamed endpoint group or change the endpoint name. If you change the endpoint group name, then this will restart the name resolution operation and the endpoint group will return to a PENDING state. An endpoint group in the PENDING state cannot be used to perform most operations.
6. Click Save to complete creating the endpoint group.
   The new endpoint group now appears in the Endpoint Groups page.

12.7.3 Modifying Endpoint Group Details

You can add endpoints and access mappings to an endpoint group after creating the endpoint group.

An endpoint can belong to more than one endpoint group. You cannot add one endpoint group to another endpoint group.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can only modify endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.
3. Click the edit pencil icon in the Edit column corresponding to the endpoint group.
   The Endpoint Group Details page appears.

   
   Description of the illustration 21_endpoint_group_details.png

4. Modify the endpoint name as necessary.
   See Naming Guidelines for Objects.
5. Modify the description as needed.
6. Add or remove access to wallets or endpoint group members by clicking Add or Remove.
7. Click Save.

12.7.4 Granting an Endpoint Group Access to a Virtual Wallet

You can grant an endpoint group access to a virtual wallet.

In a multi-master cluster, you cannot grant access to an endpoint group that is in the PENDING state to a virtual wallet.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can grant endpoint group access to wallets for only endpoint groups that the user created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.
3. Click the pencil icon in the Edit column corresponding to the endpoint group.
   The Endpoint Group Details page appears.
4. In the Access to Wallets pane, click Add.
5. Select a virtual wallet from the available list.
6. Select an Access Level:
   • Read Only: This level grants the endpoint group read access to the virtual wallet and its items.
   • Read and Modify: This level grants the endpoint group read and write access to the virtual wallet and its items.
7. Select the Manage Wallet check box if you want endpoints to:
   • Add or remove objects from the virtual wallet.
   • Grant other endpoints or endpoint groups access to the virtual wallet.
8. Click Save.

12.7.5 Adding an Endpoint to an Endpoint Group

You can add an endpoint to a named endpoint group.

In a multi-master cluster, you cannot add an endpoint that is in the PENDING state to an endpoint group. Also, you cannot add an endpoint to an endpoint group that is in the PENDING state.

1. Log in to the Oracle Key Vault management console as an administrator who has the Key Administrator role or Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can only add endpoints to endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoints in the left navigation bar.
   The Endpoints page appears.
3. Select the endpoint you want to add to a group.
   The Endpoint Details page appears.
4. Scroll to Endpoint Group Membership and then click Add.

   The Add Endpoint Group Membership page appears.

   
   Description of the illustration 21_add_endpoint_group_membership.png

   A list of endpoint groups is displayed under Endpoint Group Name.

5. Check the boxes to the left of the endpoint groups you want to add the endpoint to.
6. Click Save.

   The Endpoint Group Membership pane displays the checked endpoint group.

   
   Description of the illustration 21_added_endpoint_group_membership.png

12.7.6 Removing an Endpoint from an Endpoint Group

When you remove an endpoint from an endpoint group, this removes access to wallets that are associated with that endpoint group.

The removal process completes the removal unless the endpoint has been separately granted access to the wallets, directly or through another endpoint group. In a multi-master cluster, you can remove multiple endpoints at the same time. In a multi-master cluster, you cannot remove an endpoint from an endpoint group that is in the PENDING state.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can only remove endpoints from endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.
3. In Endpoint Groups, click the edit pencil icon next in the Edit column corresponding to the endpoint group.
   The Endpoint Group Details page appears.
4. In the Endpoint Group Members pane, check the boxes to the left of the endpoint names to be removed.
5. Click Remove.
6. In the confirmation window, click OK.

12.7.7 Deleting Endpoint Groups

You can delete endpoint groups if their member endpoints no longer require access to the same virtual wallets.

This action removes the shared access of member endpoints to wallets, not the endpoints themselves. You can only delete an endpoint group that is in the PENDING state if it has no members or access to wallets.

1. Log in to the Oracle Key Vault management console as a user who has the Key Administrator role or the Manage Endpoint Group privilege.
   A user who has the Manage Endpoint Group privilege can only remove endpoint groups that he or she created.
2. Select the Endpoints tab, then Endpoint Groups in the left navigation bar.
   The Endpoint Groups page appears.
3. Check the boxes to the left of the endpoint group names that you want to delete.
4. Click Delete.
5. In the confirmation window, click OK.