Contents

1 Overview

2 Business Logic

2.1 Connecting to Wi-Fi Network on Mobile Devices

3. Implementation for Mobile Devices

3.1 Step 1: Get Store's Wi-Fi Information

3.2 Step 2: Modify Portal Page for Mobile Devices

3.3 Step 3: Ensure AP Device Allows Access Temporarily

3.4 Step 4: Authenticate User's Weixin Identity and Allow Access

3.5 Step 5: Connect to Wi-Fi Network by Scanning QR Code

3.6 Portal Page Demo for Mobile Devices

3.7 FAQ

4 Offline Authentication

4.1 Step 1: Get Store's Wi-Fi Information

4.2 Step 2: Modify Portal Page for Mobile Devices

4.3 Step 3: Authenticate User's Weixin Identity and Allow Access

# Overview

The hardware authentication protocol is used to modify the authentication method of a portal-based device, so that the device can allow a user's access request by authenticating the Weixin user identity, enabling the user's phone to connect to a Wi-Fi network quickly.

# Business Logic

# Connecting to Wi-Fi Network on Mobile Devices

Connection Process on User Side

Tap SSID on the phone to invoke the portal page, then tap Wi-Fi via Weixin on the page to enter the lead-in page for connection, where the Official Account logo and name are displayed. Tap Connect Now to connect to the Wi-Fi network. When the connection is successful, the "Connection Successful" page appears, where the user can follow the merchant's Official Account.

Workflow Chart

If the text in the chart is too small to be legible, save the image locally by selecting Save As and then zoom in the image.

# Implementation for Mobile Devices

Modify the authentication method of your portal-based device by following the steps below to enable the users' mobile devices to use "Wi-Fi via Weixin".

# Step 1: Get Store's Wi-Fi Information

A store's Wi-Fi information includes: appId, shop_id, ssid, and secretkey. Get the information by either of the following two ways:

1. Go to the webpages

In the Wi-Fi via Weixin plug-in of the Weixin Official Accounts Platform, open Device Management > Add Device, and select Add Wi-Fi via Weixin + NFC Service > Portal-Based Device; when the device is added successfully, you can get the store's Wi-Fi information.

For an added device, you can obtain the store's Wi-Fi information in Device Details > View Device Modification Info.

2. Call an API

Obtain the information by calling the Add Portal-Based Devices API.

# Step 2: Modify Portal Page for Mobile Devices

For a mobile device, reference the following Weixin JSAPI in the portal page to give the original Wi-Fi portal page the ability to invoke Weixin:

<script type="text/javascript" src="https://wifi.weixin.qq.com/resources/js/wechatticket/wechatutil.js" ></script>

Call the JSAPI to invoke Weixin:

Wechat_GotoRedirect(
appId,      
extend,     
timestamp, 
sign,       
shop_id,   
authUrl,   
mac,      
ssid );

Example:

Wechat_GotoRedirect(
'wx23fb4aaf04b8491e',  
'demoNew',            
'1441768153341',          
'a355c78bad9be9235d2105d28f8e010c',   
'6747662',  
'http://wifi.weixin.qq.com/assistant/wifigw/auth.xhtml?httpCode=200',       
'aa:aa:aa:aa:aa:aa',     
'2099');

Parameters

Calculation of signature:

sign = MD5(appId + extend + timestamp + shopId + authUrl + mac + ssid + secretkey);

Note: The timestamp is expressed in ms.

* As required by the Apple Inc., HTTPS is used as the communication protocol for the Weixin app on iOS devices as of mid-December 2016. Please note:

1. If the authURL is a domain name, both HTTP and HTTPS need to be supported. When a Weixin user accesses a network, the protocol for the access request is same as that for the response.

2. If the authURL is an IP, support for HTTP access is required.

3. For the compatibility between the old and new versions, the authURL field still begins with "http" when the JSAPI is called on the portal page.

# Step 3: Ensure AP/AC Device Allows Access Temporarily

Please ensure that the AP/AC can temporarily allow the user's access request when the portal page is opened. Only after the user's access request is allowed temporarily can the JSAPI be called to invoke Weixin and get the user's identity information, so that the authentication request is successful and the user's phone is connected to the Wi-Fi network.

