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 WeChat 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 WeChat 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 WeChat 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 WeChat 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 WeChat".

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 WeChat plug-in of the WeChat Official Accounts Platform, open Device Management > Add Device, and select Add Wi-Fi via WeChat + 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 WeChat JSAPI in the portal page to give the original Wi-Fi portal page the ability to invoke WeChat:

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

Call the JSAPI to invoke WeChat:

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

Parameter Required Description
appId Yes Merchant's Official Accounts Platform ID
extend Yes The "extend" parameter can contain the relevant parameter set required by the developer to pass to the ISP's authentication URL. This parameter only supports English letters and numbers, with a length not longer than 300 characters.
timestamp Yes Timestamp expressed in ms
sign Yes Signature of request parameters. The calculation method of the signature is described below.
shopId Yes ID of the store where the AP device resides
authUrl Yes Authentication server URL. WeChat submits user's WeChat identity information to this URL for authentication so that the user's access is allowed.*
mac Required for Android devices. User phone's MAC address, which consists of 17 characters separated with colons (all letters are lower case), such as 00:1f:7a:ad:5c:a8
ssid Yes AP device's wireless network ID

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 WeChat 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 WeChat 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 WeChat 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 WeChat 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 WeChat. In this case, see the solutions in FAQ.

Step 4: Authenticate User's WeChat Identity and Allow Access

After being invoked, WeChat automatically initiates a request to the authUrl (input parameter of JSAPI) to submit the user's WeChat 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

Parameter Description
extend This is the "extend" parameter passed when the JSAPI for invoking WeChat is called. It is passed to the merchant's home page as it is.
openId User's WeChat openId
tid Encrypted phone number of user (only for the filing by the CyberWatch authority)

The authentication server to which the authUrl points must be able to identify these parameters and return the AC authentication result to WeChat, 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 WeChat 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 WeChat 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 WeChat user is redirected to the connection failure page.

Note: The timeout threshold of a WeChat request is 10s. Please ensure that the authentication server returns the AC authentication result (HTTP response code) within 10s after WeChat 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 WeChat, 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
Parameter Description
authUrl The "authUrl" entered in the portal page in Step 2. It is the authentication server URL. WeChat submits user's WeChat identity information to this URL for authentication so that the user's access is allowed.
extend This is the "extend" parameter passed when the JSAPI for invoking WeChat is called. It is passed to the merchant's home page as it is.

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

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 WeChat 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 ");			
}
...

WeChat 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 WeChat, tap the button in the upper right corner and select Open in Browser, instead of directly opening it in the WeChat browser.

FAQ

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

WeChat 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 WeChat version is 6.2.5 or above on Android devices;
2. When WeChat cannot be invoked automatically, a message appears automatically to prompt the user to switch to WeChat manually (refer to the JSAPI in the Demo);
3.When calling the WeChat 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 WeChat?

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 WeChat authentication is successful, the user is redirected from the portal page to WeChat. 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 WeChat 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 WeChat backend. In this case, offline authentication can be used. Connect the mobile device to the Wi-Fi network via WeChat 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 WeChat offline so that the original portal page is able to invoke WeChat. 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

Parameter Required Description
appId Yes Merchant's Official Accounts Platform ID
shopId Yes ID of the store (the store registered with the Official Accounts Platform) where the AP device resides
authUrl Yes The authentication server URL. WeChat submits the user's WeChat identity information to this URL and passes the authentication so that the user's access is allowed. The authUrl is a URL-encoded value, such as: http%3A%2F%2F192.168.1.1%2Fauth.html%3Ft%3Dabc%26s%3D123
extend Yes The "extend" parameter can contain the relevant parameter set required by the developer to pass to the ISP's authentication URL. This parameter only supports English letters and numbers, with a length not longer than 300 characters.
timestamp Yes Timestamp expressed in ms
sign Yes Signature of request parameters. The calculation method of the signature is described below.

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 WeChat Identity and Allow Access

After being invoked, WeChat automatically initiates an authentication request to the authUrl and submits the "extend" parameter. The user's WeChat 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 WeChat to the authUrl:

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

Parameters

Parameter Description
extend This is the "extend" parameter passed when the JSAPI for invoking WeChat is called. It is passed to the merchant's home page as it is.

The authentication server to which the authUrl points must be able to identify these parameters and return the AC authentication result to WeChat, 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 WeChat 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 WeChat 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 WeChat user is redirected to the connection failure page.

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