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:

Okta SSO Integration with Okta as the Authorization server, using OpenID Connect
Custom Authentication (Sample code includes APRIL's Project Flask based API Authentication)
Cisco DUO Multi-factor Authentication
Fully customisable UI
User logging
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:

Bare-metal/VM
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

Create a 30-Day Free Trial with DUO if you don't have an account already
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
Generate your akey by following Step 1 in this guide
Enroll users to your DUO Org
Add the ikey, skey, host (from Step 2) and akey (from Step 3) to the splashPageVariables.template file

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

Create a free developer account, if you don't have an account already
Create your Okta SSO integration by following this guide
Select the Application Type as Web and the Grant Type as Authorization Code by following this guide
Set the Login redirect URI to a webpage of your choice (doesn't matter which one)
Assign users to your Okta Org by following this guide
Find the baseUrlOKTA from here and add it to the splashPageVariables.env file
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

Download the Repo into your local working directory

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

Download and Install Node.js. If you are on macOS, you can use Homebrew
```
brew install node
```

Download and build all the required dependencies

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

Start the webserver
```
npm start
```
You can confirm that the captive portal was sucessfully deployed by checking:
- localhost:3006/signonokta (Okta SSO)
- localhost:3006/signon (Custom Auth)

Container Deployment

Download the Repo into your local working directory

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

Run docker-compose to build the containerised application

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

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.

In Meraki Dashboard, navigate to Wireless > Access Control
Choose the SSID you want to use from the drop-down list
Select Open in Network Access
Select Click-through in Splash Page
Set the Captive portal strength to Block all access until sign-on is complete
Set the Walled garden to Walled garden is enabled

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

Press Save Changes at the bottom of the screen
In Meraki Dashboard, navigate to Wireless > Configure > Splash page
In Splash page, choose the required SSID from the SSID drop-down list
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
Press Save Changes at the bottom of the screen

Authors & Maintainers

License

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