How To Provision Mobile Apps
Provisioning Mobile Apps
This article sets out how to set up your Swivel installation to provision the Swivel AuthControl Mobile App using the preferred Quick Provision Approach.
To be able to use quick provisioning you'll first need to contact Swivel Secure to enable this feature if it hasn't been enabled.
How it works
The provisioning works in the following way.
- User is sent a Provision Message
- User accesses the provision url on their mobile (by clicking the link or scanning the QR code)
- Mobile accesses the url, that takes the device to the Swivel Mobile Client Server
- Mobile downloads the specific server settings required for that client
- Mobile then uses those settings to access the Swivel Core Server to be provisioned
For this process to work the Swivel server needs to be allocated a Site ID and have a method of sending the required message to the user to be provisioned.
When the mobile app is provisioned, it contacts the Swivel Mobile Configuration (SMC) server and presents its Site ID, and in return is given the server settings for that customer. To request a site ID you need to send a request to Swivel Support and include the following details:
- The public hostname/ip address of the Swivel server, along with the port number, context, and where the server is set to use SSL. A typical entry would be
Host: swivel.company.com Port: 8443 Context: proxy SSL: true
You may also optionally state two other settings to define whether you wish the clients to work in Local Mode and if you want to use One Touch
One Touch: true Local: false OATH: false
Swivel support will inform you of your Site ID and this needs to be enter on the Site ID field on the Server - Name screen.
The URLs that will be used to contact the Swivel SMC server are set under Policy -> Self Reset.
Quick Provision Link
If the user can access their email on their mobile device they can be sent an email that contains a url that will instigate the provision process. Alternatively this url can be sent as a Text Message.
To use this method of provisioning you need to ensure that on the Messaging configuration screen, eg Messaging -> SMTP, the following text is included:
To automatically provision your device, click the following URL: %URL_COMPLETE%SITE_ID/%NAME/%CODE
When the message is sent to the user the %URL_COMPLETE%SITE_ID/%NAME/%CODE will be replaced by the SMC url, the site-id, the user's username and the user's provision code.
The other option is for the provision message to include a QR code that the user can scan from their Swivel Mobile App in order to start the provision process.
The Swivel User Portal includes an application that will display the QR code relevant to the provision message. This needs to be available via the internet so that the provision message can include a link to it. For example if your userportal is deployed as https://portal.domain.com:8443/userportal, then the QR code should be available from https://portal.domain.com:8443/userportal/getQRCode?text=
To use this approach the provision message must be in html format include text along the lines of
Click here to view QR Code: url4
When this message is sent to the user, url4 is replaced by the html required to pull in the image.
There are a number of polcies you can set around the provision and use of the Swivel Mobile App.
These policy settings define how the provsion process operates and are on the Policy -> Self Reset page
- Allow user self-provision of mobile client
- If set to yes the user can, at any time, request a new provision code via the user portal. If set to no then once a user has provisioned a mobile device, the only way to provision a new device is via the admin console.
- Send provision code as security string
- If this is set to No, then the provision message will be sent to the same destination as all other alert messages, usually an email address. If this is set to yes then the provision message will be sent to the same destination as their security strings, usually a mobile phone number. This option allows the system administrator to ensure that provision messages are only sent to the users registered mobile device
- Log device information when provisioning
- If set to yes, any http headers parameters sent by the mobile device will be logged against that user's device. If a mobile client attempts to download security strings and presents a different set of headers to that that was logged when the device was provisioned, the request will fail
- Provision Code Validity period (seconds)
- For how long the provision code is valid
When a mobile client is provisioned it downloads a set of policies from the Swivel Server. These policies are set on the Policy->Mobile Client screen
These policies are
- Allow user to enter PIN
- If the user has a PIN they can enter that PIN into the mobile client and it will extract the associated one-time code. If this policy is set to Npo, the user will be shown the security string and the user will have to perform the one-time extraction mentally.
- Allow user to choose how to extract OTC
- If the user is allowed to enter their PIN, if this policy is set to yes, the user can opt to disable PIN entry
- Allow user to browse strings
- The mobile client will work sequentially through the security strings that it has downloaded, however if this policy is enabled the user can browse through strings, eg skip strings. THis maybe required where the user has to use a specific string in order to authenticate (eg for MSCHAP authentication)
- Provision is numeric
- Should the user need to enter their provision code manually, by setting this you yes the mobile client will display a numeric only keypad on the provision code entry screen
- Show Settings
- If Quick Provision is being used, there should be no reason for a user to be able to view their settings. However this policy enables the user to see these settings
- Sync Index
- Some RADIUS protocols work in such a way that only a specific security string can be used to authenticate. Syncing the index means the Swivel Mobile Client will always use the security string that the server is expecting. To Read more about Sync please go here
- Support Email Address, Support Phone Number
- These support details will be shown to the user when they access the help screen on the mobile client
- VPN URL Scheme
- Certain versions of the mobile client may support the launching of a VPN client. This setting defines the format used to enable this
A key question when diagnosing provisioning issues is to determine if the Swivel Client is contacting the Swivel server or not. If there are no log entries in the Swivel logs when the provision fails, it implies the error is a configuration or network issue prior to this stage in the process/
User clicks the link or scans the QR Code and nothing happens This implies the settings for the SMC server are not correct
User sees the initial config screen then provision fails with connection error Check site is set and site id settings are correct Check that the urls are accessible. To test this you can paste
http(s)://<site id settings>/AgentXML?xml=<?xml version="1.0" ?><SASRequest><Version>3.6</Version><Action>ping</Action></SASRequest>
Where site id settings represents the server, port and context set for your server ID
You should see a response
<?xml version="1.0" encoding="UTF-8"?> <SASResponse> <Version>3.6</Version> <RequestID/> <Result>PASS</Result> </SASResponse>
Check the validity of the certificate and also check that there are no issues in relation to weak ciphers or encryption standards
Invalid Provision Code If the user gets an invalid provision code check when the code was sent and how long the validity of the code is sent to. If this is an HA pair, need to ensure that the same appliance that issue the provison code also received the provision request from the mobile or that Session Synchronisation has been enabled/