외부 포털의 서버 구축 요구 사항 (Omada SDN 컨트롤러 5.0.15 이상)

Omada 컨트롤러 v4 (4.1.5 - 4.4.6)에 대해서는 FAQ 2907를 참고해 주십시오.

Omada 컨트롤러 v3에 대해서는, FAQ 2274를 참고해 주십시오.

 

Omada SDN 컨트롤러 v4와 비교하여 주요 변경 사항은 다음과 같습니다.

1. 핫스팟 로그인 및 클라이언트 정보 제출을 위해 URL에 컨트롤러 ID를 추가합니다.

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

 

참고: 굵은 기울임꼴의 키워드는 EAP 또는 게이트웨이에 의해 자동으로 채워지는 매개변수를 나타내며 외부 포털 서버에서 올바르게 식별하고 전달해야 합니다. 매개변수의 의미는 처음에 명시되어 있습니다.

 

이 문서는 External Portal Server(줄여서 Portal, 이하 포털)를 설정하기 위한 요구 사항을 간략하게 설명합니다. 아래 그림은 작동 메커니즘을 더 잘 이해하는 데 도움이 될 수 있는 네트워크 장치 간의 데이터 흐름을 보여줍니다.

1단계 및 2단계

클라이언트가 포털이 활성화된 무선 또는 유선 네트워크에 연결되어 인터넷에 액세스하려고 하면 해당 HTTP 요청이 각각 EAP 또는 게이트웨이에 의해 가로채어지고 Omada SDN 컨트롤러(줄여서 컨트롤러)로 URL에서 EAP 또는 게이트웨이에 의해 자동으로 채워지는 연결 정보와 함께 리디렉션됩니다. 

 

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.

PORTAL		외부 포털 서버의 IP 주소 또는 URL 및 포트 번호(필요한 경우)
clientMac	CLIENT_MAC	클라이언트의 MAC 주소
apMac	AP_MAC	클라이언트가 연결된 EAP의 MAC 주소
gatewayMac	GATEWAY_MAC	게이트웨이의 MAC 주소
vid	VLAN_ID	클라이언트가 연결된 유선 네트워크의 VLAN ID
ssidName	SSID_NAME	클라이언트가 연결된 SSID의 이름
radioId	RADIO_ID	클라이언트가 연결된 대역의 무선 ID; 여기서 0은 2.4G를 나타내고 1은 5G를 나타냅니다.
site	SITE_NAME	사이트명
redirectUrl	LANDING_PAGE	인증 성공 후 방문할 URL로 랜딩페이지에서 설정할 수 있습니다.
t	TIME_SINCE_EPOCH	여기서 단위는 마이크로초입니다.

 

       

 

5단계 및 6단계

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

 

7단계, 8단계 및 9단계

클라이언트는 인증 서버에 전달되고 확인될 인증 정보를 포털에 제출합니다. 그 다음 인증 서버는 인증 결과를 포털에 반환합니다.

포털이 클라이언트의 인증 정보를 얻는 방법과 포털이 인증 서버와 통신하는 방법을 사용자 고유의 요구 사항에 따라 결정할 수 있으며 이는 이 기사의 범위를 벗어납니다.

 

참고: 위의 그림에서는 포털과 인증 서버가 분리되어 있습니다. 원하는 대로 동일한 서버에 설치할 수 있습니다. 인증 방법도 귀하에게 달려 있습니다. 포털이 인증 서버의 인증 결과를 알 수 있는지 확인하십시오.

10단계 및 11단계

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

먼저 HTTP POST 요청을 보내 컨트롤러에 로그인해야 합니다. 요청의 URL은

https://CONTROLLER:PORT/CONTROLLER_ID/api/v2/hotspot/login이어야 하며 HTTP 메시지 본문에 JSON 형식의 운영자 계정 정보

"name=OPERATOR_USERNAME&password=OPERATOR_PASSWORD"를 포함해야 합니다.

여기서 계정과 암호는 컨트롤러 계정의 계정과 암호가 아니라 핫스팟 관리자 인터페이스에 추가된 운영자입니다.

      

CONTROLLER	Omada SDN 컨트롤러의 IP 주소 또는 URL
PORT	Omada SDN 컨트롤러의 컨트롤러 관리를 위한 HTTPS 포트(기본적으로 소프트웨어의 경우 8043, OC의 경우 433, 수정을 위해 설정 --- 컨트롤러 --- 액세스 구성으로 이동)
CONTROLLER_ID	Omada SDN 컨트롤러의 식별자. 컨트롤러에 액세스하면 식별자가 자동으로 URL에 추가되어 식별자를 가져옵니다. 예를 들어 컨트롤러 URL이 https://localhost:8043/abcdefghijklmnopqrstuvwxyzabcdef/인 경우 CONTROLLER_ID는 abcdefghijklmnopqrstuvwxyzabcdef입니다.
OPERATOR_USERNAME	핫스팟 운영자의 사용자 이름입니다.
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/hotspot/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("Unable to open file!");

        fwrite($myfile, $token);

        fclose($myfile);

        return $token;

    }

 

로그인 인증이 통과된다면, 컨트롤러는 HTTP 바디에서 잇따른 JSON으로 응답할 것입니다. 결과 안의 토큰은 다음 단계에서 HTTP 헤더에 추가되어야 하는 CSRF 토큰임을 참고하십시오. 

{

    "errorCode": 0,

    "msg": "Hotspot log in successfully.",

    "result": {

        "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    }

}

 

12단계 및 13단계

성공적으로 로그인한 후, 포털은 HTTP POST 방법으로 https://CONTROLLER:PORT/CONTROLLER_ID/api/v2/hotspot/extPortal/auth 으로 클라이언트 인증을 보낼 수 있습니다. 

클라이언트 정보는 JSON 형식이어야 하며 다음 매개변수를 반드시 포함해야 합니다.

EAP에서: “clientMac=CLIENT_MAC&apMac=AP_MAC&ssidName=SSID_NAME &radioId=RADIO_ID&site=SITE_NAME&time=EXPIRE_TIME&authType =4”

Gateway에서: “clientMac=CLIENT_MAC&gatewayMac=GATEWAY_MAC&vid=VLAN_ID&site=SITE_NAME&time=EXPIRE_TIME&authType =4”

 

time

EXPIRE_TIME

인증 만료 시간입니다. 여기서 단위는 마이크로초입니다.

 

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/hotspot/login");

        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("Unable to open file!");

        $token = fgets($myfile);

        fclose($myfile);

        return $token;

    }

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

{

    "errorCode": 0

}

 

참고: 포털은 다음 두 개의 요구사항을 갖춰야 합니다.

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

2. 쿠키에 “TPEAP_SESSIONID”를 읽고 저장한 후, 쿠키와 함께 인증서를 보냅니다.