51黑料不打烊

DocumentationAEMAEM TutorialsAEM Foundation Tutorials

Use the SSL Wizard in AEM

Last update: Tue May 14 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Beginner
  • Developer

Learn how to set up SSL in 51黑料不打烊 Experience Manager to make it run over HTTPS using the built-in SSL wizard.

Transcript
Hey, what鈥檚 up? In this video, we鈥檙e going to be configuring AEM to run over HTTPS using the new SSL wizard in AEM 6.3.
So we鈥檒l just go ahead and log in to our new AEM instance and you鈥檒l notice when setting up AEM for the first time, is the鈥檙e several administrative tasks that are created. And these are really to encourage some best practices especially when setting up a production environment. And so one of these is to configure HTTPS. And to make this easier, an SSL wizard has been created. So we鈥檒l go ahead and open up the wizard. So the first thing we鈥檙e gonna do is create a new password for the KeyStore. And this is the KeyStore for the SSL service user. And that鈥檚 where the private key and certificate chain will be stored to enable the HTTPS listener. We also need to initialize our system wide Trust Store with a new password and this is required when working with any sort of certificates.
So the next thing we鈥檙e going to do is upload a private key as well as a certificate. Now the private key is the key used to create your SSL certificate and in this case we are just going to create a self signed certificate. In a true production environment, you would want to obtain your certificate from a certificate authority.
So I鈥檓 just going to create our private key and certificate from the command line and we鈥檙e just going to use the Open SSL tool. So the first thing that I鈥檓 gonna do is generate a new private key and we鈥檒l use AES256 encryption. And for the name, it鈥檒l just be called local host private key and then we鈥檒l specify 4096, 4096 for the number of bits. So I鈥檒l need to enter a passphrase for our private key.
Okay. So now we鈥檝e got our private key and then the next thing we need to do is generate a certificate signing request. So again we鈥檒l use Open SSL and we鈥檒l specify SHA256 for our # and we鈥檙e going to be creating a new certificate signing request. So we鈥檒l specify a name for our CSR, localhost.CSR and then this is only going to be used on a local host. So for the canonical name we can just specify a local host. So then we鈥檒l enter the passphrase for our private key, so we can sign it. OK, so now we鈥檝e got our certificate signing request as well as our private key. And then next thing we need to do is create our SSL certificate. So again, we鈥檒l use the Open SSL tool and we鈥檒l set the certificate to expire a year from now and we鈥檒l use our certificate signing request as well as our private key to sign it.
So then we鈥檒l just specify a file name for our SSL certificate so that鈥檒l just be localhost.CRT. And then we need to enter the passphrase for our private key. OK, so now we鈥檝e got our SSL certificate.
Now the last thing we鈥檙e going to do is encode our private key using distinguished encoding rules or DER format. Now this doesn鈥檛 change the contents of the private key but it鈥檚 a more portable format and it鈥檚 also the format that the SSL wizard expects. So use the Open SSL command line tool to complete this conversion. So pkcs8 is a standard syntax restoring private key information, so we鈥檒l specify that here. And then for the inform our private key is currently in PEM format and for the outform we want it to be converted into DER format. And so for the in file we鈥檒l specify our private key and then we鈥檒l also specify the file name for our DER formatted private key. And we鈥檒l just choose no crypt since this is just for development purposes. So enter our passphrase. OK so now we鈥檝e got our private key that鈥檚 encoded in DER format.
So we鈥檝e got two files that we鈥檙e going to upload to our SSL wizard.
So we鈥檒l return to the wizard and we鈥檒l select our private key. We just choose the DER formatted one and then we鈥檒l also select our SSL certificate.
OK, so the next step of the wizard is where we can specify the port for HTTPS to run under. We鈥檒l hit done and you can see that SSL has been successfully configured. So we鈥檒l navigate to the HTTPS URL and you鈥檒l notice immediately the browser gives us warnings that this is not secure. And that鈥檚 because we鈥檙e using a self signed cert. So in a true production environment, again you want to work with your IT teams to obtain a valid cert. So for this demo, we鈥檙e just going to proceed as is. We鈥檒l click Advance and we鈥檒l just proceed to our local post. And so now you can see that AEM is running over HTTPS. The SSL wizard is very convenient. But let鈥檚 take a look at where the cert and those configurations are actually saved. From the Start menu will go to Tools and we鈥檒l go to Security and we鈥檒l click into our Users and what we鈥檙e gonna pull up is the SSL service user. So that鈥檚 where the private key and the certificate chain are stored. We鈥檒l scroll down and find our service user, our SSL service and we鈥檒l click in there.
And if we scroll down we can see there鈥檚 a link to Manage the KeyStore for this user. And so in the link you can see that we have one certificate and that鈥檚 the local host cert that we created. And you can see that it expires a year from now.
And so if you wanted to update or add a new certificate for the SSL services user, you could do that from this UI. The other area that the SSL wizard updates is in OSGi configuration. So let鈥檚 navigate there now. So we鈥檒l click the AEM logo and we鈥檒l go to Tools, Operations and then we鈥檒l click the Web Console cart. And so this will bring up the OSGi console in the configuration manager. And I鈥檓 just going to search for granite SSL. Uou can see we have this granite SSL connector factory. So this is the config that gets updated as part of the wizard. So you can see the port as well as the KeyStore user and KeyStore password. So if you need to make any updates, if you want to change the port, you would update this config.
So that concludes the setup of the SSL wizard for development environment in AEM 6.3. The SSL wizard can also be used to accelerate the setup of a production environment but you definitely want to involve your IT security team. Thanks.
NOTE
For managed environments, it is best for the IT department to provide CA-trusted certificates and keys.
Self-signed certificates are only to be used for development purposes.

