Wi-Fi hardware authentication protocol interface description

Wi-Fi Hardware Authentication Protocol Interface Description

##Overview

Hardware authentication protocol is mainly used The authentication method of Portal-type devices has been modified so that the device can identify customers through WeChat identity, allowing customers' mobile phones and PCs to quickly and easily connect to Wi-Fi.

Business logic

##Mobile terminal connected to Wi-Fi

User connection process

Customers click on the SSID on their mobile phone to bring up the portal page, click the "WeChat Connect Wi-Fi" button on the page to enter the pre-connection page. Display the logo and name of the official account, click the "Connect Now" button and start connecting to WiFi. After the connection is successful, jump to the successful connection page and follow the merchant's official account.

Module timing diagram

If you cannot see the text in the picture clearly, you can first save the picture locally through "Save Picture As" and then enlarge it to view.

##PC connected to Wi-Fi

User connected to the Internet Process

After the customer selects the SSID on the PC, open the portal page in the browser, and the Wi-Fi QR code is displayed on the page. Use WeChat on your mobile phone to scan the QR code, click the "Confirm" button on the mobile phone page, connect your PC to Wi-Fi, and the browser's portal page will automatically jump to the webpage configured by the merchant.

Module timing diagram

If you cannot see the text in the picture clearly, you can first save the picture locally through "Save Picture As" and then enlarge it to view it.

Mobile terminal implementation process

Please follow the steps below to complete the equipment transformation and let Mobile devices use WeChat to connect to Wi-Fi.

The first step: Obtain the store Wi-Fi information

The first step to transform portal-type equipment is Obtain store Wi-Fi information, including: appId, shop_id, ssid, secretkey. There are two ways to obtain store Wi-Fi information:

1. Obtain through page operations

In the WeChat public platformWeChat Wi-Fi plug-in, open [Device Management]->[Add Device], add "Add near-field service after connecting to the Internet via WeChat" -> "Portal type device"; after successful addition, you can obtain the store Wi-Fi parameter information.

For added devices, you can also obtain store Wi-Fi parameter information in [Device Details]->[View Device Modification Information].

2. Call the interface to obtain

Call "Add portal device"Interface to obtain.

Step 2: Transform the mobile portal page

If the connected device is a mobile device, Reference the following WeChat JSAPI in the portal page so that the original Wi-Fi portal page has the ability to call WeChat:

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

Call JSAPI to trigger the WeChat client:

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

Specific 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');

Parameter description

##authUrl is the authentication server URL. The WeChat client will submit the user's WeChat identity information to this URL and obtain authentication releasemacRequired for Android devicesThe mac address of the user's mobile phone, the format is colon-separated, the character length is 17, and the letters are lowercase, for example: 00:1f :7a:ad:5c:a8##ssid

Signature calculation method:

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

Note: The timestamp here is the current timestamp in milliseconds.

Step 3: Support temporary release of Internet access requests

Please ensure that the AP/AC is on the portal page After opening, the user's Internet access request can be temporarily released. Only when the temporary release is successful can the above-mentioned JSAPI be called to call WeChat in exchange for user identity information to ensure that subsequent authentication requests are successfully completed and the network is successfully connected.

Note: When IOS calls WeChat, if the network is unavailable, Wi-Fi will be cut off, resulting in network failure. Therefore, please be sure that the AC/AP supports temporary release of Internet access requests.

The web browser of some Android devices cannot automatically launch the WeChat client. Please refer to the solution in the FAQ.

Step 4: Accept WeChat identity authentication and release

After the WeChat client is called up, it will automatically send a request to authUrl (JSAPI Incoming parameters) initiate a request and submit the user WeChat identity information parameters required for authentication, including extend, openId, and tid.

Example of WeChat client sending request to authUrl:

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

Parameter description

Parameter	Is it necessary	Description
appId	Yes	Merchant WeChat public platform account
extend	is	extend can contain a collection of relevant parameters that developers need, which will eventually be transparently transmitted to the operator's authentication URL. The extend parameter only supports English and numbers, and the length must not exceed 300 characters.
timestamp	Yes	Time stamp in milliseconds
sign	Yes	Request parameter signature, the specific calculation method is explained below
shopId	is the ID of the store where the	AP device is located, that is shop_id


is the wireless network name of the	AP device

Parameters	Description
extend	is passed when calling the WeChat JSAPI above The extend parameter is returned to the merchant homepage as it is
openId	The user’s WeChat openId
tid	is the encrypted mobile phone number of the user (only used for filing by the network supervision department)

The background authentication server corresponding to authUrl must be able to identify these parameter information and return the AC authentication result to the WeChat client. The WeChat client will prompt the user whether the connection is successful or not based on the http return code.

