30 Managing Certificates with the Certificate Management Service

Use the Certificate Management Service to simplify and streamline the management of SSL/TLS certificates in a WebLogic Server domain.

WebLogic Server relies on SSL/TLS to ensure secure connections between network resources. It allows the resources to authenticate each other's identity and encrypt the data exchanged between them.

The creation, acquisition, renewal, storage, and distribution of identity and trust material can be daunting in a single domain, let alone across multiple. The Certificate Management Service reduces certificate maintenance overhead, helping you maintain reasonable certificate handling policies and improve security across domains.

This chapter includes the following sections:

• Understanding Certificate Management
• Domain Keystores
• Using Certificate Management Service with Node Manager
• Configuring the Certificate Management Service: Main Steps

Understanding Certificate Management

The Certificate Management Service provides WebLogic Server with a built-in method for managing SSL/TLS keystore entries in a WebLogic Server domain. When configured, it can significantly streamline the distribution and renewal of keystore entries to the correct servers, ensuring certificates remain valid with minimal intervention.

The Certificate Management Service makes requests to supported Certificate Issuers to obtain identity and trust material. The Certificate Management Service stores the received material in the Domain Keystores and distributes it to servers as necessary.

How the Certificate Management Service Works

The Certificate Management Service divides responsibilities between a central control plane on the Administration Server and local certificate consumers on managed servers and Node Manager.

The Administration Server is the main domain-wide authority. It enforces certificate policies, designates the authoritative keystores, and performs domain-level lifecycle operations for certificates and Certificate Authorities (CAs).

It has two self-signed root CAs, the Domain CA and the Machine CA, which are separate so that the authority to authenticate WebLogic servers is distinct from the authority to authenticate Node Manager machines.

The Domain CA signs certificates used by the Administration Server and managed servers, including identities such as domainpki-server-identity, domainpki-client-identity, and domainpki-sign-encrypt. Its CA private key and current CA certificate are held by the Administration Server under the alias domainpki-domain-ca.

The Machine CA signs the machine identity used by Node Manager, domainpki-machine-identity. Its CA private key and current CA certificate are held by the Administration Server under the alias domainpki-machine-ca.

Managed Servers and Node Manager maintain local identity and trust stores managed by the Certificate Management Service. The service obtains the certificate chain and trust material appropriate to each component; depending on the issuer, the identity private key may be generated locally or supplied as part of a provisioned or externally issued identity. Domain CA and Machine CA private signing keys are never distributed and remain under Administration Server control.

Local identity and trust material remains usable if the Administration Server is temporarily unavailable, although new issuance, renewal, and trust refresh operations cannot complete until connectivity is restored.

The Certificate Management Service can process identity and trust material from the following Certificate Issuers:

• Domain Certificate Issuer: issues certificates on behalf of the Domain and Machine CAs. The Domain Certificate Issuer is a built-in certificate issuer that is enabled with the Certificate Management Service. When Domain Keystores are enabled, servers request certificates from the Domain CA. If Node Manager is configured, it requests a certificate from the Machine CA.

• Provisioned Certificate Issuer: distributes private keys and certificates that were manually added to the domain by a WebLogic Server administrator.

• Plug-in Certificate Issuers: obtains certificates through an external certificate service which are then distributed by the Certificate Management Service. You can develop your own custom plug-in certificate issuers through the issuer plug-in SPI.

  • The OCI Certificates Plug-in Certificate Issuer is a plug-in certificate issuer that obtains certificates directly from the OCI Certificates service. It comes packaged with WebLogic Server.

These Certificate Issuers populate the Domain Keystores with the keystore entries that are managed by the Certificate Management Service. The Domain Keystores can contain identity certificates, trust certificates, certificate authority certificates, and associated private keys.

Communication between these Certificate Management Service components is facilitated by the Remote Certificate Service, a REST application also running on the Administration Server. The Remote Certificate Service also responds to certificate requests from Managed Servers and Node Manager. The Remote Certificate Service is deployed as an internal application, with the context root wls-certificate-service.

Note:

