[功能描述]
Wiwiz Auth API是Wiwiz HotSpot Builder提供的基于Web的外部开发接口。利用它可以实现在第三方系统/用户系统进行账户认证（Web认证）后接入网络并进行简单的认证控制。

将用户系统与Wiwiz Auth API集成的过程非常简单。用户仅需了解一种Web服务器端开发语言或工具（例如，ASP，C#/VB.Net，JSP/Servlet，PHP等），并使用它根据Wiwiz Auth API的接口规范为用户系统编写一个Web程序。

如果，你已利用Wiwiz Auth API与你的系统（例如，你的网站，论坛，博客或其他系统等）进行了集成，当某个客户在你的网络中打开浏览器并访问任意的http地址时，他将会首先看到你的网络或热点的Web认证页面，即你编写的Web程序。在这个页面中，他将根据你的要求进行身份验证或登录确认等操作，并得到你的授权。之后，他才可以访问Internet。

[使用条件与要求]

1. 用户需拥有Wiwiz专业版账户。
2. 查询Wiwiz账户的User Key。（注3）
3. 在Wiwiz Web面板创建一个热点，在“认证规则设置”部分设置“认证方式”为“第三方认证(调用Wiwiz Auth API)”。设置“认证URL”为你为用户系统编写的Web程序地址。（注1）
4. 已在本地网络设备中安装并设置了Wiwiz HotSpot Builder Utility（参考Wiwiz HotSpot Builder Utility的相关安装指南）。

[调用示意图]

[调用流程说明]
(1) 网络中的客户端在浏览器中访问任意http网址，将会自动启动Web认证机制，请求会被Wiwiz服务端拦截并将浏览器页面跳转至“认证URL”（*注1）”。同时，Wiwiz服务端会通过“认证URL”向用户系统传送3个HTTP GET传入参数，tokencode，srvurl与url。参数的含义如下：

(2) 在用户系统中，根据用户系统的业务需求进行自己的账户验证/登录验证等处理。即，图中的“第1步”处理。

(3) 如在用户系统中的验证处理通过，则在用户系统的服务器端调用Wiwiz Auth API以进行预认证。即，图中的“第2步”处理。

• 调用方式为在服务器端（不是在客户端或浏览器侧）（注2）向Wiwiz服务端发起HTTP请求。请求地址为处理（1）中传入参数srvurl的值。

• 发起请求时需要设置若干参数（HTTP GET或HTTP POST参数），包括：
  

• Wiwiz服务端接收到该请求后将返回一个Http Response作为验证结果，这个结果叫做verifycode。
  如果存在错误，verifycode的值为ERRX(X代表一位数字) （*注4）。
  否则，verifycode应该是一组16位进制的数字。

(4) 然后，再次调用Wiwiz Auth API完成认证。即，图中的“第3步”处理。

• 调用方式为是在客户端/浏览器侧（*注5）向Wiwiz服务端发起一个HTTP请求。请求的地址为处理(1)中传入参数srvurl的值。

• 请求的同时需要设置以下参数（HTTP GET或HTTP POST参数），包括：
  

• 最后，认证完成。浏览器将显示认证后页面或用户指定的在参数postauth中设置的地址。
  如遇到错误则显示错误页面并显示错误代码（*注6）。

[断开连接的方法]
如果需要切断某个已认证连接，可以在服务器端向Wiwiz服务端发起HTTP请求，请求的URL为：
格式：[srvurl]?disconn=2&t=[tokencode]&userkey=[userkey]
例：http://cp.wiwiz.com/as/s/login2/?disconn=2&t=A1398E284DC&userkey=246DD22C084BB40E

Wiwiz服务端接收到该请求后返回的Http Response的含义为：

[客户端用户自主断开连接的方法]
你可能希望客户端用户自己可以主动断开已认证的Internet连接。
你只需让客户端用户在浏览器访问以下网址即可：
格式：[srvurl]?disconn=1&t=[tokencode]
例：http://cp.wiwiz.com/as/s/login2/?disconn=1&t=A1398E284DC

