z/OSMF certificates - in relation to Zowe, Unified Management Server, and Db2 Administration Foundation

Resolving Common z/OSMF Certificate Issues

Over the course of working with many customers, I've frequently encountered issues with z/OSMF certificates. One recurring problem is that the certificates often lack Subject Alternative Names (SANs)—a critical element for modern TLS setups. This issue arises because the z/OSMF installation instructions typically don’t configure SANs. If Zowe is the first major application leveraging z/OSMF in your environment, you're likely to face this challenge.

To diagnose and address this problem, follow the steps below:

Check Your z/OSMF Keyring

Run the following RACF command to view the z/OSMF keyring:

RACDCERT ID(IZUSVR) LISTRING(IZUKeyring.IZUDFLT)   

Verify the TLS Certificate

To inspect the TLS certificate on your system, issue this RACF command (note that the certificate label may vary slightly on your system):

racdcert id(IZUSVR) list(label('DefaultzOSMFCert.IZUDFLT'))

Look for Subject Alternative Names

Within the certificate details, locate the section titled "Subject's AltNames".

• If this section is missing: The certificate is invalid and will not work with services like Unified Management Server (UMS).
• If this section exists: Verify that the hostnames and IP addresses listed are accurate for your LPAR and/or sysplex.

Resolve Invalid Certificates

If your z/OSMF certificate is invalid:

1. Contact Your Certificate Issuer:
   Reach out to your certificate authority or your PKI team to request a properly signed certificate. Ensure the new certificate includes valid hostnames and, if necessary, IP addresses for your environment.

2. Generate a Temporary Certificate (Optional):
   For testing or temporary use, you can generate a site certificate. Below, I'll guide you through creating a site certificate suitable for use with z/OSMF, Zowe, UMS, and even other services like Db2 SQL Tuning Service or Db2 Analytics Accelerator Administration Services.

Temporary Solution: Creating a Site Certificate

When generating a temporary certificate, I recommend creating a site certificate, which isn't owned by a specific user. This allows broader applicability across services.

1: Create new Root CA for your sandbox

RACDCERT GENCERT CERTAUTH +                       
         SUBJECTSDN( +                            
           CN('SANDBOX ROOT CA') +                
         ) +                                      
         SIZE(2048) +                             
         NOTAFTER(DATE(2030-05-01)) +             
         WITHLABEL('SANDBOX ROOT CA') +           
         KEYUSAGE(CERTSIGN)                       

2: Create new site certificate for your sandbox (please replace O, L, SP, C, IP and DOMAIN with suitable values for your sandbox)

RACDCERT GENCERT SITE +                                           
         SUBJECTSDN( +                                            
           CN('Sandbox Server and client certificate') +          
           OU('Sandbox') +                                        
           O('ACME Inc.') +                                       
           L('Waltham') +                                         
           SP('MA') +                                             
           C('US')) +                                             
         SIZE(2048) +                                             
         WITHLABEL('SITE SANDBOX') +                              
         KEYUSAGE(HANDSHAKE) +                                    
         ALTNAME(IP(1.2.3.4) +                               
                 DOMAIN('lpar.acmeinc.com')) +     
         SIGNWITH(CERTAUTH LABEL('SANDBOX ROOT CA'))              

3: connect these certificates to your z/OSMF keyring

RACDCERT CONNECT(CERTAUTH LABEL('SANDBOX ROOT CA') +       
   RING(IZUKeyring.IZUDFLT) USAGE(CERTAUTH)) ID(IZUSVR)    

RACDCERT CONNECT(SITE LABEL('SITE SANDBOX') +                     
   RING(IZUKeyring.IZUDFLT) USAGE(PERSONAL) DEFAULT) ID(IZUSVR)   

4: Delete the existing certificates from your z/OSMF keyring

RACDCERT REMOVE(CERTAUTH   LABEL('zOSMFCA') +                     
   RING(IZUKeyring.IZUDFLT)) ID(IZUSVR)                           
                                                                  
RACDCERT REMOVE(ID(IZUSVR) LABEL('DefaultzOSMFCert.IZUDFLT') +   
   RING(IZUKeyring.IZUDFLT)) ID(IZUSVR)                           

5: Confirm the certificates have been replaced in the keyring

RACDCERT ID(IZUSVR) LISTRING(IZUKeyring.IZUDFLT)   

6: Finally, restart your z/OSMF server:

/P IZUSVR1

[wait until stopped]

/S IZUSVR1

Now access your z/OSMF server at https://<lpar hostname>:<zosmfport>/zosmf . You will still get a warning in your browser about security issues with the site. In Firefox you'll see:

Firefox does not trust <lpar hostname>:<zosmfport> because its certificate issuer is unknown, the certificate is self-signed, or the server is not sending the correct intermediate certificates.

Since you created the issuer you can accept the risk - and you could even download the Root CA and import into your browser and/or your operating system's trust store. 

By following these steps, you can address the immediate issue and ensure your system is set up for successful integrations with z/OSMF and related services.

#IBMChampion#Db2forz/OS#Db2Tools