REST API calls to the Remote Certificate Service require SSL/TLS, therefore a reachable Administration Server HTTPS endpoint is required. Either enable the domain-wide Administration Port or the Administration Server SSL listen port. If a Managed Server has not yet initialized its own trust store, it can temporarily rely on the local machine-trust keystore until it initializes its own trust store.

See CertificateManagementMBean in MBean Reference for Oracle WebLogic Server.

Certificate Authorities

The Certificate Management Service maintains two separate, self-signed Certificate Authorities (CAs): the Domain CA which issues identity certificates for Administration Servers and managed servers, and the Machine CA which issues the machine identity certificate used by Node Manager.

The Administration Server owns and protects the private keys for both CAs. When a server or Node Manager needs a certificate, the appropriate CA signs it. Other components trust that certificate because they have the corresponding CA certificate in their trust keystore.

In WebLogic Server, the private keys for both CAs reside in the Administration Server’s domain-ca store. When a CA certificate approaches expiry, WebLogic Server can roll it and retain the previous public CA certificate temporarily, allowing certificates issued by both generations to remain trusted during the transition.

CertificateManagementMBean.ExpiredCertificateAuthorityRetentionDays controls how long an expired CA remains trusted in the Administration Server's domain-trust or provisioned-trust source store before automatic cleanup. The default is 7 days; the allowed range is 0–365 days, and 0 disables automatic cleanup. An administrator can choose to manually purge expired CAs without waiting for the retention period, or remove a specific CA from domain-trust or provisioned-trust. After a source deletion, server and machine trust replicas converge through their normal periodic refresh lifecycle.

The Domain and Machine CAs are generated and rolled together using the same configured CA key profile and signature algorithm. If you change these settings, it will not alter current CA material. You must roll the CAs to adopt the new settings.

These built-in CAs establish trust within the WebLogic Server environment only. External clients will not automatically trust them unless their public CA certificates are deliberately distributed to them.

By default, the CA certificates are valid for 365 days. You can adjust this interval to another value between 45 and 1825 days. The WebLogic Server certificate check schedule also performs CA maintenance. The Domain and Machine CA pair is rolled when an active signing entry is incomplete or lacks enough remaining validity to issue a certificate for the configured leaf-certificate lifetime.

Certificate Issuers

The Certificate Management Service uses Certificate Issuers to obtain and maintain the keystore entries required for secure communication between servers.

A certificate issuer is responsible for supplying an identity certificate. The Certificate Management Service determines when an identity is required, while the issuer obtains it.

The certificate issuer does not decide which SSL listener uses the resulting certificate. That decision is determined by the consumer’s configured certificate alias.

The Certificate Management Service supports the following certificate issuers:

• Domain Certificate Issuer

• Provisioned Certificate Issuer

• Plug-in Certificate Issuers

Domain Certificate Issuer

The Domain Certificate Issuer is a built-in certificate issuer that is enabled with the Certificate Management Service.

The built-in Domain Certificate Issuer issues certificates on behalf of the Domain CA and the Machine CA. It uses the Domain CA to sign server identities and the Machine CA to sign Node Manager identities. It produces the following identities: domainpki-server-identity, domainpki-client-identity, and domainpki-sign-encrypt, and domainpki-machine-identity.

If a server is configured to use Domain Keystores, it will request a certificate from the Domain CA. Node Manager requests a certificate from the Machine CA.

The Domain Certificate Issuer operates through the Administration Server, which holds the CA signing keys. The Administration Server creates missing authorities automatically and rolls the authority pair when a signing entry is incomplete or does not have enough remaining validity for the configured leaf lifetime. You can also manually create a new pair by rolling the Domain CA.

Certificates issued by the Domain Certificate Issuer are stored with a certificate chain containing the issued identity certificate followed by its issuing CA chain. Use the CertificateManagementMBean.IncludeRootCertificateInChain attribute to determine whether the self-signed root CA certificate is included in the returned and stored chain. The default is true.

Note:

Certificates issued by the Domain Certificate Issuer only establish automatic trust within the WebLogic Server environment. External clients will not automatically trust them unless their public CA certificates are deliberately distributed to them.

