Configure Your Web Service to Use a Self-signed Certificate

When the Alexa service communicates with your web service, user requests and corresponding responses are transmitted over the Internet. To protect the confidentiality and integrity of this data, Alexa strictly enforces the use of HTTPS connections, which means that the use of SSL/TLS is required.

For testing purposes, you can use a self-signed SSL certificate to meet this requirement. In this case, you can create the certificate yourself, upload it to the developer console when you set up the skill, and configure your endpoint to present this certificate when it connects to Alexa. Note that this option can only be used for testing.

You can use the SSL Test Certificate REST API to set or get an SSL certificate for skill endpoints, whether you set the skill endpoints in the developer console or directly in the skill manifest.

See the following sections to set up a self-signed certificate for testing. These steps use OpenSSL on the Linux platform.

Create a private key and self-signed certificate for testing

  1. Run the following command to create a private key:

       openssl genrsa -out private-key.pem 2048

  2. Use a text editor to create a configuration file in the following form and save it as a .cnf file (for instance, configuration.cnf):

    [req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no

[req_distinguished_name]
C = US
ST = Provide your two letter state abbreviation
L = Provide the name of the city in which you are located
O = Provide a name for your organization
CN = Provide a name for the skill

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @subject_alternate_names

[subject_alternate_names]
DNS.1 = Provide your fully qualified domain name

  3. Replace the following content in the configuration file with your own values:

    ST: Provide your two letter state abbreviation
L: Provide the name of the city in which you are located
O: Provide a name for your organization
CN: Provide a name for the skill
DNS.1: Provide the fully qualified domain name for your endpoint

    Note that you must provide the domain name for your endpoint in the DNS.1 section, so you may want to wait to create the certificate until you have this information.

    See below for a completed sample configuration file.

  4. Use the following command to generate a certificate. Specify the names you used for your private-key.pem and configuration.cnf files:

    openssl req -new -x509 -days 365 \
            -key private-key.pem \
            -config configuration.cnf \
            -out certificate.pem

This produces a self-signed certificate in a file called certificate.pem.

Save the certificate .pem, private key .pem, and the configuration .cnf files in a safe place, then update the skill configuration with the certificate.

For example, a completed configuration file for a certificate looks similar to the following example:

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no

[req_distinguished_name]
C = US
ST = WA
L = Seattle
O = My Company Name
CN = Wise Guy

[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @subject_alternate_names

[subject_alternate_names]
DNS.1 = wiseguy.mywebserver.com

Update the Alexa skill configuration with the self-signed certificate

After creating your certificate, you need to update the configuration in the developer console. Unlike your private key, the certificate only contains public data and can be shared with Amazon for the purposes of identifying your service. This lets Alexa confirm the validity of the public key portion of the certificate.

  1. Go to https://developer.amazon.com/alexa/console/ask.

  2. Click Skills.

    The developer console opens and displays any skills you have already created.

  3. Find the skill to change in the list and click Edit.
  4. Navigate to Build > Custom > Endpoint.
  5. For the Service Endpoint Type, select HTTPS.
  6. Enter the endpoint in the region to configure, such as Default Region.
  7. Under the endpoint field, select the option I will upload a self-signed certificate.

  8. Click the Upload Certificate box and choose the .pem file for your certificate that you generated previously. The command shown above generated a certificate in a file called certificate.pem.

    You can also drag the .pem file for your certificate to the Upload Certificate box.

Configure your endpoint with the self-signed certificate

When Alexa sends a request, your service must present your certificate. The subject alternate name in your certificate must match the domain name of your endpoint.

For example, assume your service's endpoint is at https://wiseguy.mywebserver.com/wiseguy. In this case, your endpoint needs to present a valid certificate in which the subject alternate name is set to wiseguy.mywebserver.com. You specify this in the configuration file that you use to generate the certificate.

Configure your endpoint to present this certificate. The specifics for doing this depend on how you are hosting the web service. For example, if you use Amazon Web Services Elastic Beanstalk, you upload the certificate file using the AWS Command Line Interface.

Other SSL resources

See other resources about SSL and self-signed certificates. Note that these links for these tools take you to third-party sites.

Was this page helpful?

Last updated: Jul 18, 2024