• Trainer Sagar Dhawan
• Posted on September 5, 2025
• No Comments

[Day 131] Cisco ISE Mastery Training: Custom Guest Portal Branding (HTML/CSS)

Introduction

Custom guest portals are the front door your users first see. A well-branded, responsive portal increases trust, reduces helpdesk calls, and improves adoptions of guest / BYOD flows. In ISE, portal customization is powerful: you can change layout, colors, logos, text, and insert small JavaScript snippets — or build a fully custom portal with the ISE Portal Builder and upload it as a package.

This Article teaches you how to safely brand ISE guest portals: when to use simple editors vs Portal Builder, how to upload and apply custom CSS themes and images, how to use ISE substitution variables to show guest credentials or expiry times, and how to validate and debug the portal end-to-end (preview → test URL → browser console → captive portal flow). By the end you’ll be able to deliver production-grade guest experiences and teach students how to avoid common mistakes.

---

Problem Statement

Common real-world issues that require portal customization:

• Default portals are functional but don’t reflect corporate branding — users distrust unknown splash pages.
• Organizations need localized portals (logos/language) per site.
• Security teams want to control which JS runs on the portal (avoid XSS) while marketing wants features like embedded videos or tracking.
• Portal flows must work for wired, wireless, and captive-portal controllers — differences in redirect/timeout behavior increase debugging complexity.

We’ll solve these by using ISE’s built-in customization plus the Portal Builder for full control, and by applying a reproducible validation & rollback process so you can safely deploy changes to production.

---

Solution Overview (how ISE supports it)

Cisco ISE provides multiple customization tools:

• Portal Page Customization editor (GUI): edit page text (Instructional Text, Optional Content 1/2) and insert HTML/CSS/JavaScript snippets for each portal page. You must enable portal customization in System settings first. (Cisco, Cisco Community)
• Export/Import theme CSS: export existing theme CSS (theme.css), edit locally, and reimport as a custom theme. This controls global styles. (Cisco)
• ISE Portal Builder (isepb.cisco.com): visual designer that exports a portal package (zip/tar) and helps upload to ISE using the ISEPB Upload & Config Tool (recommended for large or multi-page changes). The Portal Builder also manages images centrally. (studylib.net, CRAZY NETWORKING)
• Variables / placeholders: ISE exposes substitution variables (username, expiry, timers, SSID, etc.) you can use in pages and notifications. See the admin guide variable lists. (Cisco)

Important constraints & gotchas

• ISE editor allows HTML/JavaScript but code must be valid — invalid syntax can break flows; some ISE versions have quirks (e.g., 3.2 had an issue with single-line JS comments). Test in lab first. (Cisco)
• Portal Builder generated code can overwrite manual edits — pick one approach per portal to avoid conflicts. (studylib.net)

---

Sample Lab Topology

Platform: VMware or EVE-NG. Use snapshots.

Components

• Cisco ISE (PAN + PSN) — manage/host portals.
• Wireless controller / Switch — will redirect guests to the ISE portal (e.g., Cisco WLC, Aruba, Meraki). (Any vendor that supports URL redirect to external portal will work.)
• Client devices: Windows 10 laptop (desktop browser) + iPhone (mobile browser)
• Lab host: Kali/Ubuntu VM for curl/tcpdump/wireshark.

IP plan (example)

• ISE (PSN): 10.10.10.11
• WLC/controller: 10.10.20.10
• Lab host: 10.10.99.50
• Guest VLAN: 172.16.110.0/24

Topology diagram :

---

Step-by-Step GUI Configuration Guide

Pre-req checklist (do this first):
• Ensure ISE PSN reachable and a valid portal certificate is installed (ISE > Administration > System > Certificates).
• Admin account with Portal Customization privileges.
• Enable portal customization globally.
• Backup current portal/theme before editing.

---

Step A — Enable Portal Customization (global switch)