By default, certificates issued by the Domain Certificate Issuer are valid for 90 days. You can adjust this interval to another value between 15 and 365 days. Use CertificateManagementMBean.CertificateCheckInterval to control how often WebLogic Server checks active certificates and CertificateRefreshWindow to control how many days before expiration a renewable identity is refreshed. These settings apply to WebLogic Server instances. Node Manager uses the separate schedule described in Using Certificate Management Service with Node Manager.

Use the CertificateManagementMBean.SubjectNamePolicy attribute to specify a subject name policy that controls which DNS names and IP addresses the Domain Certificates Issuer may include in certificate subjects and Subject Alternative Names. The default value, CONFIGURED_PLUS_HOST, permits configured endpoint names plus the host name and address authenticated in the request. Accepted alternative options are CONFIGURED_ONLY, which restricts names to configured endpoints and CONFIGURED_PLUS_ANY, which permits any requested identity for compatibility.

Loopback identities are always permitted. A disallowed name causes server certificate issuance to fail, whereas disallowed machine-certificate names are discarded if a permitted endpoint identity remains.

Table 30-1 WebLogic Domain CA and Machine CA Certificate Attributes

Attribute	Value or Behavior
Certificate Version	X.509 version 3
Serial Number	Random positive values derived from sixteen random bytes.
Signature Algorithm	Use any of the supported signature algorithms described in Supported Key Profiles and Signature Algorithms. The default is SHA256withRSA. Note: The configured profile and signature algorithm must be a supported pair. Changes take effect when the CAs are generated or rolled.
Issuer DN	Same as the Subject DN. Both the Domain CA and Machine CA are self-signed roots.
Validity Period	The default validity period is 365 days but you can specify any value, in days, between 45 and 1825 days.
Subject DN	Domain CA: CN=Domain Root Certificate Authority R<generation>,OU=Domain: <domain-name>,O=WebLogic Domain PKI Machine CA: CN=Machine Root Certificate Authority R<generation>,OU=Domain: <domain-name>,O=WebLogic Domain PKI
Subject Public Key Information	Use any of the supported key profiles described in Supported Key Profiles and Signature Algorithms. The default is RSA-2048.
Basic Constraints	Critical. CA=true PathLen = 1
Key Usage	Critical: digitalSignature, keyCertSign, and cRLSign.
Subject Key Identifier	Includes a subject key identifier.

Table 30-2 WebLogic Server Identity Certificate Attributes

Attribute	Value
Certificate Version	X.509 version 3
Serial Number	Random positive values derived from sixteen random bytes.
Signature Algorithm	Uses the signature algorithm of the currently active issuing Domain CA.
Issuer DN	Subject DN of the active WebLogic Domain CA that issued the certificate.
Validity Period	The default validity period is 90 days but you can specify any value, in days, between 15 and 365 days.
Subject DN	The Domain Certificate Issuer chooses the preferred CN from the configured hostname or listen-address selection, subject to SubjectNamePolicy. For a server identity, the normal organizational units identify the server and domain, and the built-in issuer uses O=WebLogic Domain PKI. When a permitted fully qualified endpoint name is available: CN=<permitted-FQDN>,OU=Server: <server-name>,OU=Domain: <domain-name>,O=WebLogic Domain PKI. When no permitted FQDN is available and an authenticated IP address is used: CN=Server: <server-name>,OU=Domain: <domain-name>,O=WebLogic Domain PKI. The IP address is placed in the Subject Alternative Name extension and the server organizational unit is omitted. Selection is controlled by SubjectCommonName and SubjectNamePolicy.
Subject Public Key Information	Use any of the supported key profiles described in Supported Key Profiles and Signature Algorithms. The default is RSA-2048.
Basic Constraints	Critical. CA=false
Key Usage	Critical. RSA combined server identity: digitalSignature, keyEncipherment, dataEncipherment. RSA single-purpose server or client identity: digitalSignature, keyEncipherment. RSA signing and encryption identity: digitalSignature, keyEncipherment, dataEncipherment. EC identities of any purpose: digitalSignature, keyAgreement.
Extended Key Usage	Noncritical. Combined server identity: serverAuth, clientAuth, codeSigning. Single-purpose server identity: serverAuth. Single-purpose client identity: clientAuth. Signing/encryption identity: codeSigning.
Subject Alternative Names	Noncritical. The preferred permitted endpoint identity is included first as either a DNS SAN or IP SAN. Additional permitted DNS names and IP addresses are derived from SubjectAlternativeNames, server and channel configuration, targeted virtual hosts, authenticated host information, and SubjectNamePolicy.
Subject Key Identifier	Noncritical RFC 5280 type 1 subject key identifier: the complete 160-bit SHA-1 hash of the certificate’s subjectPublicKey BIT STRING.
Authority Key Identifier	Noncritical. Identifies the issuing CA using the CA’s subject key identifier together with the issuer name and CA certificate serial number.

