API and Code Sample for RADIUS Server with External Web Portal (Omada Controller 4.1.5 or above)

Q&A of functional explanation or specification parameters
Updated 03-29-2024 14:38:03 PM FAQ view icon61758
This Article Applies to: 

 

Suitable for Omada Controller 4.1.5 or above.

 

For Omada Controller 3.1.4 to 3.2.17, please refer to FAQ2390

 

For Omada Controller 3.0.5 or below, please refer to FAQ916

 

This document outlines the requirements when establishing an external web portal server. In an Omada Controller, External Web Portal can only be used when the portal authentication type is External RADIUS Server.

 

The image below depicts the workflow among the wireless client, EAP, Omada Controller, External Web Portal, and the RADIUS Server. Its purpose is to help you better understand the requirements to establish an External Web Portal server.

 

 

1. For wireless clients & wired clients, when they are connected to the SSID of the wireless network or wired LAN network and try to access the internet, the EAP or gateway will intercept the client’s HTTP request and then redirect it to the Omada Controller. (Step 1 and Step 2)

 

2. The Omada Controller then redirects the client’s request to the external portal page by replying using an HTTP response with status code 302 Found to the client. (Step 3 and Step 4)

 

3. Client sends HTTP/HTTPS GET request to external web portal with parameter “?target=target_controller_ip&targetPort=target_controller_port&clientMac=client_mac&clientIp=client_ip&raidusServerIp=radius_server_ip&apMac=ap_mac&gatewayMac=gateway_mac&scheme=scheme&ssidName==ssid_name&radioId=radio_id(0 for 2.4G radio, 1 for 5G radio)&vid=vid&originUrl=redirecturl (if you did not assign or configure a redirect URL for clients after they complete portal authentication, the default redirect URL depends on the wireless clients).


For example:

 

https://www.externalportal.com/?target=172.30.30.113&targetPort=8088&clientMac=F8-1E-DF-AA-AA-AA&clientIP=172.30.30.103&raidusServerIp=172.30.30.120&apMac=AC-84-C6-BB-BB-BB&GatewayMac=172.30.0.1&scheme=https&ssidName=eap_test&radioId=1&originalUrl=https%3A%2F%2Fwww.tp-link.com” (Step 5)

 

4. External web portal server should be able to get the value of the clientMac, clientIp, apMac, gatewayMac, ssidName, radioId, vid, scheme, originUrl parameters. Then external web portal server should redirect the client to Controller with the information of username, password, clientMac, clientIp, apMac, gatewayMac, ssidName, scheme, vid, radioId, originUrl. (Step 6)

 

5. Client sends HTTP/HTTPS POST packets to (http) https://target_controller_ip:targetport/portal/radius/auth (or radius/browserauth) with JSON format (or HTML form) in the HTTP message body after submitting.The default “targetport” of portal is 8843 (Step7). 

 

For the difference between radius/auth and radius/browserauth, please refer to Demo and api section.

 

Note: From Controller 5.0 and later, if the API “radius/auth” is used, the “Access-Control-Allow-Origin:URL” field should be submitted in the HTTP header to enhance security during Cross-Origin Resource Sharing (CORS). For example, if the domain name of your External Web Portal is “www.tplinkportal.com”, you need to add “Access-Control-Allow-Origin:https://www.tplinkportal.com”. Please download the demo at the end of the article for reference.

 

6. Omada Controller communicates with the RADIUS server to verify the username and password. (Step 8 and Step 9)

 

7. If the authentication succeeds, i.e., Access-Accept is received from RADIUS server, Omada Controller will redirect a built-in success page or a predefined webpage according to the configuration of clients. (Step 10)

 

Demo and api:

 

From 4.1.5 to 5.1.0, we provide api: target_controller_ip:targetport/portal/radius/auth with JSON format submitting,

 

The below html template is a simple demo for you to develop your External Web Portal working with Omada Controller using JSON format:

 

External Web Server Demo (JSON)

 

When HTTPS is used on the web portal side and HTTP is used on the Omada Controller side, AJAX access will cause cross domain access problems of CORS and be intercepted by the browser, so we provide HTML form submitting api as of Omada Controller 5.3.1: target_controller_ip:targetport/portal/radius/browserauth, and it realizes the page jump on the back end

 

The below html template is another demo using HTML form:

 