这个访问请求成功后，其返回结果有以下3种：

[注解]
注1：“认证URL”可在Wiwiz Web面板的“热点设置”页面中设置。它就是用户根据Wiwiz Auth API的规范为用户系统写的Web程序的地址。

注2：<重要>出于安全考虑，进行预认证发起的HTTP请求一定要在服务器端程序中进行。例如，在ASP，C#/VB.Net，JSP/Servlet，PHP代码中，而不要使用HTML与Javascript在客户端发起请求。

注3：User Key可在Wiwiz Web面板的“用户菜单”->“升级选项”->“查询User Key”中查询。

注4：错误代码及错误原因：

注5：用于完成认证所发起的HTTP请求，最简单的方式是的方式是使浏览器跳转到指定地址，可使用服务器端代码通过向浏览器发送Redirect指令进行，也可使用客户端代码进行浏览器页面地址跳转，如HTML，JavaScript。

注6：错误代码及错误原因：

本文章由 http://www.wifidog.pro/2015/03/20/wifidog%E8%AE%A4%E8%AF%81%E6%9C%8D%E5%8A%A1%E6%8E%A5%E5%8F%A3.html 整理编辑，转载请注明出处

一般，当热点用户连接至该热点并成功通过认证后，将见到一个默认的认证后页面。这个页面将提示用户一些很有用的信息，如用户的原始请求地址、剩余的连接时间、连接结束时刻、热点管理员推送来的公告信息、系统提示信息及其他一些链接等。

热点管理员也可以自行制作任何式样和内容的自定义认证后页面，以满足不同的需求。在Wiwiz Web面板中（用户菜单 >> 我的热点 >> 热点设置）设置”自定义跳转URL“或”自定义HTML“后即可。之后，当热点用户连接至该热点并成功通过认证后，将见到这个热点管理员自定义的认证后页面。

我们也提供了开发接口供热点管理员在自定义认证后页面中调用，以实现和在默认认证后页面中相同的面向热点用户的提示信息。
我们提供两种接口，一种是URL参数；另一种是Javascript函数。详细的接口说明请参考以下内容。

1. URL参数：
url – 用户的原始请求地址
et – 连接结束时刻
rm – 剩余的连接时间

2. Javascript函数：
2.1. 准备工作
注意，调用Javascript函数前，
如果采用”自定义跳转URL”，则首先需要加入以下语句：

如果采用”自定义HTML”，则首先需要加入以下语句：

2.2. 可调用函数：
2.2.1. wiwizGetEndingTime() – 返回连接结束时刻。

2.2.2. wiwizGetRemaining() – 返回剩余的连接时间(秒数)。

2.2.3. wiwizShowCountdown(d, h, m, s) – 以倒计时方式显示剩余的连接时间。
参数说明: d, h, m, s分别代表日、小时、分钟、秒的分割字符。如不指定参数则使用默认分割字符。
调用用例: wiwizShowCountdown(" days ", " hours ", " minutes ", " seconds ");

2.2.4. wiwizCountdownNotice(tm, msg) – 设置倒计时提示消息。在连接结束前tm秒显示消息文本msg。
参数说明：
tm 连接结束前的秒数
msg 代表消息文本

2.2.5. wiwizGetBulletin() – 用于显示在Wiwiz Web面板编辑热点时设置的公告信息。

2.2.6. wiwizGetDisconnectLink() – 用于获取用户自主断开已认证连接的链接地址。
返回值说明：此函数将返回一个URL。此URL只可在用户的浏览器中请求，请求后的返回Response含义如下：

Response返回结果 含义
wiwiz_user_disconnect(0) 认证连接立即切断
wiwiz_user_disconnect(1) 认证连接无法立即切断，但即将会自动切断
wiwiz_user_disconnect(2) 连接不存在或已切断