Provisioned Certificate Issuer

The Provisioned Certificate Issuer distributes private keys and certificate chains that a WebLogic Server administrator imports into the domain. The imported identities are held in the dedicated provisioned-identity keystore on the Administration Server.

When a server configured to use Domain Keystores requests a provisioned alias, the Certificate Management Service distributes the corresponding identity to that server. Provisioned certificate aliases begin with provisioned-.

The Provisioned Certificate Issuer does not contact the external CA that originally issued the certificate, and it will not automatically renew an expiring provisioned certificate. The administrator must manually import a replacement certificate.

WebLogic Server can issue expiration warnings for a provisioned certificate when the certificate is loaded as the server's SSL identity or is present in the server's trusted-CA set. Configure the SecurityConfigurationMBean attributes, CheckIdentityCertificates, CheckTrustCertificates, CheckCertificatesIntervalDays, and CheckCertificatesExpirationDays. This checker does not scan unused identities in the Administration Server's provisioned-identity source store. You must monitor those entries separately.

The Provisioned Certificate Issuer is not enabled automatically when you enable the Certificate Management Service. Enable the Provisioned Certificate Issuer before importing or distributing provisioned identities. For import instructions, see Import Certificates into the Provisioned Trust or Identity Keystores in Oracle WebLogic Remote Console Online Help.

Table 30-3 Supported Import and Export Formats

Operation	Supported Input or Output	Validation and Semantics
Add Provisioned Identity Certificate	JKS/PKCS12 identity entry, or combined PEM	JKS/PKCS12 use source store password, source alias and key password. PEM must contain exactly one PKCS#8 key and its matching leaf plus optional chain. fromFilePassphrase decrypts the key, and source alias/key-alias password are ignored.
Add Provisioned Identity Certificate And Key	PEM chain and PEM key DER leaf and DER key PEM chain and DER key	Keys are PKCS#8, encrypted or unencrypted. DER certificate and PEM key is not a supported pairing. PKCS#1 private-key input is not supported.
Add Provisioned Trust Certificate	JKS, PKCS12, PEM, or DER	Import one trust certificate. For a PEM bundle, only the first certificate is used.
Add Provisioned Trust Certificates	PEM only	Validate the entire bundle, then import every certificate under provisioned-<base>-1, -2, and so on in file order. Empty bundles or bundles with duplicate aliases or certificates are rejected.
Remove Provisioned Identity Certificate / Remove Provisioned Trust Certificate	Alias	Delete from the selected authoritative provisioned source store. Refresh consumers separately.
Export Trusted Certificates	PEM, JKS, PKCS12	Export combined domain-trust and provisioned-trust public certificates. Excludes JDK cacerts and all private keys.
Export Domain Trust Certificates / Export Provisioned Trust Certificates	PEM, JKS, PKCS12	Export only the named source trust set. DER export is not supported.

For identity certificates imported from PEM or DER files, WebLogic Server validates the complete identity before persisting it. The import must contain exactly one certificate that matches the private key and a uniquely ordered, connected certificate chain with valid signatures. Issuing certificates must satisfy CA basic constraints, keyCertSign usage when the Key Usage extension is present, and path-length constraints. WebLogic Server rejects duplicate certificates, ambiguous chains, cycles, and disconnected certificates without persisting a partial identity. This validation is not repeated for identities imported as existing PrivateKeyEntry entries from JKS or PKCS12 keystores. Certificate validity dates are not checked during import.

Plug-in Certificate Issuers

A plug-in Certificate Issuer is a custom certificate issuer that contacts an external certificate service for certificate distribution. When configured, the plug-in uses credentials and properties from the external service to integrate with the Certificate Management Service issuer interface.