1. Log into ISE (PAN) as an admin.
2. Go to Administration > System > Admin Access > Settings > Portal Customization.
3. Check Enable portal customization with HTML. If you will use client-side scripting, also check Enable portal customization with HTML and JavaScript. Save.
   • [Screenshot: Administration > System > Admin Access > Settings > Portal Customization].

Validation: You should be able to enter HTML/JS in portal page text boxes in the next steps.

---

Step B — Edit a Guest Portal (quick inline edits)

1. Go to Work Centers > Guest Access > Portals & Components > Guest Portals.
2. Click the portal you want to customize (e.g., Self-Registered Guest Portal).
3. Choose Portal Page Customization → Pages. You’ll see pages like Welcome, Login, Registration, Success, Print Receipt.
   • For each page you can edit:
     • Instructional Text (main HTML area)
     • Optional Content 1 / 2 (additional HTML regions)
     • Banner / Logo / Desktop / Mobile images (upload image)
   • [Screenshot: Guest Portals > Portal Page Customization > Pages].

1. Use the mini-editor to paste your HTML snippets (example below). Click Preview → Desktop Preview or Mobile Preview to see changes.

Example: Minimal branded Welcome HTML

<div class="pb-welcome">
  <img src="/portal/images/mylogo.png" alt="MyCorp Logo" style="max-height:70px;">
  <h1>Welcome to MyCorp Guest Wi-Fi</h1>
  <p>Please accept the policy and enter your details to get access.</p>
</div>

Note: use images uploaded to the portal/theme (see image upload below).

Validation: Preview shows new text/logo. If not, open browser console; look for 404s for missing images.

---

Step C — Export / edit / import CSS theme (global styling)

1. In the portal Portal Page Customization area, find Tweaks → Export / Import Themes (or Theme Editor / Export depending on ISE version). Export the .css file (usually theme.css or structure.css). (Cisco)
   • [Screenshot: Export Theme]
2. Edit theme.css locally with your CSS. Example snippet (make buttons match corp brand):

