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
- Update the Alexa skill configuration with the self-signed certificate
- Configure your endpoint with the self-signed certificate
- Other SSL resources
- Related topics
Create a private key and self-signed certificate for testing
-
Run the following command to create a private key:
openssl genrsa -out private-key.pem 2048
Important: Anyone in possession of your private key could masquerade as your service, so store your key in a secure location. -
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
-
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.
-
Use the following command to generate a certificate. Specify the names you used for your
private-key.pem
andconfiguration.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.
- Go to https://developer.amazon.com/alexa/console/ask.
-
Click Skills.
The developer console opens and displays any skills you have already created.
- Find the skill to change in the list and click Edit.
- Navigate to Build > Custom > Endpoint.
- For the Service Endpoint Type, select HTTPS.
- Enter the endpoint in the region to configure, such as Default Region.
- Under the endpoint field, select the option I will upload a self-signed certificate.
-
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 calledcertificate.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.
- Open SSL
- How to Create A Self Signed Certificate
- How to Create a Self Signed Certificate using Java Keytool
- Java Keytool Reference
Related topics
- Build Skills in the Alexa Developer Console
- Host a Custom Skill as a Web Service
- Deploy a Web Service for a Custom Skill to AWS Elastic Beanstalk
Last updated: Jul 18, 2024