使用例:

var url = wiwizGetDisconnectLink();
var script = document.createElement('script');
script.setAttribute('src', url);
document.getElementsByTagName('head')[0].appendChild(script);
function wiwiz_user_disconnect(s) {
    switch(s) {
        case 0:
            alert("The connection will shutdown immediately.");
            break;
        case 1:
            alert("The connection will shutdown in seconds.");
            break;
        case 2:
            alert("The connection does not exist or already shut down.");
            break;
    }
}

2.3. 可重写函数：
2.3.1. 调用wiwizCountdownNotice()后，提示消息将按照默认式样显示。如果你需要定制显示的方式或式样，你可以重写一个叫做wiwizUpdateNotice(str)的函数。参数str代表消息的文本。
例如：

function wiwizUpdateNotice(str) {
    alert(str); //alert the message
}

2.3.2. 调用wiwizGetBulletin()后，公告信息将按照默认式样显示。如果你需要定制显示的方式或式样，你可以重写一个叫做 wiwizUpdateBulletin(title, content)的函数。参数title代表公告的标题，content代表公告的详细内容。
例如：

function wiwizUpdateBulletin(title, content)
    alert(title + "\n" + content); //alert the bulletin
}

2.3.3. 当接近超过流量限制时，wiwizTrafficAlert()函数将会被触发调用，你可以重写它以定制你的流量限制提示。

本文章由 http://www.wifidog.pro/2015/03/20/%E8%87%AA%E5%AE%9A%E4%B9%89wifidog%E8%AE%A4%E8%AF%81%E5%90%8E%E8%B7%B3%E8%BD%AC%E9%A1%B5%E9%9D%A2%E7%9A%84%E8%AE%BE%E7%BD%AE.html 整理编辑，转载请注明出处

GatewayID default 

GatewayInterface br0
#GatewayAddress 192.168.1.1
GatewayPort 2060

HtmlMessageFile /opt/wifidog/etc/wifidog.html


AuthServer {
    Hostname                 www.wifidog.pro (Mandatory; Default: NONE) 
    SSLAvailable             no (Optional; Default: no; Possible values: yes, no)
    SSLPort                  443 (Optional; Default: 443)
    HTTPPort                 80 (Optional; Default: 80)
    Path                     /example/ (Optional; Default: /wifidog/ Note:  The path must be both prefixed and suffixed by /.  Use a single / for server root.)
    LoginScriptPathFragment  (Optional; Default: login/? Note:  This is the script the user will be sent to for login.)
    PortalScriptPathFragment (Optional; Default: portal/? Note:  This is the script the user will be sent to after a successfull login.)
    MsgScriptPathFragment    (Optional; Default: gw_message.php? Note:  This is the script the user will be sent to upon error to read a readable message.)
    PingScriptPathFragment    (Optional; Default: ping/? Note:  This is the script the user will be sent to upon error to read a readable message.)
    AuthScriptPathFragment    (Optional; Default: auth/? Note:  This is the script the user will be sent to upon error to read a readable message.)
}

AuthServer {
    Hostname auth.wifidog.pro
    SSLAvailable yes
    Path /
}

AuthServer {
    Hostname auth2.wifidog.pro
    SSLAvailable yes
    Path /
}


Daemon 1 


HTTPDMaxConn 10 


CheckInterval 60

ClientTimeout 5


TrustedMACList 00:00:DE:AD:BE:AF,00:00:C0:1D:F0:0D


FirewallRuleSet global {

    FirewallRule block to 192.168.0.0/16
    FirewallRule block to 10.0.0.0/8
    FirewallRule allow udp to 69.90.85.0/27
    FirewallRule allow tcp port 80 to 69.90.89.205

}


FirewallRuleSet validating-users {
    FirewallRule allow to 0.0.0.0/0
}