External Web Server Demo (HTML form)

 

Note:

 

1. If you are using Omada Cloud-Based Controller (CBC), Only HTTPS POST to the API “browserauth” with HTML form is supported for security reasons. For CBC, please use the domain of your CBC instead of “target_controller_ip:targetport” in the URL pointing to the “browserauth” API.

 

For example, for the CBC with URL in this figure, the API would be “https://aps1-omada-controller.tplinkcloud.com/portal/radius/browserauth

 

2. If your Controller (4.1.5 or above) is upgraded from Controller 3. x.x, note that we have changed some “Names“ of the parameters.

Name(V3.x)

Name(V4.x)

Type

Remark

clientMac

clientMac

string

client MAC address

clientIp

clientIp

string

client IP address

ap

apMac

string

AP MAC address(only for ap)

 

gatewayMac

string

Gateway MAC address (only for wired auth)

 

vid

integer

vid (only for wired auth)

ssid

ssidName

string

ssid name

radioId

radioId

integer

0: 2.4GHz, 1: 5GHz(only for ap)

/

authType

integer

The actual authentication type, only supports External RADIUS and Hotspot RADIUS authentication methods.

2: External RADIUS; 8: Hotspot RADIUS

redirectUrl

originUrl

string

redirectUrl

username

username

string

authentication username

password

password

string

authentication password

 

Note that apMac and gatewayMac connot exist in the same requestwhen the wired clients authenticateplease left blank the apMac

 

3. In step7, if your form has non-ASCII characters (such as the SSID name is Chinese or other languages), UTF-8 encoding must be used when sending the HTTP/HTTPS POST to the Controller.

 

4. If you choose ajax access, please note the “Access-Control-Allow-Origin:URL” field for Controller 5.0 and above.

 

5. HTML form demo and radius/browserauth api is recommended.

 

Appendix: API document of auth and browserauth

 

portal/radius/auth (since Omada Controller 4.1.5)

Basic Information

 

Path /portal/radius/auth

 

Method POST

 

Request Parameters

 

Headers

 

Parameters

Value

Required

Content-Type

application/json

Yes

Query

Parameters

Required

Description

key

Yes

AES key encrypted by RSA public key, RSA/ECB/PKCS1Padding. The first 16 bytes are the key, and the last 16 bytes are the IV.

This 32-byte key needs to be URLBase64 encoded.

Body

Parameters

Type

Required

Description

clientMac

string

Yes

client MAC address

clientIP

String

 

Client IP address

apMac

string

Yes

AP MAC address

gatewayMac

string

Yes

gateway MAC address

ssidName

string

Yes

SSID name

vid

integer

Yes

VLAN ID

radioId

integer

Yes

0: 2.4GHz 1: 5GHz

authType

integer

Yes

This entry is the realtime authentication type. Only the following two options are supported: 2: External RADIUS 8: Hotspot RADIUS

originUrl

string

 

Redirect URL

username

string

Yes

The username for authentication

password

string

Yes

The password for authentication

 

Response Parameters

 

Parameters

Type

Required

Description

errorCode

integer

Yes

Error Code

 

portal/radius/browserauth (since Omada Controller 5.3.1)

Basic Information

 

Path /portal/radius/browserauth

 

Method POST

 

Request Parameters

 

Headers

 

Parameters

Value

Required

Content-Type

application/x-www-form-urlencoded

Yes

Path parameters

Parameters

Type

Required

Description

clientMac

string

Yes

client MAC address

clientIp

String

 

Client IP address

apMac

string

Yes

AP MAC address

gatewayMac

string

Yes

gateway MAC address

ssidName

string

Yes

SSID name

vid

integer

Yes

VLAN ID

radioId

integer

Yes

0: 2.4GHz 1: 5GHz

authType

integer

Yes

This entry is the realtime authentication type. Only the following two options are supported: 2: External RADIUS 8: Hotspot RADIUS

originUrl

string

 

Redirect URL

username

string

Yes

The username for authentication

password

string

Yes

The password for authentication

 

Response Parameters

 

Parameters

Type

Required

Description

errorCode

integer

Yes

Error Code

 

Is this faq useful?

Your feedback helps improve this site.

Recommend Products

Community

TP-Link Community

Still need help? Search for answers, ask questions, and get help from TP-Link experts and other users around the world.

Visit the Community >