Note: When Weixin is invoked on an iOS device, the connection will be switched to the mobile data network if the Wi-Fi network is unavailable. Therefore, please ensure that the AC/AP supports "Allow Access Temporarily".

Some Android devices' web browsers cannot automatically invoke Weixin. In this case, see the solutions in FAQ.

# Step 4: Authenticate User's Weixin Identity and Allow Access

After being invoked, Weixin automatically initiates a request to the authUrl (input parameter of JSAPI) to submit the user's Weixin identity parameters required for authentication, including extend, openId, and tid.

Example of the request:

http://www.foo.com/portal/auth.html?extend=xxx&openId=xxx&tid=xxx

Parameters

The authentication server to which the authUrl points must be able to identify these parameters and return the AC authentication result to Weixin, which will inform the user of the connection result based on the HTTP response code.

If the HTTP response code is 200, the authentication is successful, and the Weixin user is redirected to the "Connection Successful" page. After tapping "Done", the user is redirected to the merchant's home page. If the authentication server needs to temporarily redirect the authentication request, return 302 and the next hop address so that Weixin initiates a request again to the next hop address (only one 302 redirection is allowed). If a code other than 200 and 302 is returned, or the number of 302 redirections exceeds the limit, the authentication fails and the Weixin user is redirected to the connection failure page.

Note: The timeout threshold of a Weixin request is 10s. Please ensure that the authentication server returns the AC authentication result (HTTP response code) within 10s after Weixin sends a request to authUrl. If the authentication server fails to return the result within 10s, the authentication is considered a failure.

# Step 5: Connect to Wi-Fi Network by Scanning QR Code

After completing Steps 1-4, you can implement a portal-based connection to the Wi-Fi network by scanning QR code, as described by the steps below:

1. Redirect access request to portal page

When an unauthenticated mobile phone user attempts to connect to the Wi-Fi network, the AC forwards the user's HTTP request to the portal page on the Portal Server, where the AC further authenticates the user identity. If the HTTP request comes from Weixin, just contain the "authUrl" and "extend" parameters in the redirect URL.

http://www.foo.com/portal/portal.html?authUrl=http%3A%2F%2Fwww.foo.com%2Fportal%2Fauth.html&extend=xxx

2. How to verify if the HTTP request comes from Weixin

Parse the "User-Agent" in the header of the HTTP packet to verify whether the keyword "micromessenger" is included. (Be sure not to intercept other Weixin HTTP requests. Therefore, the keyword should be exactly matched.) The following is the sample code:

...
String userAgent = request.getHeader("User-Agent");
if(userAgent.matches(".*micromessenger.*")){  response.sendRedirect("http://www.foo.com/portal/portal.html?authUrl=http%3A%2F%2Fwww.foo.com%2Fportal%2Fauth.html&extend=xxx ");			
}
...

Weixin parses the "authUrl" and "extend" parameters in the redirect URL of the Portal Server to proceed with the connection process.

3. Prevent the automatic pop-up of portal page on an iOS device

In order to prevent the automatic pop-up of portal page on an iOS device when the device is switching SSID, whitelist the iOS device's sniff address "http://captive.apple.com/hotspot-detect.html".

4. Download QR code materials

After modifying the portal server, call the Configure Connection Method API, download the QR code and post it in the store. A user can connect to the Wi-Fi network by scanning the QR code on the materials.

# Portal Page Demo for Mobile Devices

Modify the portal page for mobile devices by referring to the Demo (JS code is in the page).

Open the following link using your mobile browser (enter it manually or scan the code below to get the URL):

https://wifi.weixin.qq.com/operator/demoNew.xhtml

If you scan the QR code with Weixin, tap the button in the upper right corner and select Open in Browser, instead of directly opening it in the Weixin browser.

# FAQ

1. Some Android devices' web browsers cannot automatically invoke Weixin.

Weixin 6.2.5 or above on Android devices can be opened manually to continue the connection. To ensure the process goes well, developers should ensure that:

1. The Weixin version is 6.2.5 or above on Android devices;
2. When Weixin cannot be invoked automatically, a message appears automatically to prompt the user to switch to Weixin manually (refer to the JSAPI in the Demo);
3.When calling the Weixin JSAPI in the portal page, the AP device's SSID and the mobile phone's MAC address are correct and invalid;
4.The test begins with switching to the target SSID. For example, if the phone is previously connected to the 3G or 4G mobile data network or a Wi-Fi network other than the target SSID, switch it to the target SSID manually.