Plug-in certificate issuers can operate centrally or on the requesting server, depending on their implementation. They can also support pending requests and challenges.

You can develop a custom plug-in certificate issuer for your preferred external certificate authority using the issuer plug-in SPI.

OCI Certificates Plug-in Certificate Issuer

The Certificate Management Service includes a packaged plug-in certificate issuer for the OCI Certificates service, called the OCI Certificates Plug-in Certificate Issuer.

For general information on the OCI Certificates service, see OCI Certificates in OCI Documentation.

When configuring the OCI Certificates Plug-in Certificate Issuer, you must create credential sets that contain the encrypted properties required to authenticate with OCI. Each OCI Certificates Plug-in Certificate Issuer references one credential set. However, the same credential set may be shared by multiple issuers.

Table 30-4 Required OCI Encrypted Properties

Encrypted Property	Value
oci.region	OCI region identifier.
oci.tenancy	Tenancy OCID.
oci.user.id	User OCID.
oci.user.api.key.fingerprint	API-signing-key fingerprint.
oci.user.api.key	The API private-key text, not a path to a file.

You will also need to specify certain certificate request properties which are properties that are passed to the issuer when the Certificate Management Service requests a certificate from the OCI Certificates Plug-in Certificate Issuer.

Note:

WebLogic Server performs limited validation of certificate request properties when a certificate request is processed. For example, it validates certain alias-specific values and typed subject alternative names. However, it does not verify when the issuer configuration is saved that all properties required for the selected OCI operation are present and valid. Missing or invalid properties can therefore cause a later certificate retrieval, issuance, or renewal operation to fail.

Table 30-5 Certificate Request Properties

Certificate Request Property	Function	Retrieve Existing Certificate	Issue New Certificate
certificate.ocid	Identifies an existing OCI certificate whose current certificate chain and private key are retrieved. If this property is present, retrieval mode takes precedence and the issuance properties are not used.	Required	Do not set
certificate.authority.ocid	Identifies the OCI private certificate authority that signs the new certificate.	Not used	Required
certificate.name	Sets the OCI resource name for the newly created certificate. The name must be unique within the compartment and satisfy OCI naming requirements.	Not used	Required
certificate.description	Sets the OCI description of the certificate resource. The description does not become part of the X.509 certificate subject.	Not used	Optional
compartment	Identifies the OCI compartment in which the certificate resource and, when applicable, its OCI-managed key are created.	Not used	Required
certificate.renewal.interval.in.days	Sets the initial certificate validity period, in days, and supplies the renewal interval in the OCI certificate-renewal rule. WebLogic Server parses the value as an integer. There is no default.	Not used	Required
certificate.advance.renewal.period.in.days	Specifies how many days before the targeted OCI renewal date OCI should renew the certificate. This property configures an OCI renewal rule; it is not the WebLogic Server certificate-renewal threshold or polling interval. WebLogic Server parses the value as an integer. There is no default.	Not used	Required
use.ocs.gen.keys	Selects where the key pair is generated.	Ignored	When set to true (default), OCI generates and returns the private key. When set to false, WebLogic Server generates the key pair and submits a CSR, so the private key remains in WebLogic Server.

Domain Keystores

Domain Keystores are the managed storage and distribution system for identity and trust material used by the Certificate Management Service. Domain Keystores can contain identity certificates, trust certificates, certificate authority certificates, and associated private keys.

Managed servers and Node Manager obtain certificates from these stores using certificate aliases. Domain Keystores can contain certificates obtained from the Domain Certificate Issuer, imported by an administrator (Provisioned Certificate Issuer), or obtained through another configured issuer (plug-in certificate issuer).

Enabling the Certificate Management Service doesn't automatically configure Domain Keystores. You need to specify it as the keystore type at either the domain, server, or server template level. If you're using Node Manager, you must configure it in nodemanager.properties.

You can configure the Domain Keystores using WebLogic Remote Console or WLST. If the domain is offline, you can also use the domainKeystores.sh utility. See domainKeystores.sh in Command Reference for Oracle WebLogic Server.

These keystores are PKCS12 keystores that use the .p12 extension. Private key entries are password protected.