Using SSL Configuration Wizard

Navigate to AEM Author > Tools > Security > SSL Configuration, and open the SSL Configuration Wizard.

SSL Configuration Wizard

Create store credentials

To create a Key Store associated with the ssl-service system user and a global Trust Store, use the Store Credentials wizard step.

  1. Enter the password and confirm password for the Key Store associated with the ssl-service system user.

  2. Enter the password and confirm password for the global Trust Store. Note it is a system-wide Trust Store and if it is already created, the entered password is ignored.

    SSL Setup - Store Credentials

Upload private key and certificate

To upload the private key and SSL certificate, use the Key & Certificate wizard step.

Typically, your IT department provides the CA-trusted certificate and key, however self-signed certificate can be used for development and testing purposes.

To create or download the self-signed certificate, see the Self-Signed private key and certificate.

  1. Upload the Private Key in the DER (Distinguished Encoding Rules) format. Unlike PEM, DER-encoded files do not contain plain text statements such as -----BEGIN CERTIFICATE-----

  2. Upload the associated SSL Certificate in the .crt format.

    SSL Setup - Private Key and Certificate

Update SSL connector details

To update the hostname and port use the SSL Connector wizard step.

  1. Update or verify the HTTPS Hostname value, it should match the Common Name (CN) from the certificate.

  2. Update or verify the HTTPS Port value.

    SSL Setup - SSL Connector details

Verify the SSL setup

  1. To verify the SSL, click the Go to HTTPS URL button.

  2. If using self-signed certificate, you see Your connection is not private error.

    SSL Setup - Verify AEM over HTTPS

Self-Signed private key and certificate

The following zip contains DER and CRT files required for setting up AEM SSL locally and intended for local development purposes only.

The DER and CERT files are provided for convenience and generated using the steps outlined in the Generate Private Key and Self-Signed Certificate section below.

If needed, the certificate pass phrase is admin.

This localhost - private key and self-signed certificate.zip (expires July 2028)

Download the Certificate file

Private key and self-signed certificate generation

The above video depicts the setup and configuration of SSL on an AEM author instance using self-signed certificates. The below commands using can generate a private key and certificate to be used in Step 2 of the wizard.

### Create Private Key
$ openssl genrsa -aes256 -out localhostprivate.key 4096

### Generate Certificate Signing Request using private key
$ openssl req -sha256 -new -key localhostprivate.key -out localhost.csr -subj '/CN=localhost'

### Generate the SSL certificate and sign with the private key, will expire one year from now
$ openssl x509 -req -extfile <(printf "subjectAltName=DNS:localhost") -days 365 -in localhost.csr -signkey localhostprivate.key -out localhost.crt

### Convert Private Key to DER format - SSL wizard requires key to be in DER format
$ openssl pkcs8 -topk8 -inform PEM -outform DER -in localhostprivate.key -out localhostprivate.der -nocrypt
recommendation-more-help
c92bdb17-1e49-4e76-bcdd-89e4f85f45e6