목차

목표

필수 조건

소개

설정

목적

이 가이드는 외부 포털 서버(Omada 컨트롤러 5.0.15 이상)용 API 및 코드 샘플을 제공합니다.

Omada 컨트롤러 5.0.15 이상에 적합합니다.

Omada 컨트롤러 4.1.5~4.4.6의 경우 FAQ 2907을 참조하십시오.

Omada 컨트롤러 2.6.0~3.2.17의 경우 FAQ 2274를 참조하십시오.

필수 사항

• Omada 컨트롤러(v5.0.15 이상)

소개

Omada SDN 컨트롤러 v4와 비교했을 때 주요 변경 사항은 다음과 같습니다:

1. 핫스팟 로그인 및 클라이언트 정보 전송 시 URL에 컨트롤러 ID를 추가합니다.

2. CSRF 토큰을 포함하는 HTTP 헤더를 추가합니다.

참고: 굵은 이탤릭체로 표시된 키워드는 EAP 또는 라우터가 자동으로 채우는 매개변수를 나타내며, 외부 포털 서버에서 이를 올바르게 식별하여 전달해야 합니다. 매개변수의 의미는 처음 등장하는 부분에 명시되어 있습니다.

설정

이 문서는 외부 포털 서버(이하 '포털')를 구축하기 위한 요구 사항을 설명합니다. 아래 그림은 네트워크 장치 간의 데이터 흐름을 보여 주며, 작동 메커니즘을 더 잘 이해하는 데 도움이 될 수 있습니다.

1단계 및 2단계.

클라이언트가 포털이 활성화된 무선 또는 유선 네트워크에 연결되어 인터넷에 접속하려고 시도하면, 해당 HTTP 요청은 각각 EAP 또는 라우터에 의해 차단된 후, EAP 또는 라우터가 URL에 자동으로 채워 넣은 연결 정보와 함께 Omada SDN 컨트롤러(이하 '컨트롤러')로 리디렉션됩니다.

3단계 및 4단계.

그 후, 클라이언트는 연결 정보를 포함한 HTTP GET 요청을 컨트롤러로 전송하고, 상태 코드 302가 포함된 HTTP 응답을 통해 컨트롤러의 응답에 따라 포털로 리디렉션됩니다. HTTP 응답에는 위치 필드에 포털의 URL과 연결 정보가 포함됩니다.

EAP용 URL:

http(s)://PORTAL?clientMac=CLIENT_MAC&apMac=AP_MAC&ssidName=SSID_NAME&t=TIME_SINCE_EPOCH&radioId=RADIO_ID&site=SITE_NAME&redirectUrl=LANDING_PAGE.

라우터용 URL:

http(s)://PORTAL?clientMac=CLIENT_MAC&gatewayMac=GATEWAY_MAC&vid=VLAN_ID&t=TIME_SINCE_EPOCH&site=SITE_NAME&redirectUrl=LANDING_PAGE.

다음은 Omada 컨트롤러 v6의 예시입니다.

5단계와 6단계.

클라이언트는 위의 URL을 사용하여 포털에 HTTP GET 요청을 보냅니다. 포털은 HTTP GET 요청의 쿼리 문자열에서 연결 정보를 인식하고 유지하며, 인증을 위한 웹 페이지를 반환할 수 있어야 합니다.

7, 8, 9단계.

클라이언트는 인증 정보를 포털에 제출하면, 이 정보는 인증 서버로 전달되어 검증됩니다. 그런 다음 인증 서버는 인증 결과를 포털로 반환합니다.

포털이 클라이언트의 인증 정보를 어떻게 획득하고, 포털이 인증 서버와 어떻게 통신할지는 사용자의 요구 사항에 따라 결정할 수 있으며, 이는 본 문서의 범위를 벗어납니다.

참고: 위 그림에서 포털과 인증 서버는 분리되어 있습니다. 원한다면 동일한 서버에 설치할 수도 있습니다. 인증 방법 또한 자유롭게 선택할 수 있습니다. 단, 포털이 인증 서버로부터 인증 결과를 확인할 수 있도록 해야 합니다.

10단계 및 11단계.

인증 요청이 승인되면, 포털은 API를 호출하여 클라이언트 정보를 컨트롤러로 전송해야 합니다.

먼저, HTTP POST 요청을 전송하여 컨트롤러에 로그인해야 합니다. 요청 URL은 https://CONTROLLER:PORT/CONTROLLER_ID/api/v2/핫스팟/로그인이어야 하며, HTTP 메시지 본문에 JSON 형식의 운영자 계정 정보를 포함해야 합니다: {"name": "OPERATOR_USERNAME","password": "OPERATOR_PASSWORD"}.

여기서 계정 및 비밀번호는 컨트롤러 계정의 것이 아니라, 핫스팟 매니저 인터페이스에서 운영자가 추가한 계정 및 비밀번호임을 유의하십시오.

PHP 코드 템플릿:

public static function login()

