This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
| user_guide:chilli:coova_json [2021/02/04 05:40] – created admin | user_guide:chilli:coova_json [2021/02/04 09:07] (current) – [logoff] admin | ||
|---|---|---|---|
| Line 4: | Line 4: | ||
| * This document will discuss the technical workings of the JSON interface. | * This document will discuss the technical workings of the JSON interface. | ||
| * In order to have access to the JSON interface you have to be on the same network served by CoovaChilli, | * In order to have access to the JSON interface you have to be on the same network served by CoovaChilli, | ||
| + | |||
| + | ===== Accessing the JSON interface ===== | ||
| + | * The JSON interface is served from the UAMLISTEN IP Address which is typically 10.1.0.1 | ||
| + | * It has a standard interface (HTTP) on UAMPORT which is typicallly 3990 | ||
| + | * If Coova is configured to also support HTTPS in the UAM, the HTTPS access will be on the UAMUIPORT which is typically port 4990. | ||
| + | * Each of the endpoints can then be reached by appending **/json/** and the end point name . | ||
| + | * For HTTP a typical URL will look like this | ||
| + | * **status** http:// | ||
| + | * **logon** | ||
| + | * **logoff** | ||
| + | * For HTTPS a typical URL will look like this | ||
| + | * **status** https:// | ||
| + | * **logon** | ||
| + | * **logoff** | ||
| + | |||
| + | ==== Specifying a Callback ==== | ||
| + | * In order to allow cross site functionality the JSON interface also allows for you to include a value for the **callback** | ||
| + | * Simply include **callback** and the required value for it in the query string of the endpoint call. | ||
| + | * http:// | ||
| + | * The reply will then be wrapped inside the value of **callback** | ||
| + | <code javascript> | ||
| + | jQuery33105641008201093548_1612410177983({" | ||
| + | </ | ||
| + | |||
| + | |||
| + | |||
| ===== The JSON interface methods ===== | ===== The JSON interface methods ===== | ||
| * The JSON interface has three endpoints exposed. They are | * The JSON interface has three endpoints exposed. They are | ||
| * **status** Report on the current status of the client from which you are making the call | * **status** Report on the current status of the client from which you are making the call | ||
| - | | + | |
| - | * **logoff** Used to disconnect a user that has an active session on the captive portal. | + | * **logoff** Used to disconnect a user that has an active session on the captive portal. |
| We will now unpack each of these endpoints in their own dedicated session | We will now unpack each of these endpoints in their own dedicated session | ||
| ==== status ==== | ==== status ==== | ||
| + | * The reply of a status call will indicate the current connection status of a client / user from where the call was made. | ||
| + | * Here is a typical reply when the user is not connected | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | * Here is a typical reply when the user is connected | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | * The item that indicates if there is an active session is the value of **ClientState** | ||
| + | * **0** No active session | ||
| + | * **1** Active session | ||
| + | |||
| ==== logon ==== | ==== logon ==== | ||
| + | * The logon process consists of three calls | ||
| + | * Doing a status call to get the latest challenge from the status reply | ||
| + | * Doing a call the the UAM encryption service on the RADIUSdesk back-end by calling the uam.php script. | ||
| + | * Using the returned hash value together with the username to to a call to the JSON login end-point. | ||
| + | |||
| + | === Get the latest challenge === | ||
| + | * Each time we do a call to the **status** end point we get a new challenge in the reply. | ||
| + | * CoovaChilli remembers the last challenge it generated for a client (when they are not logged in) and uses that during the login process. | ||
| + | * This is why its good practice to do a **status** call as step one of the login process to get a fresh challenge from CoovaChilli. (There is an expiry on the challenge which is why we go this route to ensure we have a current value that has not expired yet) | ||
| + | * The call to the status end point was already covered earlier in the document. From it you can see there is a **challenge** item. | ||
| + | |||
| + | === Encrypt the Challenge and Password === | ||
| + | * RADIUSdesk includes a UAM service that takes the challenge, the user's password along with a common uam secret to generate a encrypred value that it uses on the logon end point to authenticate the user. | ||
| + | * Here is a sample call that you can use as reference | ||
| + | * http:// | ||
| + | * And here is the result | ||
| + | <code javascript> | ||
| + | jQuery331012987580313312852_1612418453858( | ||
| + | { | ||
| + | ' | ||
| + | } | ||
| + | ) | ||
| + | </ | ||
| + | |||
| + | <WRAP center round tip 90%> | ||
| + | * You will replace **hotspot.radiusdesk.com** with the FQDN or IP Address of your own server | ||
| + | </ | ||
| + | |||
| + | === Call the logon JSON endpoint === | ||
| + | * We can now use the response as the value of **password** when we do the logon JSON call | ||
| + | * http:// | ||
| + | * Alternative format | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | * And here's the response of a successful logon | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | |||
| + | ==== logoff ==== | ||
| + | * The last JSON end point is **logoff** | ||
| + | * Here is the call and the results | ||
| + | * http:// | ||
| + | * Alternative | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | * Repsonse | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | * As you can see the reply is pretty much the same than logon but the **clientstate** is now **0** meaning it logged off fine. | ||
| + | |||
| - | ==== llogoff ==== | ||