Greetings AirHeads, hope to see some of you next week in Vegas. This is a placeholder forum entry in prep for the Guest customization session:
Wednesday 4:45 Mandalay Bay J
AB307 The Wonderful, Customizable World of ClearPass Guest
After the session this posting will get updated with individual code snippets, screenshots that were shown.
Sorry for the delay. Hope those who were in the session got something out of it. If you have a distinct question please create a new forum post. I will be monitoring the boards.
Starting point was a relatively stock 6.8 with the following:
* SMTP server in Policy Manager
* SMS server in Guest
* Basic controller setup for captive portal and RADIUS
* Basic Policy Manager Guest service template
* LDAP server within Guest for sponsor lookups
* A dummy landing Web Page 'redir.php' so I do not have to keep going back to the controller to swap anding pages.
redir.php:
New Configuration » Pages » Web Pagesnamed 'redir', with Blank Skin. HTML set to:
{capture name=url}https://wonderful.clearpass.boston/guest/airheads.php?{$smarty.server.QUERY_STRING|escape}{/capture}
<html>
<head>
<meta http-equiv="refresh" content="0; URL='{$smarty.capture.url|trim}'" />
</head>
<body><a href="{$smarty.capture.url|trim}">{$smarty.capture.url|escape}</a></body>
</html>
The controller captive portal was set to https://wonderful.clearpass.boston/guest/redir.php. All I needed to do was edit 'airheads' to whatever new page I had created. A normal deployment never needs this but you could add some logic to detect incoming attributes and redirect based on apname, remote address or something.
Smarty:
Whenever you see code with { } tags, that is our templating languages and available in most text areas like the headers and footers. We use Smarty 2 as documented https://www.smarty.net/docsv2/en/. The most important thing to know about this is that when you write CSS or JavaScript on your own, which almost always also uses { and }, you need to escape out of our processing. You MUST wrap the following {literal} lines around your code:
{literal}
Your code with { }
{/literal}
If you do not it will probably not even save as you will fail a syntax check.
General Setup:
On Configuration » Guest Manager don't forget to update the Site SSID to your main Guest SSID so it is auto included in the receipts.
This is also the spot controlling random usernames and passwords. We showed the new lower case letters with no vowels and the two words separated by a small number.
Basic Self-Registration:
We looked at the stock self-registration and it's receipt. I wanted to keep the stock registration as a reference point so I duplicated guest_register on Configuration » Pages » Self-Registrations setting guest_register as the parent. A child self-registration is simply the shell of a config with the name overridden. Until you make edits it always inherits the values of it's parent (which will inherit from it's parent!). This is very useful if you need regions with different skins or landing instructions and the NAS and receipt may be the same. You can centralize core configuration. When editing a child registration, any config wrapped in a green border is using the parent value. Any overridden value will have a Revert action beside it. This also holds true for editing fields in a form. They default their config to the base field. If you want global changes change the base under Configuration » Pages » Fields, otherwise Edit just changes the form you are on.
We went to disable fields in the receipt but first had to Override Parent Fields as the registration and receipt forms default to re-using the parent. Once done we disabled sponsoe_name, sponsor_email and start_time. These were just a distraction for our needs.
On the registration form I wanted to extend the accounts from 1 day to 7. I edited expire_after and changed the Initial Value to 168. This field is in hours, so 7*24. I disabled validation, selected Advanced and checked Force Value. For any hidden field with a special value, we highly recommend setting Force Value as it stops anyone with browser trickery from overridding it.
We enabled visitor_phone as I wanted to capture their number as well send an SMS receipt. The phone field defaults to country+number so we can consistently store the numbers in their international format. The top of the country options can be set to commonly expected ones. Preferred Countries is available when editing the field and is a comma separated list of the two-letter country codes. If you wanted North America: 'us,ca,mx'. As of 6.8 their is a global setting under Configuration » Receipts » SMS Receipt that will cover registrations and administrative pages.
6.8 defaults guest facing pages to the free Galleria Skin. 6.8 also includes a new Galleria theme with new background images and a more modern form. Unfortunately the new theme is not the default. Please go to Administration » Plugin Manager, find Galleria Skin > Configuration and set Version to 'Version 2'. Feel free to upload your logo into Content Manage and use that in Galleria. Note the professional skin service is still the preferred method if you want to look like your existing branding.
reCAPTCHA:
6.8 includes Google's reCAPTCHA 2 support https://www.google.com/recaptcha/admin. The 'I am not a robot' checkbox common on many logins and forms. I wanted this right above the submit button so I selected 'submit' in the registration form fields list and selected Insert Above. When adding a field to a form, you always insert relative to one of the existing fields. We ship with Google's public test keys and they display a warning as such. Google's service is free so just follow their directions to generate a set of keys against your hostname and add them in the field settings. Note ClearPass and the captive portal network need to be able to access www.recaptcha.net. Update firewalls for ClearPass and the ACL within the AP/Controllers for the captive portal role.
The Weather:
We quickly added the weather to the oeprator login as we ran out of time, but it was suppose to be on the self-registation landing. The weather was an easy example of how to add external HTML snippets to Guest pages. This could include advertising, analytics trackers, twitter feeds, event fees, etc. The only important thing to keep an eye out for is the captive portal profile on the AP/controller needs to allow whatever sites required. In our case, we had an API key from https://openweathermap.org/ and updated the ACL for api.openweathermap.org. The following went into the Footer HTML. The Las Vegas zip code is hard coded. You would want to change that and the API key. Advanced code is capable of detecting location via the browser but often in a secure wifi environment that is not always the correct value.
<div id="weather" style="font-size:34px;line-height:30px;"></div>
{nwa_script src=jquery.min}
<script type="text/javascript">
var zipcode = 89109; // Could do some 'apname' mapping or something here.
var url = '//api.openweathermap.org/data/2.5/weather?zip=' + zipcode;
{literal}
$(document).ready(function () { $.get(url, {
units: 'imperial',
mode: 'json',
APPID: '1234567890987654321'
}).done((weather) => {
$('#weather').html('<p>Welcome to <span class="location">' + weather.name + '</span>.</p><p>Currently: <span class="temp">' + Math.round(weather.main.temp) + '°F</span></p>');
});
});
{/literal}
</script>
Sponsor Confirmation:
We showed how easy it was to enable the sponsored flow. This is used to keep people on the receipt page until someone enables their account. On the registration from I inserted sponsor_lookup to the top of the form and enabled Sponsor Confirmation from the main registration landing map. I aleady had an AD server configured in Administration » Operator Logins » Servers. When configured, sponsor_lookup is an as-you-type search box querying against the AD server. When saved we look up the account and pull in the email and name and store this into the guest account.
If you do not want the searching for security reasons, you can instead have a fixed list of sponsors. You can edit sponsor_lookup, change it's User Interface to 'Dropdown'. This will make a Options text area appear. The syntax for this is 'key | Label', one per line.
han.solo | Flight School
darth.vader | Empire
For any UI field with a drop down, we recommend setting the Validation to IsInOptionsList. This ensures only the values you display can be saved.
Auto Submit:
Since the guest was receiving emails and SMS with their password, we wanted to auto submit on the receipt as soon as possible. In the sponsored case this would be after the sponsor, and in a normal scenario it would be immediately following the save. In order to show the timing of the sponsored flow I went to the Sponsor Confirmation settings, selected UI Overrides, and in Registration Receipt changed the refresh from 30 to 5 seconds in the two places '30' appears. The auto submit code goes in the Receipt Footer HTML.
{if !$error && !$mac_error && !$username_error && !$_form_error}
{nwa_script src=core}
<script type="text/javascript"><!--{literal}
addLoadEvent(function() {
Nwa_SubmitForm(_form_name,"ID_"+_form_name+"_submit");
});
{/literal}//-->
</script>
{/if}
As long as there is not an error this paste will auto submit any Guest form. It is highly recommended if you turn a self-registration into device creation.
Operator Experience:
The sponsor needed to enter their credentials in order to confirm the account, which means they now have an operator session. Went into /guest/ to look around. Manage Accounts had employee accounts than I wanted that sponsor profile to see, so we went to Administration » Operator Logins » Profiles and edited the Profile I had previously created. In the Roles list, I select Guest to stop the other ones from being seen. We also updated this profile to use a custom skin instead of the default ClearPass. Logging the sponsor out an in we now had an updated UI and accounts were locked down. On top of updating a profile with a skin, you can also change the skin used on the operator login page on Administration » Operator Logins » Login Configuration.
Access Codes:
I wanted to convert the self-registration to create an account requiring simply an access code, not a username and password.
* Disabled sponsor confirmation.
* Added username_auth to the registration fields list and ensured it's Initial Value was 1, along with Advanced > Force Value. This is the magic key that allows accounts to work when a login is configured for Access Codes.
* Since the registration is still asking for email, that would always become the username. We do not want that so we inserted random_username_method into the registration form as a Hidden Field. In the Initial Value we set the method we want. These are listed out in the Guest Guide. But you can use 'nwa_novowels_password'. Disable validation and set Advanced>Force Value.
* In the receipt fields, edit password and change the user interface to Hidden Field.
* In the registration login settings set 'Only require a username for authentication'.
Accounts created with these settings cna have a simple 1-field login form.
Translation and Text:
When we converted to Access Codes 'Username' was still used throughout and we wanted to update this to 'Access Code'. You can edit the registration and fields directly, but there are alternative ways to bulk update text using the translation tools. Using the translation tool also is required given all stock pages default to a number of languages and you may need to override those as well.
Configuration » Translations » Assistant has three assist options that will help that logged in admin deal with translations. Turn all these on and start editing pages. A number of links will be added to each page when translation options are available. There are two parallel workflows for translation and text updates. The original are text IDs that can be updated to globally updated. Overridding a text ID affects all pages using that text so they should be used with care. These are updated on Configuration » Translations » Language Packs by selection your language and selecting Translations. You can search by a text substring on this page, or use one of the Common IDs links to get to an area you need, or just type in the IDs you want. For instance ID 24 is 'Username:' used on many forms, and 25 is 'Operator Login' used on the operator login. The other translation tool embeds the override right into the configuration dataset. This is used for the fields and forms that can have many parallel implementations with different meanings. These translations are found on many edit lists by selection your main configuration and clicking the Translations action. These translations were made available in 6.7.0.
For Access Codes we only wanted to update the self-registration so we chose the newer method. On Configuration » Pages » Self-Registrations we select the registration and clicked Translations, the the Edit link for Default (English). On this page we searched for username and updated all instances. Self-registrations break each form out so after saving we changed the Item to the registration form and receipt form and also looked for 'username' to replace appropriately. We also noticed the email field stated 'This will become your username to log into the network.' so we deleted that. I switched the language to French and made the same updates in French. My French test browser picked these up immediately.
Operator Form Overrides:
I wanted to update the operator experience to also say Access Codes, but I wanted to leave the defaults as is for our Super Administrators. To do this I want to Configuration » Pages » List Views selected guest_users and hit Duplicate. On the new view we added email, enabled visitor_phone and visitor_name, and disabled role_name and start_time. For the Sponsor profile to use this we went to Administration » Operator Logins » Profiles, edited the profile, and at the bottom selected 'Override the application’s forms and views'. This opens up a means to override most of the Guest and Devices pages. We found Manage Guest Accounts, selected the dropdown and selected guest_users_2. We could then log int the sponsor user and see Manage Accounts with the new columns. The Super Administrator browser still had the stock columns. Using the same Translations action as before, we updated guest_users_2 to change Username to Access Code.
Others:
We ran out of time before getting to a couple last things.
Codes in SMS Available in Forms:
Mac's and iOS support detecting access codes in SMS and prompting you to use them within the keyboard app. This can come in very handy for access code logins. Update the SMS Receipt to 'Access Code: {$u.username|escape}', and then in the Footer HTML of the Login Page append:
{nwa_script src=jquery.min}
{literal}
<script>
$('input[name=user]').attr("autocomplete", "one-time-code");
</script>
For Aruba devices, the username is 'user'. This might be 'username' or something else for other vendors and you can View-Source and look for the field. Update as needed. If your workflow is sending passwords over SMS then update to 'name=password'. Engineering is still researching the timing of how long the code is available and when Android will support it as well.
https://developer.apple.com/documentation/security/password_autofill/enabling_password_autofill_on_an_html_input_element
QR Codes:
Guest has a means to output a QR code in templates. To create bulk access codes to print out with QR codes you can do the following:
* Add username_auth to create_multi on Configuration » Pages » Forms and make it's User Interface a checkbox.
* On Configuration » Receipts » Templates duplicate Account List and rename it Access Codes. Update Username to Access Code and delete the block for passwords.
* Replace the username printout block with {$u.username|escape} to:
{nwa_qrcode width="128" format="png" fg="000000" bg="ffffff" padding="0" error_correction="0" class="" style="" alt="" title=""}{$u.username}{/nwa_qrcode}
Force Destination:
A reminder you can override someone's original destination after they login with the Default Destination URL and Force Destination checkbox on all login setups. This is especially useful when your workflow allows mobile to bring up a CNA.
If you have made it this far and are still reading, we'll consider you an amigo. Well done.