{

$loginInfo = array(

"name" => OPERATOR_USER,

"password" => OPERATOR_PASSWORD

);

$headers = array(

"Content-Type: application/json",

"Accept: application/json"

);

$ch = curl_init();

// POST

curl_setopt($ch, CURLOPT_POST, TRUE);

// 페이지로 돌아가지 않고 값을 반환하도록 설정

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// 쿠키 설정. COOKIE_FILE_PATH는 쿠키를 저장할 위치를 정의합니다.

curl_setopt($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);

curl_setopt($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);

// 자체 서명 인증서 허용

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);

// API 호출

curl_setopt($ch, CURLOPT_URL, "https://" . CONTROLLER . ":" . PORT . "/" . CONTROLLER_ID . "/api/v2/핫스팟/extPortal/auth");

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($loginInfo));

$res = curl_exec($ch);

$resObj = json_decode($res);

//CSRF 방지. TOKEN_FILE_PATH는 토큰을 저장할 위치를 정의합니다.

if ($resObj->errorCode == 0) {

// 로그인 성공

self::setCSRFToken($resObj->result->token);

}

curl_close($ch);

}

private static function setCSRFToken($token)

{

$myfile = fopen(TOKEN_FILE_PATH, "w") or die("파일을 열 수 없습니다!");

fwrite($myfile, $token);

fclose($myfile);

return $token;

}

로그인 인증이 성공하면, 컨트롤러는 HTTP 본문에 다음 JSON을 포함하여 응답합니다. result 내부의 token은 CSRF 토큰이며, 이는 다음 단계의 HTTP 헤더에 추가되어야 합니다.

{

"errorCode": 0,

"msg": "핫스팟 로그인 성공.",

"result": {

"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

}

}

12단계 및 13단계.

성공적으로 로그인한 후, 포털은 HTTP POST 메서드를 사용하여 클라이언트 인증 결과를 https://CONTROLLER:PORT/CONTROLLER_ID/api/v2/핫스팟/extPortal/auth로 전송할 수 있습니다.

클라이언트 정보는 HTTP 메시지 본문에 JSON 형식으로 포함되어야 하며, 다음 매개 변수를 반드시 포함해야 합니다.

EAP의 경우: {"clientMac":"CLIENT_MAC","apMac":"AP_MAC","ssidName":"SSID_NAME","radioId":"RADIO_ID","site":"SITE_NAME","time":"EXPIRE_TIME","authType":"4"}

라우터의 경우:

{"clientMac":"CLIENT_MAC","gatewayMac":"GATEWAY_MAC","vid":"VLAN_ID","site":"SITE_NAME","time":"EXPIRE_TIME","authType":"4"}

EAP용 PHP 코드 템플릿:

public static function authorize($clientMac, $apMac, $ssidName, $radioId, $milliseconds)

{

// 사용자에게 인증 요청 및 허용 시간을 전송

$authInfo = array(

'clientMac' => $clientMac,

'apMac' => $apMac,

'ssidName' => $ssidName,

'radioId' => $radioId,

'time' => $milliseconds,

'authType' => 4

);

$csrfToken = self::getCSRFToken();

$headers = array(

'Content-Type: application/json',

'Accept: application/json',

'Csrf-Token: ' . $csrfToken

);

$ch = curl_init();

// POST

curl_setopt($ch, CURLOPT_POST, TRUE);

// 페이지로 돌아가지 않고 값을 반환하도록 설정

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// 쿠키 설정.

curl_setopt($ch, CURLOPT_COOKIEJAR, COOKIE_FILE_PATH);

curl_setopt($ch, CURLOPT_COOKIEFILE, COOKIE_FILE_PATH);

// 자체 서명 인증서 허용

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);

// API 호출

curl_setopt($ch, CURLOPT_URL, "https://" . CONTROLLER . ":" . PORT . "/" . CONTROLLER_ID . "/api/v2/핫스팟/로그인");

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($authInfo));

curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$res = curl_exec($ch);

echo $res;

$resObj = json_decode($res);

if ($resObj->errorCode == 0) {

// 인증 성공

}

curl_close($ch);

}

public static function getCSRFToken()

{

$myfile = fopen(TOKEN_FILE_PATH, "r") or die("파일을 열 수 없습니다!");

$token = fgets($myfile);

fclose($myfile);

return $token;

}

인증 요청이 승인되면 컨트롤러는 다음 JSON으로 응답합니다:

{

"errorCode": 0

}

참고: 포털은 다음 두 가지 요구 사항을 충족해야 합니다:

1. 자체 서명된 인증서를 허용해야 합니다. 그렇지 않으면 컨트롤러에 자체 HTTPS 인증서를 업로드해야 합니다.

2. 쿠키에서 “TPEAP_SESSIONID”를 읽고 저장한 후, 해당 쿠키와 함께 인증 요청을 전송해야 합니다.

* 컨트롤러 v5.11 이상 버전의 경우, 쿠키 이름은 “TPOMADA_SESSIONID”입니다.

각 기능 및 설정에 대한 자세한 내용은 다운로드 센터에서 해당 제품 설명서를 다운로드하여 확인하시기 바랍니다.

이 문서에는 기계 번역이 적용되었으며, 정확한 내용을 확인하려면 원본 영문 문서를 참고하시기 바랍니다.