Each keystore has an associated properties file that contains the name, type, and purpose of the keystore, along with the passphrases needed to access the keystore and its entries. Sensitive values are encrypted. The properties file is co-located with the keystore file and shares its name except for the file extension. For example:

• DOMAIN_HOME/security/pki/domain/domain-trust.p12

• DOMAIN_HOME/security/pki/domain/domain-trust.props

Note:

Domain Keystores use domain encryption. Back up each .p12 keystore together with its matching .props file and the domain's SerializedSystemIni.dat file as one coordinated set. Backing up only the .p12 files is not sufficient for recovery.

Table 30-6 Domain Keystores

Logical Store	Location	Description
domain-ca	DOMAIN_HOME/security/pki/domain/domain-ca.p12	Stores the current signing private keys and certificates for both the Domain CA and the Machine CA. Note: This keystore is only available on the Administration Server.
domain-trust	DOMAIN_HOME/security/pki/domain/domain-trust.p12	Stores the Domain PKI trust anchors, including the current and retained Domain CA and Machine CA root certificates. Note: This keystore is only available on the Administration Server.
machine-identity	DOMAIN_HOME/security/pki/machine/machine-identity.p12	Stores the identity certificates for a machine.
machine-trust	DOMAIN_HOME/security/pki/machine/machine-trust.p12	Stores a copy of the domain's trust certificates, domain-trust and provisioned-trust. These certificates are used to bootstrap Managed Servers, and by the Node Manager.
provisioned-identity	DOMAIN_HOME/security/pki/provisioned/provisioned-identity.p12	Stores keys and certificates that an administrator can make available to other servers. The Certificate Management Service fetches certificates from the Provisioned Certificate Issuer on request and distributes them to servers. Note: This keystore is only available on the Administration Server.
provisioned-trust	DOMAIN_HOME/security/pki/provisioned/provisioned-trust.p12	Stores trust anchors that the domain should trust in addition to the domain CA. Note that this is only to provision specific CAs that may be needed for a particular environment. This file is only updated by admins, and read by the Certificate Management Service. Note Trust in the global trust anchors provided by the JRE's cacerts file is configured differently and they should not be added to this keystore. This keystore is only available on the Administration Server.
server-identity	DOMAIN_HOME/security/pki/server-servername-identity.p12	Stores the identity certificates for a server.
server-trust	DOMAIN_HOME/security/pki/server-servername-trust.p12	Stores the local server's copy of the domain-trust certificates. This trust store also includes any certificates stored in the provisioned-trust keystore.

Reserved or Well-Known Certificate Aliases

Review the reserved or well-known certificate aliases used by the Certificate Management Service.

Table 30-7 Reserved or Well-Known Aliases

Alias or Prefix	Use
<configured-plugin-name>-<name>	Plug-in-issued identity alias.
domainpki-client-identity	Domain-issued outbound client identity. Maps to server identity when single-purpose mode is off.
domainpki-domain-ca; domainpki-machine-ca	Current CA private-key entries.
domainpki-domain-ca-r<N>; domainpki-machine-ca-r<N>	Generated historical CA trust aliases.
domainpki-machine-identity	Node Manager machine identity.
domainpki-server-identity	Domain-issued server/combined identity.
domainpki-sign-encrypt	Domain-issued signing and encryption identity. Maps to server identity when single-purpose mode is off.
provisioned-<name>	Customer-provided identity and trust aliases.

Supported Key Profiles and Signature Algorithms

Review the supported RSA and EC profiles and the compatible RSA or ECDSA CA signature combinations.

Profile and algorithm spellings are case-sensitive.

WebLogic Server also validates the selected key profile and signature algorithm against the active security provider. It rejects the configuration if that provider does not support the requested key generation or signature operation.

The following key profiles are supported for both CertificateKeyProfile and CertificateAuthorityKeyProfile. CertificateKeyProfile controls generated leaf keys and is independent of the Certificate Authority key and signature algorithm. The compatible signature algorithms shown in the table apply only when the profile is used as CertificateAuthorityKeyProfile.

Table 30-8 Key Profiles and Signature Algorithms