If the http return code is 200, the service authentication is considered successful, and the WeChat client jumps to the successful connection page. After the user clicks the "Finish" button, it will jump to the merchant's homepage; if the authentication server needs to transfer authentication request, please return 302 and the next hop address. The WeChat client will initiate another request to the next hop address. The 302 jump is only supported once; for non-200 and 302, or 302 return codes that exceed the number of times, it is regarded as authentication failure. , the connection failed this time, and the WeChat client jumped to the connection failure page.

Note: The waiting time for a WeChat client request is 10s. Please ensure that the background authentication server returns the AC authentication result, that is, the http return code, within 10s after the WeChat client sends a request to authUrl. Failure to return an authentication result for more than 10 seconds will be considered an authentication failure.

Step 5: Scan the QR code to connect to the Internet

After completing the first to fourth steps Next, perform the following configuration to enable the portal device to scan the QR code to connect to Wi-Fi. The specific operations are as follows:

1. Modify the portal server jump content

When an unauthenticated mobile phone user tries to connect to the Internet, AC will forward the user's http request to the Portal page on the Portal Server. Here AC needs to further identify. If the http request comes from the WeChat client, then in Just put the two agreed parameters authUrl and extend on the jump URL.

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

Parameters	Description
authUrl	That is, in the second step portal page The filled in authUrl is the authentication server URL. The WeChat client will submit the user's WeChat identity information to this URL and obtain authentication and release
extend	is called above The extend parameter passed when calling WeChat JSAPI is returned to the merchant homepage as it is

2. How to identify whether the http request comes from the WeChat client

Just parse "User-Agent" in the header structure of the http packet and determine whether it contains the keyword "micromessenger" (Please be careful not to intercept other WeChat http requests here, so please match the keywords). The sample code is as follows:

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

The WeChat client will parse the authUrl in the Portal Server jump address and extend parameters to continue completing the connection process.

3. Prevent IOS from automatically popping up the portal page

In order to prevent IOS from automatically popping up the portal page when switching SSIDs, please change the sniffing address of IOS to "http://captive.apple.com/hotspot-detect.html”Put it into the whitelist.

4. Download the material QR code

After completing the portal server transformation, call the "Get the material QR code" interface, Download the QR code of the store and post it in the store. Customers can scan the code to connect to Wi-Fi.

Mobile Portal Page Example Demo

Please refer to the example Demo to transform the mobile Portal page (JS code is directly on the page Medium)

Please use mobile browser to open the following link (you can enter it manually or scan the QR code to get the link address):

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

If you use WeChat to scan the code, please click the button in the upper right corner and select "Open in browser" ” page, do not experience it directly in the WeChat browser.

FAQ

1. The web browser of some Android phones cannot automatically call up the WeChat client

WeChat for Android version 6.2.5 or above already supports the function of manually opening the client and continuing the connection process. To ensure that this process proceeds smoothly, developers should pay attention to the following points:

1.保证微信客户端版本为6.2.5以上的Android版微信；
2.参考示例demo中jsapi的写法，在无法自动跳转微信客户端时弹出提示，让用户手动切换到微信；
3.在portal页面中调用微信jsapi时，需保证AP设备的ssid和手机mac这2个参数真实有效；
4.测试过程请从切换到目标ssid动作开始（例如：原来为3G或4G网络然后手动选择目标ssid，原来为非目标ssid的wifi信号然后手动选择目标ssid，等等）。

2. How to ensure that the phone remains under the target SSID after IOS jumps from the portal page to WeChat?

In order to ensure that Wi-Fi is available, the IOS system will not switch to an SSID immediately after the user selects it. Instead, it will sniff whether the SSID can reach the default on the public network. Service, if it can be sniffed, it will actually show the connection to the ssid. In the AP environment where the portal pops up, this is used to pop up the portal page. If the authentication is completed on the portal page, the prompt in the upper right corner of the portal will change from "Cancel" to "Complete". If you leave this interface in the "Complete" state, the SSID you just selected will be disconnected and return to the previous available connection. However, if you leave this interface in the "Complete" state, it will not be disconnected.

Since when passing WeChat authentication, the portal interface will jump to WeChat, it is a prerequisite to ensure the "Complete" status in the upper right corner of the portal. Developers need to pay attention to the following points:

1.确保弹出portal后，临时放行手机的所有流量；
2.临时放行手机的所有流量后，局部或整体刷新portal页面触发IOS再次进行嗅探；
3.IOS嗅探可以正常触达公网上的预设服务后“取消”变为“完成”；
4.以上动作完成后，再调用跳转微信的JSAPI，继而跳转微信完成认证连接流程。

##PC side implementation process

Please follow the steps below to Use WeChat to connect to Wi-Fi on PC.

The first step: Obtain the store Wi-Fi information

The first step to connect the PC to Wi-Fi , is to obtain the store Wi-Fi information, including: appId, shop_id. There are two ways to obtain store Wi-Fi information:

1. Obtain the page operation

Open WeChat Wi-Fi on the