FirewallRuleSet known-users {
    FirewallRule allow to 0.0.0.0/0
}


FirewallRuleSet unknown-users {
    FirewallRule allow udp port 53
    FirewallRule allow tcp port 53
    FirewallRule allow udp port 67
    FirewallRule allow tcp port 67
}

FirewallRuleSet locked-users {
    FirewallRule block to 0.0.0.0/0
}

本文章由http://www.wifidog.pro/2015/03/19/WifiDog%E9%85%8D%E7%BD%AE%E5%8F%82%E6%95%B0%E8%A7%86%E9%A2%91%E8%AF%A6%E8%A7%A3.html整理编辑，转载请注明出处

本文是新版的关于如何制作自定义认证页面的指南。此新版指南对制作自定义认证页面的方法做了很大的简化。认证的处理使用JavaScript进行了封装，用户无需再关心传入与传出的参数处理。同时，还支持用户使用自己的代码来自定义报错机制。

• 尽管我们不推荐，但你依然可以参考旧版的指南来制作自定义认证页面。

你需要创建类似以下样例的页面作为自定义认证页面，并请阅读下面的“要点说明”：

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Cache-Control" content="no-cache">
<!-- 必须引入AuthPageScript.js -->
<script src="http://cp.wiwiz.com/as/AuthPageScript.js"></script>
<script>
/* 回调函数。“获取验证码”按钮按下后，将自动调用此函数。可根据code值自行改写该函数。 */
function WiwizSmsVerifyMsg(code) {
    if    (code == "-1") {
        alert("手机号码不可为空!");
    } else if(code == "0") {
        alert("验证码已通过短信发送至您的手机，请注意查收。然后请在认证页面输入验证码。");
    } else if(code == "1") {
        alert("该热点不允许进行手机号码验证。如有疑问请您联系热点管理员。");
    } else if(code == "2") {
        alert("该热点不允许进行手机号码验证。如有疑问请您联系热点管理员。");
    } else if(code == "3") {
        alert("该手机号码不允许进行验证。如有疑问请您联系热点管理员。");
    } else if(code == "4") {
        alert("手机号码验证过于频繁，请稍后再试。");
    } else if(code == "5") {
        alert("该手机号码进行验证次数已超过今日上限。");
    } else if(code == "6") {
        alert("热点认证服务已暂停，不可进行手机验证。");
    } else if(code == "7") {
        alert("该热点手机验证次数已超过配额。请联系热点管理员。");
    } else if(code == "8") {
        alert("请求已超时，请刷新认证页面。");
    } else if(code == "9") {
        alert("请使用上一次通过短信接收到的验证码。");
    } else if(code == "99") {
        alert("验证短信发送失败。请检查手机号码的有效性，或联系热点管理员。");
    } else if(code == "999") {
        alert("系统异常，验证短信发送失败。请联系热点管理员。");
    } else {
        alert("系统异常。请联系热点管理员。");
    }
}
/* 回调函数。“认证”按钮按下后，如报错将自动调用此函数。可根据code值自行改写该函数。 */
function WiwizAuthPageError(code) {
    if     (code == 1) {
        alert("您无法使用此网络，除非您认同此协议条款。");
    } else if(code == 2) {
        alert("请输入用户名。");
    } else if(code == 3) {
        alert("用户名或密码错误。");
    } else if(code == 4) {
        alert("电子招待券无效。");
    } else if(code == 5) {
        alert("超过该电子招待券的最大使用人数限制。");
    } else if(code == 6) {
        alert("超过最大在线用户数。");
    } else if(code == 7) {
        alert("请输入手机号码。");
    } else if(code == 8) {
        alert("热点已停用。");
    } else if(code == 32) {
        alert("账户存在异常，暂时锁定中。");
    } else if(code == 35) {
        alert("手机验证码错误或已超时。");
    } else if(code == 36) {
        alert("该手机号码不允许进行验证。如有疑问请您联系热点管理员。");
    } else if(code == 37) {
        alert("该手机号码进行验证次数已超过今日上限。");
    } else {
        alert("未知错误。错误码："+ code);
    }
}
</script>
</head>
<body>
<form name="myform" id="myform" action="" method="post">
热点介绍文本<br>
使用协议与条款文本...... <br>
<!-- 以下各参数应根据热点的认证方式正确设置 -->
<!-- 参数: agree 代表认同协议 -->
<input name="agree" id="agree" type="checkbox" value="1"  />
<label for="agree">我认同协议</label>
<br>
<!-- 参数: username 代表用户名 -->
用户名:
<input name="username" id="username" type="text" value="" />
<br>
<!-- 参数: pswd 代表密码 -->
密码:
<input name="pswd" id="pswd" type="password" />
<br>
<!-- 参数: encrypt 代表是否对密码加密 -->
<input name="encrypt" id="encrypt" type="checkbox" value="1" checked /><label for="encrypt">加密密码</label>
<br>
<!-- 参数: voucher 代表电子招待券 -->
电子招待券:
<input name="voucher" id="voucher" type="text" />
<br>
<!-- 参数: phonenum 代表手机号码 -->
手机号码:
<input name="phonenum" id="phonenum" type="text" value="" />
<!-- 用于取得发送手机验证码短信的按钮，onclick事件必须调用WiwizSmsVerify()函数
    WiwizSmsVerify()参数说明:
    参数1(必须): 手机号码
    参数2(必须): HotSpot ID
 -->