Supported Key Profile	Key Generation	Compatible CertificateAuthoritySignatureAlgorithm values
RSA-2048, RSA-3072, RSA-4096	RSA with the indicated modulus size.	SHA256withRSA, SHA384withRSA, SHA512withRSA (each allowed with each RSA profile).
EC-256, EC-384, EC-521	EC using secp256r1, secp384r1, secp521r1, respectively.	SHA256withECDSA, SHA384withECDSA, SHA512withECDSA (each allowed with each EC profile).

Keystore File Watching and Locking

Determine how the Certificate Management Service handles multiple processes reading or modifying the same managed keystore at incompatible times.

Use keystore file watching to monitor keystore files and their associated metadata for changes made by other processes. When WebLogic Server and Node Manager detect those changes, they can reconcile their cached keystore state. This is particularly useful when multiple processes access the same machine-identity or machine-trust keystore.

Cross-process file locking coordinates access to these shared machine keystores, helping prevent simultaneous operations from producing conflicting updates or inconsistent keystore data. The configurable lock timeout determines how long a process waits to acquire a lock before the operation fails.

Keystore file watching and file locking are enabled by default with a default lock timeout of 60,000 milliseconds. You can modify them using KeystoreFileWatchingEnabled, KeystoreFileLockingEnabled, or KeystoreFileLockTimeout, respectively. For WebLogic Server, these are attributes of CertificateManagementMBean; for Node Manager, configure the corresponding properties in nodemanager.properties. Changes require restarting the affected process.

Single Purpose Certificates

In development mode and production mode without secured production mode enabled, the Domain Certificate Issuer issues a single certificate by default that handles server authentication, client authentication, and signing and encryption. In secured production mode, it issues distinct single-purpose certificates by default. You can configure this behavior for your domain.

Note:

You can designate certificates obtained from other certificate issuers as single purpose certificates but it is your responsibility to confirm that they are suited to their designated purpose.

Table 30-9 Certificate Aliases for Single-Purpose Certificates

Usage	Alias	Supported MBean Assignments
Client authentication	domainpki-client-identity	SSLMBean.DomainKeystoresClientCertAlias, NetworkAccessPointMBean.DomainKeystoresClientCertAlias, and SingleSignOnServicesMBean.TransportLayerSecurityKeyAlias.
Server authentication	domainpki-server-identity	SSLMBean.DomainKeystoresServerCertAlias and NetworkAccessPointMBean.DomainKeystoresServerCertAlias.
Signing and encryption	domainpki-sign-encrypt	SingleSignOnServicesMBean.SSOSigningKeyAlias, SingleSignOnServicesMBean.AssertionEncryptionDecryptionKeyAlias, and SAML2CredentialMapperMBean.SigningKeyAlias.

See Configure Single Purpose Certificates in Oracle WebLogic Remote Console Online Help.

Using Certificate Management Service with Node Manager

The Certificate Management Service includes a Machine CA that administers the identity and trust material used by Node Manager. The Machine CA is distinct from the Domain CA that's also included in the Certificate Management Service.

This separation allows the authority to authenticate Node Manager machines to be distinct from the authority to authenticate WebLogic servers.

When Node Manager is configured to use Domain Keystores, it must already have sufficient trust material to validate the Administration Server's SSL certificate. This bootstrap trust is provisioned into the persistent machine-trust keystore associated with Node Manager's selected host domain. Node Manager uses those trust anchors to create the SSL trust context for its HTTPS connection to the Administration Server's Certificate Management Service.

After SSL is established, Node Manager authenticates its certificate service request using a protected authorization token. It then retrieves the current effective trust anchors, comprising the domain and provisioned trust, and reconciles its local machine-trust keystore with them. If that trust changes, Node Manager reloads its certificate service client with the refreshed trust before requesting or renewing its machine identity.

If the initial bootstrap trust is unavailable or misconfigured, Node Manager can't use the Certificate Management Service.

The Machine CA signs the machine identity, domainpki-machine-identity, used by Node Manager. Its CA private key and current CA certificate are held under domainpki-machine-ca on the Administration Server. Node Manager maintains local machine-trust and machine-identity keystores.