WeChat public platform Fi plug-in, in [Device Management]->[Add Device], add "New WeChat-based near-field service after connecting to the Internet"->"Portal type device"; after successful addition, you can get the store Wi-Fi Fi parameter information.

Added devices can also obtain store Wi-Fi parameter information in [Device Details]->[View Device Modification Information].

2. Obtain through the interface

Call "Get WiFi store list"Interface to obtain the shop_id, which is the ID of the store to which the device is to be added.

Step 2: Modify the PC portal page

If the connected device is a PC, in the portal page Quoting the following WeChat JSAPI, the original Wi-Fi portal page has the ability to call WeChat:

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

Call JSAPI to generate a QR code. The specific example code is as follows:

 <script type="text/javascript">
	    JSAPI.auth({
	    	target : document.getElementById('qrcode_zone'),
	        appId : 'wx23fb4aaf04b8491e',
	        shopId : 6747662,
	        extend : 'wechatpc',
	        authUrl : 'http://wximg.qq.com/tmt/wifi-landing-pc/dist/html/index-success.html'
	    });
</script>

Parameter Description

Parameter	Is it necessary	Description
target	Yes	QR code image placement location
appId	is the	merchant WeChat public platform account
shopId	is	which is shop_id, the ID of the store where the device is located (WeChat public platform store)
extend	Yes	extend can contain the relevant parameter set required by the developer, which will eventually be transparently transmitted to the operator's authentication URL. The extend parameter only supports English and numbers, and the length must not exceed 300 characters.
authUrl	is the	authentication server URL. The WeChat client will submit the user’s WeChat identity information to this URL and obtain authentication release

##Step 3: Support PC side whitelist release

AP/AC required Whitelist the PC to allow the portal page to reference jsapi, and poll the WeChat backend to obtain openid and tid.

Please whitelist support for the URL of WeChat connecting to Wi-Fi. The URL is:

https://wifi.weixin.qq.com/

to support:

1. Quote jsapi:

https://wifi.weixin.qq.com/resources/js/wechatticket/pcauth.js

2. Poll the WeChat background to obtain openid and tid:

https://wifi.weixin.qq.com/cgi-bin/pollpcresult

Step 4: Support the mobile terminal to temporarily release Internet requests

Please refer to the third step of the mobile terminal implementation process. Supports temporary release of Internet access requests on mobile terminals.

Step 5: Accept WeChat identity authentication and release

Please refer to the fourth step of the mobile terminal implementation process. Accept WeChat identity verification and release.

PC Portal Page Example Demo

Please refer to the example Demo to modify the PC Portal page (JS code directly in the page):

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

Offline authentication method

The Wi-Fi environment cannot temporarily release user traffic for communication with the WeChat backend, so offline authentication can be used. Please follow the steps below to use WeChat to connect to Wi-Fi on your mobile device.

Module timing diagram

If you cannot see the text in the picture clearly, you can first save the picture as Save the picture locally and then zoom in to view

Step one: Obtain store Wi-Fi information

Please refer to the mobile terminal implementation process The first step is to obtain the store’s Wi-Fi information.

Step 2: Transform the mobile portal page

Quote the link to call WeChat offline in the portal page, so that the original Wi-Fi portal page has the ability to call the WeChat client. 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;
}

Parameter description

##extend is

Parameter	Is it necessary	Description
appId	Yes	Merchant WeChat public platform account
shopId	is	, which is shop_id, the ID of the store where the device is located (WeChat public platform store)
authUrl	is the	authentication server URL. The WeChat client will submit the user's WeChat identity information to this URL and obtain authentication release. The value of authUrl is Url encoded, such as: http://192.168.1.1/auth.html?t=abc&s=123
		extend, which can contain the relevant parameter set required by the developer, and will eventually be transparently transmitted to the operator's authentication URL. The extend parameter only supports English and numbers, and the length must not exceed 300 characters.
timestamp	Yes	Time stamp in milliseconds
sign	Yes	Request parameter signature, please see the description below for the specific calculation method

Signature calculation method:

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

Note: Here timestamp is the current timestamp in milliseconds. authUrl is an unencoded URL format when signing, such as: http://192.168.1.1/auth.html?t=abc&s=123

##Step 3: Support WeChat identity authentication release

WeChat client is blocked After the call is made, an authentication request will be automatically initiated to authUrl and the extend parameter will be submitted. The user's WeChat identity (tid parameter) will be passed through the merchant's homepage. Developers should pay attention to obtaining it in the background of the merchant's homepage. Example of WeChat client sending request to authUrl:

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

Parameter Description

Parameters	Description
extend	is passed when calling the WeChat JSAPI above extend parameter, here it is returned to the merchant homepage as it is

The background authentication server corresponding to the authUrl must be able to identify these parameter information and return the AC authentication result to the WeChat client. WeChat The client will prompt the user whether the connection is successful or not based on the http return code.

Wi-Fi hardware authentication protocol interface description