2. How can I ensure that an iOS phone is still connected to the target SSID after the phone is redirected from the portal page to Weixin?

To ensure the Wi-Fi network is available, an iOS device does not switch to the Wi-Fi network immediately after the user selects a SSID. Instead, it sniffs whether the SSID can reach the preset services on the public network. Only after it verifies this, it is connected to this SSID. At this time, in an portal-based AP environment, a portal page pops up for authentication. When the authentication is successful, the Cancel button at the top right of the page changes to Done. If leaving the page while Cancel is shown, the user is disconnected from the SSID they just selected and returns back to the previous available connection. But if the user leaves the page in the Done status, the connection is maintained.

When the Weixin authentication is successful, the user is redirected from the portal page to Weixin. Therefore, ensuring the button at the top right of the portal page is Done is the prerequisite. The following considerations should be taken into account :

1. Ensure all the access requests from the phone are allowed temporarily after the portal page pops up;
2. When the access requests are allowed, refresh the portal page in part or in whole to enable the iOS device's sniff again.
3.IOS When the iOS device verifies that the SSID can reach the preset services on the public network, the **Cancel** button changes to **Done**;
4.After the above actions, call the JSAPI for switching to Weixin to complete the authentication and connection.

# Offline Authentication

In the Wi-Fi environment, the user phone's access requests cannot be allowed temporarily for the communication with the Weixin backend. In this case, offline authentication can be used. Connect the mobile device to the Wi-Fi network via Weixin by following the steps below.

Workflow Chart

If the text in the chart is too small to be legible, save the image locally by selecting Save As and then zoom in the image.

# Step 1: Get Store's Wi-Fi Information

Get the store's Wi-Fi information as described in the "Step 1: Get Store's Wi-Fi Information" in "Implementation for Mobile Devices"

# Step 2: Modify Portal Page for Mobile Devices

In the portal page, reference the link for invoking Weixin offline so that the original portal page is able to invoke Weixin. The link format is as follows:

 function callWechatBrowser(){var appId = getParam('appId');var shopId = getParam('shopId');var authUrl = getParam('authUrl');var extend = getParam('extend');var timestamp = getParam('timestamp');var sign = getParam('sign');var weixinUrl = 'weixin://connectToFreeWifi/?apKey=_p33beta&appId='+appId+'&shopId='+shopId+'&authUrl='+authUrl+'&extend='+extend+'&timestamp='+timestamp+'&sign='+sign;	window.location=weixinUrl;
}

Parameters

Calculation of signature:

sign = MD5(appId + extend + timestamp + shop_id + authUrl + mac + ssid + secretkey);

Note: The timestamp is expressed in ms. The authUrl is an uncoded URL when being signed, such as: http://192.168.1.1/auth.html?t=abc&s=123

# Step 3: Authenticate User's Weixin Identity and Allow Access

After being invoked, Weixin automatically initiates an authentication request to the authUrl and submits the "extend" parameter. The user's Weixin identity information (tid) is passed through the merchant's homepage. Developers should get the information at the merchant backend. Example of the request sent by Weixin to the authUrl:

http://www.foo.com/portal/auth.html?extend=xxx

Parameters

The authentication server to which the authUrl points must be able to identify these parameters and return the AC authentication result to Weixin, which will inform the user of the connection result based on the HTTP response code.

If the HTTP response code is 200, the authentication is successful, and the Weixin user is redirected to the "Connection Successful" page. After tapping "Done", the user is redirected to the merchant's home page. If the authentication server needs to temporarily redirect the authentication request, return 302 and the next hop address so that Weixin initiates a request again to the next hop address (only one 302 redirection is allowed). If a code other than 200 and 302 is returned, or the number of 302 redirections exceeds the limit, the authentication fails and the Weixin user is redirected to the connection failure page.

Note: The timeout threshold of a Weixin request is 10s. Please ensure that the authentication server returns the AC authentication result (HTTP response code) within 10s after Weixin sends a request to authUrl. If the authentication server fails to return the result within 10s, the authentication is considered a failure.