Social Identity Management Service

SIMS is a very basic project aims to add social login as a method of authentication and authorization to wireless networks managed by Cisco ISE. It's built on top of Node.js/Express and use Passport.js to easily add more than 500 social login strategies

How It Works

Prerequisites

For a quick start you'll don't need to have any network setup or equiqments, we will use the default configuration and test portals. so the must have list include only:

1. Cisco ISE v2.3+
   • In case you don't have Cisco ISE you can use one from DevNet sandbox or in case you have access, from Cisco dCloud where you'll even get a nice network setup to start with
2. Desktop/VM/Server with Node.js v8.9.3+/Docker installed
   • Machine must have network access to Cisco ISE primary node
   • SIMS is cross platform app but the instructions below written in Unix (or OS x) flavor

Installation

# Clone this repository
$ git clone https://github.com/CiscoDevNet/ise-social-login-guest-authentication.git

# Go into the repository
$ cd sims

# Install dependencies (skip it in case you plan run on docker)
$ npm i

Config

SIMS is using environment variables for configuration. the easiest way to manage and persist them is using the .env file sits on the root project directory

Configuration in the file is splitted to three parts, listed below

Project Settings

NODE_TLS_REJECT_UNAUTHORIZED=0 // Get access to Cisco ISE with no SSL cert installed
CALLBACK_HOSTNAME= // Hostname that we will run our server, used for callback redirection
PORT= // Port we will run our server

Cisco ISE Details

ISE_ADDRESS=// IP Address of our Cisco ISE PAN node
ISE_SPONSOR_USER_NAME=// Sponsor user that will create our guest users
ISE_SPONSOR_PASSWORD=// Password for the sponsor user
SPONSOR_PORTAL_ID= // Sponsor portal that guest will be part of
GUEST_USER_LOCATION=// The location where the guest user created

Social Strategies Config

SIMS is use by default four social login strategies. For strategies modifications refer to Add/Remove Login Strategies section below. Pay attention that missing config property will fail the application

LINKEDIN_CLIENT_ID=
LINKEDIN_SECRET=
GITHUB_CLIENT_ID=
GITHUB_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
TWITTER_CONSUMER_KEY=
TWITTER_CONSUMER_SECRET=

.env file is listed as .gitignore file to avoid commiting of sensitive data to source control

Usage

Run the project

Node.js

From the project directory, Run:

• npm start for a quick up'n'running
• npm run dev to use nodemon and modify the code in realtime

Docker

This project has both Dockerfile and docker-compose.yml files to allow plain docker and docker-swarm running env

From the project directory, Run:

• docker run --rm -it -p 3001:3001 $(docker build -q --no-cache .) to build docker image and run it on port 3001

Use on ISE

ISE ERS Setup

Enable ERS for read/write on ISE on the Admin Portal

• Go to: Administration > System > Settings > ERS Settings
• Select: Enable ERS forRead/Write
• Click: Save

Create ERS sponsor user for ISE

• Go to: Administration > Identities > Users
• Click: Add
• Insert: Name (Usually sponsor-api)
• Insert: Password (Choosen password)
• Select: ALL_ACCOUNTS (default) at User Groups dropdown
• Click: Submit

Enable ERS access for sponsor group

• Go to: Work Centers > Guest Access > Portals & Components > Sponsor Groups > ALL_ACCOUNTS (default)
• Check: Access Cisco ISE guest accounts using the programmatic interface (Guest REST API)
• Click: Save

Get project config variables

Get the portal ID

• Go to: Work Centers > Guest Access > Portals & Components > Sponsor Portals > Sponsor Portal (default)
• Click: Portal test URL
• Copy: portal value from the address bar (should look like 5d6c7720-f612-43df-ad36-ecfb166de8be)
• Paste: portal value on .env file

Create guest location (no need in case your code running on PST)

• Go to: Work Centers > Guest Access > Settings > Guest Locations and SSIDs
• Insert: Location name:* (Free text)
• Choose: Time zone:*
• Click: Add
• Click: Save
• Paste: location name value on .env file

Add the button to ISE

The sample below will add all the four default login methods to the portal, refer to Add/Remove Login Strategies section for more info

• Go to: Work Centers > Guest Access > Portals & Components > Guest Portals > Self-Registered Guest Portal (default)
• Click: Portal Page Customization
• Scroll: Instructional Text section
• Click: Toggle HTML Source (a button with icon looks like <> appear on the bottom row of the editor sidebar)
• Paste:

  <button onclick="window.location.href='http://localhost:3001/auth/google'+window.location.search+'&iseAddress='+window.location.host+'&token='+document.getElementsByName('token')[0].value">Login with Google</button>
  <button onclick="window.location.href='http://localhost:3001/auth/twitter'+window.location.search+'&iseAddress='+window.location.host+'&token='+document.getElementsByName('token')[0].value">Login with Twitter</button>
  <button onclick="window.location.href='http://localhost:3001/auth/linkedin'+window.location.search+'&iseAddress='+window.location.host+'&token='+document.getElementsByName('token')[0].value">Login with LinkedIn</button>
  <button onclick="window.location.href='http://localhost:3001/auth/github'+window.location.search+'&iseAddress='+window.location.host+'&token='+document.getElementsByName('token')[0].value">Login with Github</button>

Test the flow

• Go to: Work Centers > Guest Access > Portal & Components > Guest Portals > Self-Registered Guest Portal (default)
• Click: Portal Test URL
• Click: Login with GitHub (or any other method you have)
• Login: with your social credetials
• Authorize: usage of your ISE social app
• Wait: for user creation
• Click: Accept
• Navigate: back to ISE admin portal
• Go to: Work Centers > Guest Access > Manage Accounts
• Click: Manage Accounts
• Click: Managed Accounts tab
• List: your social identities as guest user

Add custom fields

One of the advantages of using social network as login method is the extra attributes we can get on our guest users. We can use this attributes to make policy desicion. (e.g. take the account age as proof for account validation, guest age for legal purpose etc.), marketing insights (e.g. push user profile to our CRM), user targeting/profiling and more
To manage the extra field that will populate we will use the userSerializer.js file where we manage the serialization of guest users from various social identities

Add/Remove Login Strategies

The current version of SIMS implemented four social login methods, there is no reason why we choose to implement only those, you can use it or not
To add or remove the

Troubleshooting

Location isn't fit
Custom field does not created
Passwords not match