<input type="button" value="获取验证码" onclick="WiwizSmsVerify(document.getElementById('phonenum').value, WiwizGetQueryParameter('gw_id'));" />
<br>
<!-- 参数: phonecode 代表手机验证码 -->
手机验证码:
<input name="phonecode" id="phonecode" type="text" value="" />
<br>

<!-- 参数: userstring 代表自定义追踪信息 -->
<input name="userstring" id="userstring" type="HIDDEN" value="" />

<!-- 用于开始触发认证的按钮，onclick事件必须调用WiwizStartAuth()函数 -->
<input type="button" name="login" value="   认证   " onclick="WiwizStartAuth();" />
<br>
<!-- 以下是一些非必须的可选链接 -->
<a href="#" onclick="window.open('http://cp.wiwiz.com/as/s/viewhotspot/?gw_id='+ WiwizGetQueryParameter('gw_id')); return false;">更多信息</a>
<a href="http://cp.wiwiz.com/as/s/register/" target="_blank">注册</a>
<a href="http://cp.wiwiz.com/as/s/remindpswd/" target="_blank">忘记密码?</a>
</form>
</body></html>

[要点说明]

1. 页面HTML代码中必须通过script标签引入AuthPageScript.js。如果你使用的是“自定义认证页面HTML”（而不是“自定义认证页面URL”），那么它的路径应该是”/as/AuthPageScript.js”。
2. 认证页面样式可自由定义。但用于认证的各表单域必须被包含。包含的用于认证的表单域应与设置热点时的认证规则一致。
3. “获取验证码”按钮按下时，需调用WiwizSmsVerify()函数方可发送短信。调用后，系统将会自动调用WiwizSmsVerifyMsg()回调函数。用户可根据需要对函数内容由自由重写。
4. “认证”按钮按下时，需调用WiwizStartAuth()函数方可进行认证。调用后，如有错误，系统将会自动调用WiwizAuthPageError()回调函数。用户可根据需要对函数内容由自由重写。如果没有错误，则自动调用函数WiwizBeforeAuthDone()，它也可以重写。最后，认证通过并跳转到“认证后页面”。

本文章由 http://www.wifidog.pro/2015/03/19/wifidog%E8%AE%A4%E8%AF%81%E9%A1%B5%E9%9D%A2%E5%88%B6%E4%BD%9C.html 整理编辑，转载请注明出处