Securely pairing Amazon Alexa with Home Assistant

I recently figured out how to pair Amazon Alexa with Home Assistant in your home network without port forwarding or exposing your public IP address and thought I’d share how I did it.

To facilitate access to the Home Assistant instance, I am using a free Cloudflare Tunnel. This will still expose it to the internet, effectively acting as a reverse proxy, but in a more secure way than with port forwarding. The Home Assistant Alexa Skill Adapter (haaska) then bridges the two Smart Home APIs from Home Assistant and Amazon Alexa.

Prerequisites

• Home Assistant running in your home network
• CloudFlare account (free) with a domain pointing to its name servers
• Amazon Developer account (free)
• Amazon AWS account (AWS lambda is free for up to 1 million requests and 1GB of outbound data per month)

Set up a CloudFlare tunnel

1. Log in to the CloudFlare Zero Trust dashboard and go to Access > Tunnels.
2. Select Create a tunnel.
3. Enter a name for your tunnel (for example homeassistant-tunnel).
4. Select Save tunnel.
5. Take note of the tunnel token. It is the string of alphanumeric characters at the end of the run command.
6. Install and run cloudflared using the token. If you are using docker compose, you can add the following service to your configuration:

  cloudflared:
    container_name: cloudflared
    image: cloudflare/cloudflared
    restart: unless-stopped
    command: tunnel run
    environment:
      - TUNNEL_TOKEN=******

7. Select Next.
8. Choose a public hostname (for example tunnel.example.xyz). You can use any hostname as long as it is a domain linked to your CloudFlare account. I recommend using a subdomain of a single-purpose domain that does not have an A record to decrease the likelihood of it being discovered.
9. Test the tunnel by visiting the chosen domain. You should see the login screen of your Home Assistant instance.

Prepare Home Assistant

1. Add the following to your configuration.yaml file:

api:

alexa:
  smart_home:

2. Restart and log in to Home Assistant.
3. Click on your username in the bottom left corner.
4. Scroll down to Long-Lived Access Tokens and click CREATE TOKEN.
5. Enter a name for the token (for example haaska) and select OK.
6. Take note of the token.

Set up Amazon OAuth2

1. Log in to Amazon Developer Console.
2. Click on Login with Amazon in the top navigation bar.
3. Select Create a New Security Profile.
4. Enter a name for the security profile (for example haaska).
5. Enter a short description (for example haaska for Alexa and Home Assistant).
6. Enter any URL in the privacy notice field (for example example.xyz).
7. Select Save.
8. Hover over the gear icon next to your new security profile and choose Web Settings.
9. Take note of the Client ID and Client Secret. Keep this browser tab open for later.

Set up Alexa Skills Kit

1. Open Amazon Developer Console in a new tab.
2. Hover over Alexa in the top navigation bar and select Alexa Skills Kit.
3. Select Create Skill.
4. Name your skill (for example haaska).
5. Choose the language you would like to use (for example German (DE))
6. Select the Smart Home tile.
7. Click on Create Skill at the top right.
8. Take note of the Skill ID. Keep this browser tab open for later.

Set up AWS Lambda

1. Log in to AWS Console in a new tab.
2. Click on Services in the top left and go to Security, Identity & Compliance > IAM.
3. Select Roles in the menu to the left.
4. Click on Create Role.
5. Make sure AWS service is selected, then select Lambda from the use case list.
6. Click Next.
7. Search for basic in the search field and select the checkbox next to AWSLambdaBasicExecutionRole when it appears.
8. Click Next.
9. Name the role lambda_basic_execution.
10. Select Create role at the bottom right.
11. Return to AWS Console.
12. Click on the region dropdown next to your username at the top right in the menu bar.
13. Select the appropriate region for your skill language and endpoint region (for example EU (Ireland) for German in Germany).

14. Click on Services in the top left and go to Compute > Lambda.
15. Click on Create Function in the top right.
16. Select Author from scratch.
17. Set a function name (for example haaska).
18. Select Python 3.9 as the runtime.
19. Click on Change default execution role to expand the menu and select Use an existing role.
20. Select lambda_basic_execution from the dropdown menu and klick on Create Function.
21. Click on Add trigger.
22. Select Alexa from the drop down menu and then select Alexa Smart Home.
23. Copy and paste the Skill ID from the tab where Alexa Developer Console is open and paste it in Skill ID.
24. Click on the Code tab below the function overview.
25. Download the most recent version of haaska from GitHub.
26. Select Upload from in the top right and click on .zip file, then upload the haaska zip file.
27. Scroll down to the section Runtime settings and click on Edit.
28. Replace the current Handler with haaska.event_handler and click on Save.
29. Keep this browser tab open for later.

Configure haaska

1. Click on the file config.json in the file panel in the section Code source.
2. Add your tunnel domain appended by /api the section after url (for example https://tunnel.example.xyz/api)
3. Enter the noted down Long Life Access token from Home Assistant next to bearer_token.
4. Click on Deploy.
5. Scroll up to the section Function overview and take note of the Function ARN.

Link Alexa Skills Kit with AWS Lambda

1. Return to the tab where Alexa Developer Console is open.
2. Paste the Function ARN in the field Default endpoint.
3. Select the Endpoint Region that matches the Skill language from earlier (for example Europe, India)
4. Paste the ARN in the region box.
5. Click Save at the top right.

Link Alexa Skills Kit with Amazon OAuth2

1. Scroll down to the bottom section and click on Setup Account Linking.
2. Under Authorization URI enter https://www.amazon.com/ap/oa.
3. Under Access Token URI enter https://api.amazon.com/auth/o2/token.
4. Enter your Client ID and Client Secret from the Amazon OAuth2 tab.
5. Click on Add scope and enter profile.
6. Scroll down and take note of the Alexa Redirect URLs at the bottom of the page.
7. Click Save in the top right corner of the page.
8. Return to the tab where Amazon Developer Console (Securiy Profile) is open and click Edit at the bottom right.
9. Click on Add Another in the Allowed Return URLs section until you have three fields.
10. Enter the Redirect URIs from the tab where Alexa Developer Console is open and click Save.

Done!

Open the Alexa app on your phone and enable your Skill under the Developer tab. Then try out your newly connected Alexa by asking it to turn on lights or scenes from Home Assistant.