Meraki Duo Integration

What is it?

An awesome webapp that can be used as a Meraki WiFi Captive Portal aka Splash Page. Capabilities include the ability to use Okta SSO or your own authentication server, enhanced with Cisco DUO MFA!

Supported Features:

1. Okta SSO Integration with Okta as the Authorization server, using OpenID Connect
2. Custom Authentication (Sample code includes APRIL's Project Flask based API Authentication)
3. Cisco DUO Multi-factor Authentication
4. Fully customisable UI
5. User logging
6. Container Support with Docker

How does it work?

The Captive Portal utilises Cisco Meraki Click-through Authentication and a built-in authentication flow with DUO MFA that authenticates the user, via Okta SSO or via Custom Authentication, before serving the Meraki URL that enables network access. If you want to see it in action, you can checkout this 30s YouTube video.

The diagram below shows the splash page authentication flow when using Okta SSO with DUO MFA.

The diagram below shows the splash page authentication flow when using a custom authentication service with DUO MFA.

Please check here to learn more about the Meraki Click-through API.

How do I deploy this?

Building this application couldn't be easier. There's two awesome options:

1. Bare-metal/VM
2. Container

Setting the environment

The splash page webapp that you are about to deploy has to be externally accessible, so if you are deploying this On-Premise or in the Cloud make sure that you have all your firewall rules setup for this. If you are deploying this locally in your machine, for testing purposes only, you can also use ngrok for exposing the webapp.

Before you deploy the application you need to set the env variables located in the /env folder. For that you will need to have both a DUO and a Okta account, if you are using Okta.

DUO Account Setup

1. Create a 30-Day Free Trial with DUO if you don't have an account already
2. Follow Step 2 & 3 in this guide to create your application within your DUO account. From here you will get your DUO integration key, secret key, and API hostname
3. Generate your akey by following Step 1 in this guide
4. Enroll users to your DUO Org
5. Add the ikey, skey, host (from Step 2) and akey (from Step 3) to the splashPageVariables.template file
6. Rename the splashPageVariables.template file as an .env file

   cd env/
   mv splashPageVariables.template splashPageVariables.env
   cd ..

Please note: In this demo the DUO Web SDKv2 is used. If you wish to use the latest DUO Web SDKv4 you will need to follow this guide to upgrade it from Web SDKv2.

Okta Account Setup

1. Create a free developer account, if you don't have an account already
2. Create your Okta SSO integration by following this guide
3. Select the Application Type as Web and the Grant Type as Authorization Code by following this guide
4. Set the Login redirect URI to a webpage of your choice (doesn't matter which one)
5. Assign users to your Okta Org by following this guide
6. Find the baseUrlOKTA from here and add it to the splashPageVariables.env file
7. Add DUO Security (MFA) integration to your Okta application by following this guide

Custom Authentication

If you are using a 3rd Party Authentication service or one that you have built, you will need to add the base URL of that auth service to the baseUrlAuth variable in the splashPageVariables.env file.

Bare-metal/VM Deployment

1. Download the Repo into your local working directory

   git clone https://github.com/JPedro2/meraki-duo-integration

2. Download and Install Node.js. If you are on macOS, you can use Homebrew

   brew install node

3. Download and build all the required dependencies

   cd meraki-duo-integration/customSplashPage/
   npm install
   npm run build

4. Start the webserver

   npm start

5. You can confirm that the captive portal was sucessfully deployed by checking:
   • localhost:3006/signonokta (Okta SSO)
   • localhost:3006/signon (Custom Auth)

Container Deployment

1. Download the Repo into your local working directory

   git clone https://github.com/JPedro2/meraki-duo-integration

2. Run docker-compose to build the containerised application

   cd meraki-duo-integration/
   docker-compose up -d --build

3. One of the microservices deployed is an NGINX container which is acting as a reverse-proxy. You can confirm that the captive portal was sucessfully deployed by checking:
   • localhost/signonokta (Okta SSO)
   • localhost/signon (Custom Auth)

Meraki Setup

Once you have the webapp running you will need to configure the SSID of your Meraki wireless network to support the splash page. You will also need to setup the Walled Garden, which determines what network access the client has before authorization. This is critical for redirecting the client to the webapp, as well as the DUO and Okta authentication services.

1. In Meraki Dashboard, navigate to Wireless > Access Control
2. Choose the SSID you want to use from the drop-down list
3. Select Open in Network Access
4. Select Click-through in Splash Page
5. Set the Captive portal strength to Block all access until sign-on is complete
6. Set the Walled garden to Walled garden is enabled
7. In the Walled garden ranges, enter the following IP address ranges and domains:

   <IP/Domain-of-the-Webapp-Deployed>
   *<your-Okta-domain>
   *.duo.com
   *.duosecurity.com
   *.duomobile.s3-us-west-1.amazonaws.com

8. Press Save Changes at the bottom of the screen
9. In Meraki Dashboard, navigate to Wireless > Configure > Splash page
10. In Splash page, choose the required SSID from the SSID drop-down list
11. Enter the full path to the Splash page webapp deployed in the Custom splash URL
    • If you deployed with the Bare Metal/VM option:
      • <webapp-ip/domain>:3006/signonokta - if you are using Okta
      • <webapp-ip/domain>:3006/signon - if you are using Custom Auth
    • If you deployed with the Container option:
      • <webapp-ip/domain>/signonokta - if you are using Okta
      • <webapp-ip/domain>/signon - if you are using Custom Auth
12. Press Save Changes at the bottom of the screen

Authors & Maintainers

• Pedro Oliveira
• Josh Dean

License

This project is licensed to you under the terms of the Cisco Sample Code License.