Node Manager maintains its own certificate-check schedule. It performs its first check approximately two minutes after the Certificate Management Service initializes and then checks once every 24 hours. This schedule is independent of the CertificateManagementMBean.CertificateCheckInterval, CertificateCheckTime, and CertificateCheckTimeMaximumOffset attributes used by WebLogic Server instances. Administrators can initiate an immediate refresh using nmRefreshMachineTrust() or nmRefreshMachineIdentity(isForceUpdate).

A direct machine-trust refresh updates machine-trust and reloads the outbound certificate-service client without restarting Node Manager. During automatic scheduled reconciliation after startup, however, Node Manager requests a restart when machine trust changes or its machine identity is issued, replaced, or removed. Automatic restart requires Node Manager to be launched by a restart-capable launcher and with the weblogic.nodemanager.restartSupported system property set to true. Otherwise, restart Node Manager manually to load the updated listener identity.

You can use the Certificate Management Service with either per-domain or per-host Node Manager configurations.

For more information, see Using SSL With Java-Based Node Manager in Administering Node Manager for Oracle WebLogic Server.

Note:

The keystores configured for Node Manager do not affect or propagate to the managed servers that it controls. If you want to configure Domain Keystores on a managed server, you must configure it separately at the domain, server template, or server level.

Configuring the Certificate Management Service: Main Steps

To set up the Certificate Management Service and Domain Keystores, perform the following steps:

1. Ensure that an Administration Server HTTPS endpoint is reachable. Either enable the domain-wide Administration Port or the Administration Server SSL listen port. See Configure the Domain-Wide Administration Port in Oracle WebLogic Remote Console Online Help.

2. Enable the Certificate Management Service. See Configure the Certificate Management Service in Oracle WebLogic Remote Console Online Help. You can configure additional Certificate Management Service properties now or later as needed, including:

   • Enabling the Provisioned Certificate Issuer if you plan to import external certificates into the Domain Keystores.

   • Enabling Java Standard Trust Enabled if you want the domain trust to include Java Standard Trust.

   For a full list of properties, see CertificateManagementMBean in MBean Reference for Oracle WebLogic Server.

3. Configure properties for the Domain Certificate Issuer as needed.

4. Configure properties for Keystore Access to determine how the Certificate Management Service handles multiple processes reading or modifying the same managed keystore at incompatible times.

5. Specify Domain Keystores as the keystore type at either the domain, server, or server template level.

6. Prepare to start Managed Servers:

   • If starting Managed Servers using Node Manager, configure Node Manager properties to specify the relevant domain, Administration Server, machine, and keystore type. See Configure Node Manager with Domain Keystores Administering Node Manager for Oracle WebLogic Server.

     Note:

     Configuring Domain Keystores on Node Manager will not configure Domain Keystores on the Managed Servers that it controls. You must configure keystores for Node Manager and each managed server separately.

   • If starting a Managed Server directly, set TrustKeyStore=DomainTrust in its boot.properties file or add -Dweblogic.security.TrustKeyStore=DomainTrust to the Java command line.

Configuring the Certificate Management Service

You can configure the Certificate Management Service as needed for your environment.

Table 30-10 Configuring the Certificate Management Service

If you want to do this...	See this topic...
Enable the Certificate Management Service	Configure the Certificate Management Service in Oracle WebLogic Remote Console Online Help.
Enable Domain Keystores	Configure Keystores in Oracle WebLogic Remote Console Online Help.
Import Certificates into the Provisioned Keystores	Import Certificates into the Provisioned Trust or Identity Keystores in Oracle WebLogic Remote Console Online Help.
Configure Single Purpose Certificates	Configure Single Purpose Certificates in Oracle WebLogic Remote Console Online Help.
Configure the OCI Certificates Plug-in Certificate Issuer	Configure the OCI Certificates Plug-in Certificate Issuer in Oracle WebLogic Remote Console Online Help
Review Certificates in Domain Keystores	Review Certificates Managed by Certificate Management Service in Oracle WebLogic Remote Console Online Help.
Refresh Certificates and Trust	Refresh Certificates and Trust in Oracle WebLogic Remote Console Online Help.
Export Trusted Certificates	Export Trusted Certificates in Oracle WebLogic Remote Console Online Help.
Roll the Domain CA Certificate	Roll Domain and Machine CA Certificates in Oracle WebLogic Remote Console Online Help.