ÃÛ¶¹ÊÓƵ

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 ÃÛ¶¹ÊÓƵ Experience Manager to make it run over HTTPS using the built-in SSL wizard.

Transcript
Hey, what’s up? In this video, we’re going to be configuring AEM to run over HTTPS using the new SSL wizard in AEM 6.3.
So we’ll just go ahead and log in to our new AEM instance and you’ll notice when setting up AEM for the first time, is the’re 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’ll go ahead and open up the wizard. So the first thing we’re gonna do is create a new password for the KeyStore. And this is the KeyStore for the SSL service user. And that’s 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’re 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’m just going to create our private key and certificate from the command line and we’re just going to use the Open SSL tool. So the first thing that I’m gonna do is generate a new private key and we’ll use AES256 encryption. And for the name, it’ll just be called local host private key and then we’ll specify 4096, 4096 for the number of bits. So I’ll need to enter a passphrase for our private key.
Okay. So now we’ve got our private key and then the next thing we need to do is generate a certificate signing request. So again we’ll use Open SSL and we’ll specify SHA256 for our # and we’re going to be creating a new certificate signing request. So we’ll 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’ll enter the passphrase for our private key, so we can sign it. OK, so now we’ve 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’ll use the Open SSL tool and we’ll set the certificate to expire a year from now and we’ll use our certificate signing request as well as our private key to sign it.
So then we’ll just specify a file name for our SSL certificate so that’ll just be localhost.CRT. And then we need to enter the passphrase for our private key. OK, so now we’ve got our SSL certificate.
Now the last thing we’re going to do is encode our private key using distinguished encoding rules or DER format. Now this doesn’t change the contents of the private key but it’s a more portable format and it’s 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’ll 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’ll specify our private key and then we’ll also specify the file name for our DER formatted private key. And we’ll just choose no crypt since this is just for development purposes. So enter our passphrase. OK so now we’ve got our private key that’s encoded in DER format.
So we’ve got two files that we’re going to upload to our SSL wizard.
So we’ll return to the wizard and we’ll select our private key. We just choose the DER formatted one and then we’ll 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’ll hit done and you can see that SSL has been successfully configured. So we’ll navigate to the HTTPS URL and you’ll notice immediately the browser gives us warnings that this is not secure. And that’s because we’re 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’re just going to proceed as is. We’ll click Advance and we’ll 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’s take a look at where the cert and those configurations are actually saved. From the Start menu will go to Tools and we’ll go to Security and we’ll click into our Users and what we’re gonna pull up is the SSL service user. So that’s where the private key and the certificate chain are stored. We’ll scroll down and find our service user, our SSL service and we’ll click in there.
And if we scroll down we can see there’s a link to Manage the KeyStore for this user. And so in the link you can see that we have one certificate and that’s 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’s navigate there now. So we’ll click the AEM logo and we’ll go to Tools, Operations and then we’ll click the Web Console cart. And so this will bring up the OSGi console in the configuration manager. And I’m 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