/* theme.css — snippet */
button.primary {
  background-color: #0a6ebd; /* corporate blue */
  color: #ffffff;
  border-radius: 6px;
  padding: 12px 18px;
  font-weight: 600;
}
.pb-welcome h1 { font-family: 'Open Sans', Arial, sans-serif; color: #0a6ebd; }

3. Re-import the modified theme via Import Theme and Apply to the portal. If you keep multiple portals, apply to the target portal only.

Validation: Use Preview and check Network tab in DevTools to confirm CSS loads. If old CSS persists, clear browser cache or test in private/incognito window.

---

Step D — Using the Portal Builder for full-page custom portals (recommended for complex designs)

1. Go to https://isepb.cisco.com (ISE Portal Builder). Sign in with Cisco ID. Build your portal visually using templates, upload images via the Image Manager, and export the portal package. (studylib.net, CRAZY NETWORKING)
   • [Screenshot: ISE Portal Builder — Template Gallery]
2. Export the portal and download the ISEPB Portal Upload & Config Tool (Windows/Mac) from the Portal Builder page. Use this Upload tool (it communicates with ISE) to import the portal package to ISE — it will create theme, images, html pages and JS correctly. Do not edit the portal in the ISE GUI after importing via Portal Builder (Portal Builder contents will be overwritten if you re-export). (studylib.net)

Validation: After import, open Guest Portals in ISE and use Preview to check all pages. Portal Builder also uploads image assets so pathing is correct.

---

Step E — Upload images and logos (GUI)

1. In Portal Page Customization → Global Page Customization you can upload Desktop Logo, Mobile Logo, Background etc. (or use Portal Builder Image Manager). (Cisco Community)
   • [Screenshot: Portal Page Customization > Global Page Customization > Upload Images]
2. Use only HTTPS image URLs or images uploaded to portal assets; mixed content (HTTP on HTTPS portal) is blocked by browsers.

Validation: In browser devtools → Network tab, verify 200 OK for /portal/images/mylogo.png.

---

Step F — Add dynamic fields using ISE variables

1. When editing pages, you can use ISE substitution variables (listed in the admin guide) to show guest username, expiry, time left, SSID, etc. Examples include ui_user_name, ui_start_date_time, ui_time_left and many more — check the variables table in the ISE Administrator Guide. (Cisco)

Example: Success page with dynamic username

<p>Your guest account: <strong>${ui_user_name}</strong></p>
<p>Expires: <strong>${ui_time_left}</strong></p>

Use the exact variable names from the admin guide for your ISE version.

Validation: Complete a self-register flow — the Success page should render the substituted values. If variables render literally, check that you used the correct variable name for your ISE version.

---

Step G — Small JavaScript enhancements (use sparingly)

Example: mobile-only tweak

<script>
  // avoid heavy libraries; keep JS short and tested
  document.addEventListener('DOMContentLoaded', function() {
    if(window.innerWidth < 480) {
      document.querySelector('.pb-welcome h1').textContent = 'Welcome! (mobile)';
    }
  });
</script>

Caveats

• Keep JS minimal for performance and XSS safety.
• Some ISE versions had known JS parsing quirks (avoid single-line comments // on certain patched releases). Test in your ISE version. (Cisco)

Validation: Use DevTools Console on the preview/test URL to check for any JS errors after page load.

---

Step H — Apply & Test portal in live flow (end-to-end)

1. With portal customized, set it as active in Guest Portals → Portal Settings → choose the portal for the guest service.
2. Trigger a captive portal redirect from your controller (or simulate with a browser hitting the portal test URL). Use controller or switch logs to ensure redirect occurs.
3. Complete a registration/login flow and verify username/password (if configured), AUP, and email/SMS notifications.
   • [Screenshot: Guest Portal Test URL]

Validation checklist

• Portal loads on desktop and mobile (responsive).
• Images and CSS load without mixed content errors.
• JS executes without errors.
• Variables display correct guest data.
• Email/SMS templates use the same variables and deliver correctly.

---

Quick CLI / curl validation (network / availability tests)

• From lab host:

# check TLS & redirects
curl -vk https://10.10.10.11/portal/login?portalId=GuestSelfReg

# fetch assets to ensure accessible
curl -I https://10.10.10.11/portal/images/mylogo.png

• Check ISE syslog remotely if configured, or check Live Logs in GUI for portal access events.

---

Troubleshooting & Diagnostics

Use this ordered checklist — each item includes diagnostic commands or GUI checks.

Symptom A — Changes not appearing in Preview or Test URL

1. Cause: Cached browser CSS/JS.
   Fix: Use incognito/private window, clear cache, or disable caching in DevTools.
2. Cause: You edited portal via Portal Builder but also modified ISE GUI. Portal Builder overwrites GUI.
   Fix: Use Portal Builder for edits; do not mix methods. (studylib.net)

---

Symptom B — Images 404 or blocked

• Check DevTools Network tab. If image fetch returns 404, ensure image uploaded to portal assets or the path matches /portal/images/yourimage.png. If blocked (Mixed Content), ensure image delivered over HTTPS.
• Use curl -I https://<ise>/portal/images/yourimage.png to check.

---

Symptom C — JS not executing / errors in console

• Open browser Console (F12) and note errors. Common errors: CSP blocking, single-line comment parsing (ISE bug on some releases), or undefined DOM elements because of timing.
• Try moving script into bottom of page or wrap in DOMContentLoaded. Check release notes for JS parsing quirks. (Cisco)

---

Symptom D — Variables not substituted (e.g., ${ui_user_name} shown literally)

• Confirm you’re using the variable name exactly as defined for your ISE release (see admin guide variables table). (Cisco)
• Ensure the page where you used the variable is in the correct portal scope (Guest vs Sponsor pages have different available variables). (Cisco)

---

Symptom E — Portal breaks captive portal redirect or login flow

• Check controller/NAD logs to confirm redirect is to ISE portal URL and not blocked by firewall.
• On ISE check Live Logs for Access-Request / URL redirect attributes. If no logs, NAD may not be sending redirect to ISE correctly.

---

Debugging tools & filters

• Browser DevTools: Console, Network tab, disable cache.
• curl: curl -vk <portal test URL> for TLS/redirects.
• tcpdump / wireshark (on lab host or in path to ISE): tcpdump -i eth0 tcp and port 443 -w portal.pcap then inspect HTTP(S) flows and assets.
• ISE GUI: Operations > RADIUS > Live Logs and Guest > Guest Logs to trace sessions.
• ISE Portal Builder logs (if used): check export/import tool output for errors.

---

Lab Walkthroughs with Validation (two scenarios)

Lab Walkthrough 1 — Quick brand (logo + color + AUP text)

Goal: Replace logo, change button color, show AUP text, confirm guest gets credentials.

Steps:

1. Enable portal customization (Step A).
2. Upload mylogo.png in Portal Page Customization → Global Page Customization.
3. Edit Welcome page Instructional Text: paste logo + headline. (See Step B)
4. Export theme.css → edit button color as shown in Step C → import theme and apply.
5. Preview portal; connect client to guest SSID, trigger redirect. Complete self-register → verify success page shows username/password variables.
   Validation: Check ISE Live Logs for Access-Accept and Guest account creation; verify email/SMS sent (if enabled). Use curl or browser.

---

Lab Walkthrough 2 — Full custom portal with Portal Builder

Goal: Build a multi-page portal with background image, custom layout, and multi-language label; upload via Portal Builder.

Steps:

1. Use isepb.cisco.com → create new portal template (Hotspot Guest). Upload images in Image Manager. (studylib.net)
2. Customize pages visually, add translations per locale. Export the portal package.
3. Download ISEPB Portal Upload & Config Tool and run -> upload portal zip to ISE. The tool will create a portal and assets. (studylib.net)
4. In ISE, select the imported portal and Preview. Test end-to-end by connecting a client and completing flow.
   Validation: Preview page fidelity, check mobile vs desktop views, test translations by adding ?lang=xx or selecting locale in portal UI.

---

Expert Level Use Cases (step-by-step mapping + validation)

---

Use Case A — Multi-site locales & per-site branding

1. Create one portal per region (Portal Builder allows easy duplication). Upload per-site logos via Image Manager.
2. In ISE Guest Portals assign portal based on NAD location (NAS-IP) or SSID so guests see local branding.
3. Validate: connect from each site and confirm correct portal served.

Validation: Use NAD redirect attributes (NAS-IP or Called-Station) to map site → portal. Test with curl from site network or use a test client.

---

Use Case B — A/B test two portal variants

1. Create Portal A and Portal B (slight differences in CTA or layout).
2. Use an external load balancer or DNS trick to route half the traffic to one portal URL and half to the other (or change portal on a test VLAN).
3. Measure metrics (conversion rate) via portal page events injected to analytics endpoint (careful with privacy & legal). Keep JS minimal and review SOC risk.

Validation: Track page hits in analytics, ensure both portals work with captive portal redirect and guest creation.

---

Use Case C — Integrate OAuth (social / SSO) button in portal

1. Add OAuth button and redirect flow in portal HTML; backend must validate tokens and call ISE ERS/Guests API to create/approve guest.
2. Implement server side token exchange off the portal (ISE only hosts static pages; heavy backend logic should live external to ISE). Use the portal to redirect/iframe external flows and receive callback to a backend that calls ISE APIs. (ISE’s pages are presentation layer.) (studylib.net)

Validation: Complete OAuth flow end-to-end and confirm ISE guest account created via ERS or portal API.

---

FAQs – Cisco ISE Custom Guest Portal Branding (HTML/CSS)

Q1. Can I use my company’s existing HTML/CSS template for the Cisco ISE Guest Portal?
A1. Yes. Cisco ISE supports importing custom HTML and CSS files into the Guest Portal. However, you must ensure that all placeholders like $userName$, $password$, $portalName$ remain intact. These are system variables that ISE injects dynamically. Always test after upload.

---

Q2. Does ISE allow embedding JavaScript along with HTML/CSS for branding?
A2. Yes, but with limitations. You can include custom JavaScript to enhance UI/UX (like hiding/showing fields, validation, or animations). However, security restrictions apply—ISE blocks certain scripts to prevent XSS. Always test in a lab before production.

---

Q3. What image formats are supported for logos and backgrounds?
A3. Cisco ISE supports .PNG, .JPG, and .GIF formats. For performance and compatibility, PNG (transparent) is recommended. The file size must be within the ISE upload limit (usually <1 MB for best performance).

---

Q4. Can different SSIDs/WLC WLANs have different branded Guest Portals?
A4. Yes. You can create multiple Guest Portals in ISE and map them to different SSIDs or different authorization policies. For example, “Conference Guest Wi-Fi” may use a blue theme, while “VIP Guest” may use a gold theme.

---

Q5. How do I revert to the default Cisco ISE branding if my custom HTML/CSS breaks the portal?
A5. Navigate to:
Work Centers → Guest Access → Portals & Components → Portal Page Customization → Revert to Default.
Alternatively, restore from a previous ISE backup if the portal fails to load.

---

Q6. Does Cisco ISE allow responsive design (mobile-friendly) for guest portals?
A6. Yes. ISE’s Guest Portal engine supports CSS media queries. You can make the design responsive for laptops, tablets, and smartphones. Testing with Chrome DevTools/Firefox Responsive Design Mode is recommended.

---

Q7. Can we add multi-language support in the Guest Portal?
A7. Yes. ISE provides localization options for default text (like Login, Password). For full branding, you can add language-switching logic using HTML/JavaScript. Many enterprises integrate locale-based redirection for multilingual guest portals.

---

Q8. Is SSL required for the Guest Portal?
A8. Absolutely. Cisco ISE portals use HTTPS by default. You must install a trusted SSL certificate (signed by a public CA) to avoid browser warnings. Self-signed certs can break branding when external resources (like CDN fonts or logos) are referenced.

---

Q9. Can we integrate third-party analytics (Google Analytics, Adobe Analytics) into the portal?
A9. Yes, by embedding the analytics JavaScript tracking code in the custom HTML header/footer. Ensure compliance with privacy regulations (GDPR, HIPAA). Test performance impact before enabling.

---

Q10. How do I validate custom branding changes before going live?
A10. Use the following approach:

• Create a test Guest Portal and map it to a dummy SSID/VLAN.
• Validate with multiple browsers (Chrome, Edge, Safari).
• Use tcpdump or ISE Live Logs to confirm the portal loads correctly.
• CLI command on ISE: application configure portal (to check/reset portal services if branding fails).
• Confirm with guest user authentication flow to ensure placeholders like $username$ render properly.

---

YouTube Link

For more in-depth Cisco ISE Mastery Training, subscribe to my YouTube channel Network Journey and join my instructor-led classes for hands-on, real-world ISE experience

---

Closing Notes (key takeaways)

• Use the simple inline GUI editor for small AUP/label changes and logo swaps. Use Portal Builder for multi-page or heavy layout customization. Don’t mix both approaches for the same portal. (studylib.net, Cisco)
• Always export the existing theme before editing and test in lab across desktop & mobile. Validate using DevTools, curl and ISE Live Logs.
• Keep JavaScript minimal, trustworthy, and test the exact ISE release for known UI parsing quirks. Use substitution variables from the admin guide for dynamic guest data. (Cisco)

---

Upgrade Your Skills — Start Today

For more in-depth Cisco ISE Mastery Training, subscribe to my YouTube channel Network Journey and join my instructor-led classes.

Fast-Track to Cisco ISE Mastery Pro — 4 months instructor-led: hands-on labs (EVE-NG/VMware), weekly live troubleshooting, Portal Builder exercises, and CCIE-style scenarios.
Reserve a seat & get the Guest Portal labpack: https://course.networkjourney.com/ccie-security/

Enroll Now & Future‑Proof Your Career
Email: info@networkjourney.com
WhatsApp / Call: +91 97395 21088

---