방법: 권한 부여(애플리케이션)

소개

이 가이드에서는 Frame.io 프로젝트에서 C2C 애플리케이션을 인증하고 권한을 부여하는 방법을 알아봅니다.

무엇이 필요할까요?

C2C 구현: 설정 가이드를 읽지 않으셨다면, 다음으로 넘어가기 전에 빠르게 살펴보세요! 또한 연동 시스템을 식별하는 데 사용될 client_id를 저희 팀으로부터 발급받으셨을 것입니다. client_id를 받지 못하셨다면 이 C2C 에코시스템 소개를 확인하시고 저희 팀에 문의해 주세요. client_id 대신 client_secret을 받으신 경우, C2C 애플리케이션이 아닌 하드웨어 디바이스로 설정된 것이므로 하드웨어 디바이스 권한 부여 가이드를 따르거나 저희 팀에 문의하여 client_id를 대신 발급받으셔야 합니다.

애플리케이션 권한 부여 흐름 살펴보기

구현하고자 하는 권한 부여 흐름에 대해 예상되는 사용자 경험을 전반적으로 이해하고 있어야 합니다. 다음 리소스를 확인하여 사용자 관점에서 이 흐름을 살펴보고, Zoelog를 다운로드한 후 Frame.io에 로그인하여 C2C 애플리케이션의 권한 부여 프로세스를 직접 경험해 보세요!

OAuth 개요

C2C 애플리케이션은 인증 및 권한 부여를 위해 OAuth 2.0 흐름을 사용합니다. 이는 타사 애플리케이션이나 사용자를 서비스에 대해 인증하고 권한을 부여하는 데 사용할 수 있는 표준화된 호출 세트입니다. OAuth 흐름에 대한 자세한 내용은 여기에서 확인할 수 있습니다.

콜백/리디렉션 URI

OAuth 흐름의 일환으로 저희 서버는 귀하가 제어하는 URI/URL로 HTTP 호출을 수행해야 합니다. 사용자가 브라우저에서 Frame.io에 로그인한 후, 이 URI로 브라우저를 리디렉션하여 귀하의 앱에 몇 가지 정보를 제공합니다. 리디렉션 URI는 다음 조건을 충족해야 합니다.

• 귀하의 소유일 것
• 고정

이 두 가지 기준을 충족하는 한 디바이스에 대해 둘 이상의 유효한 리디렉션을 등록할 수 있습니다.

OAuth 흐름을 진행하는 동안 귀하의 애플리케이션이 요청하는 콜백 URI가 저희가 보관하고 있는 URI 중 하나인지 확인합니다. 일치하지 않으면 권한 부여 흐름이 실패합니다. 이 확인 과정을 거치지 않으면 악의적인 사용자가 자신이 제어하는 주소로 리디렉션을 제공할 수 있습니다.

개발 목적으로 http://localhost에서 HTTPS가 아닌 콜백을 지원합니다.

디바이스 식별

Camera to Cloud에 연결할 때 사용자의 프로젝트에 디바이스 연결을 나열할 수 있도록 각 개별 앱 설치를 고유하게 식별해야 합니다.

C2C 애플리케이션의 경우 이를 디바이스의 device_id라고 합니다. 구현을 설정할 때 이 작업을 어떻게 수행할지 고려해야 합니다. 일부 플랫폼은 바로 이 사용 사례에 맞춰 디바이스 및 앱에 한정된 식별자를 생성하는 API를 제공합니다.

어떤 값을 사용해야 할지 잘 모르겠다면 함께 상의하여 연동을 최대한 간소화할 수 있는 적절한 값을 선택하도록 도와드릴 수 있습니다.

1단계: 사용자 인증

*YourApp™*에서 Frame.io에 연결하기로 결정하면 Frame.io 구성 섹션으로 이동하여 “프로젝트에 연결”(또는 유사한 항목)을 선택합니다. 버튼을 누르면 Frame.io로 리디렉션되어 로그인하고 앱에 권한을 부여하게 됩니다.

이 작업은 URL을 구성하여 웹 브라우저에서 여는 방식으로 이루어집니다. Python 형태의 의사 코드를 살펴보겠습니다.

1
def redirect_to_auth(config):
2
    credentials = {
3
        "response_type": "code",
4
        "redirect_uri": "http://MyApp.io/frameio-callback",
5
        "client_id": f"{MYAPP.client_id}",
6
        "scope": "offline device.connect asset.create",
7
        "state": str(uuid.uuid4()),
8
        "device_id": f"{HARDWARE.get_vendor_id('com.mycompany.myapp')}",
9
    }
10
11
    encoded = parse.urlencode(credentials)
12
    url = "https://applications.frame.io/oauth2/auth?" + encoded
13
14
    webbrowser.open(url)

“페이로드”는 URL 자체에 인코딩되며, 완전히 인코딩된 URL은 다음과 같은 형태가 됩니다.

https://applications.frame.io/oauth2/auth?response_type=code&redirect_uri=http%3A%2F%2FMyApp.io%2Fframeio-callback&client_id=[client_id]&scope=offline+device.connect+asset.create&state=[state]&device_id=62f88d2a-1ae1-45e7-a6a0-81954e0cf2ff

이러한 옵션을 조금 더 자세히 살펴보겠습니다.

response_type: OAuth 흐름이 응답해야 하는 형식입니다. 이 값은 항상 “code”여야 합니다. 이는 OAuth 서버에 리디렉션 URI로 코드를 다시 보내도록 지시하며, 이후 해당 코드는 실제 권한 부여 토큰을 가져오는 데 사용됩니다. redirect_uri: 권한 부여 요청에 응답할 때 OAuth 서버가 GET 요청을 보내야 하는 URL/URI입니다. client_id: 앱을 식별합니다. 애플리케이션 연동의 경우 이 값은 Frame.io에서 제공합니다. scope: 앱이 요청하는 권한 목록으로, 공백으로 구분됩니다. C2C 애플리케이션에서 사용할 수 있는 권한은 다음과 같습니다.

• offline: 초기 토큰이 만료되었을 때 앱이 자체적으로 권한 부여를 새로 고칠 수 있습니다.
• device.connect: 사용자가 C2C 연결을 수행할 수 있는 계정 및 프로젝트 목록을 디바이스에서 가져올 수 있습니다.
• asset.create: 앱이 연결된 프로젝트에 에셋을 업로드할 수 있습니다.

이러한 권한 중 일부만 요청하고 승인받는 것도 가능하지만, 항상 세 가지를 모두 요청하는 것이 좋습니다.

state: 이 요청과 연결된 임의의 값입니다. 저희는 state를 사용하여 리디렉션 URI에 대한 호출이 유효한 요청인지 확인합니다. 등록된 URI에서 콜백을 수신하면 예상되는 state인지 확인해야 합니다.

device_id: 이 특정 디바이스/설치에 대한 고유 식별자입니다. 디바이스 ID는 귀하가 제어할 수 있는 값이어야 하며(따라서 MAC 주소, CPU 일련번호 등은 안 됨), 개인 식별 정보를 포함하지 않아야 합니다(따라서 이메일 주소, 주민등록번호, 지문 해시 등은 안 됨). 자세한 내용은 위의 device_id 섹션을 참조하세요.

2단계: OAuth 응답 수신

사용자가 브라우저에서 Frame.io에 로그인하고 요청된 권한(scope)을 수락하면 콜백 URI로 GET 요청이 전송됩니다. 이 요청에는 다음 쿼리 매개변수가 포함된 URL 인코딩 페이로드가 포함됩니다. code: Frame.io 백엔드에서 실제 권한 부여 토큰을 가져오는 데 사용될 코드입니다. state: 1단계의 원래 인증 요청에 포함되었던 state 값입니다. scope: 승인된 권한/범위입니다.

전체 URI는 다음과 같은 형태가 됩니다.

https://MyApp.io/frameio-callback?code=[authorization_code]&scope=offline+device.connect+asset.create&state=[state]

URI를 파싱하는 것은 까다로울 수 있으며, 사용 중인 HTTP/서버 라이브러리에 이를 위한 좋은 리소스가 있을 가능성이 높으므로 이 값을 직접 파싱하려고 시도하기 전에 먼저 확인해 보세요!

테스트를 위해 Python을 사용하여 GET 요청을 관찰하는 서버를 빠르게 설정할 수 있습니다. 콜백 URI는 http://localhost:8888/callback으로 구성되어야 합니다.

$
$ python -m http.server 8888

이제 다음 템플릿을 사용하여 Frame.io 액세스를 요청할 수 있습니다. [client_id] 및 [state] 값을 입력하세요. state의 경우 여기에서 임의의 UUID를 생성할 수 있습니다.

https://applications.frame.io/oauth2/auth?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8888%2Fcallback&client_id=[client_id]&scope=offline+device.connect+asset.create&state=[state]&device_id=62f88d2a-1ae1-45e7-a6a0-81954e0cf2ff

권한 부여 흐름을 진행하면 404 오류가 발생합니다. Python이 요청된 리소스를 인식하지 못하고 이에 응답하는 방법을 모르기 때문입니다. 하지만 걱정하지 마세요. 권한 부여 요청은 성공했습니다! 서버가 터미널에 다음과 같은 내용을 출력하는 것을 볼 수 있습니다.

Serving HTTP on :: port 8888 (http://[::]:8888/) ...
::1 - - [08/Mar/2022 14:04:34] code 404, message File not found
::1 - - [08/Mar/2022 14:04:34] "GET /callback?code=[authentication_code]&scope=offline+device.connect+asset.create&state=[state] HTTP/1.1" 404 -

전송한 것과 동일한 state인지 확인해야 하며, authentication_code는 다음 단계에서 액세스 토큰을 검색할 때 중요합니다.

실제 앱에서 콜백 핸들러는 다음과 같은 형태일 수 있습니다.

1
@handler("/frameio-callback")
2
def do_get(request):
3
    params = url.parse_query(request.url.parts.query)
4
    if "error" in params:
5
       raise AuthError(params["error"])
6
7
    # Handles sending the authentication code and state to the proper user
8
    MyApp.frameio_oauth_success(state=params["state"], code=params["code"])
9
10
    # Render some sort of confirmation page for the user.
11
    request.send_response(
12
        code=200, 
13
        headers={"Content-type": "text/html"}, 
14
        data=OauthSuccessPage()
15
    )

3단계: 액세스 토큰 검색

이제 authorization_code를 얻었으므로 액세스 토큰을 검색할 수 있습니다! 이 시점에서 액세스 토큰은 이미 부여되었으므로 백엔드에 요청하기만 하면 됩니다.

다음과 같이 요청해 보겠습니다.

$
curl -X POST https://applications.frame.io/oauth2/token \
>
    --form 'client_id=[client_id]' \
>
    --form 'state=[state]' \
>
    --form 'code=[authorization_code]' \
>
    --form 'redirect_uri=http://localhost:8888/callback' \
>
    --form 'grant_type=authorization_code' \
>
    --form 'scope=offline device.connect asset.create' \
>
    | python -m json.tool

인증이 완료되면 다른 엔드포인트는 application/json 페이로드를 허용하지만, 인증 엔드포인트에 application/x-www-form-urlencoded 데이터 대신 JSON을 전송하면 오류가 반환됩니다.

이 매개변수들을 살펴보겠습니다.

client_id: Frame.io에서 발급받은 OAuth 앱 식별자입니다. state: 브라우저에 대한 원래 권한 부여 요청에 포함되었고 콜백에서 수신한 state 값입니다. code: 콜백에서 수신한 권한 부여 코드입니다. redirect_uri: Frame.io 백엔드에 등록한 것과 동일한 리디렉션 URI입니다. 이 값이 연동을 위해 Frame.io에 기록된 쉼표로 구분된 URL 목록에 없으면 이 요청은 실패합니다. grant type: 소프트웨어 디바이스 권한 부여 흐름의 경우 항상 authorization_code가 됩니다. scope: 콜백에서 반환된 승인된 권한과 일치해야 합니다.

다음과 유사한 응답을 받아야 합니다.

1
{
2
    "access_token": "[access_token]",
3
    "expires_in": 3599,
4
    "refresh_token": "[refresh_token]",
5
    "scope": "offline device.connect asset.create",
6
    "token_type": "bearer"
7
}

이제 디바이스가 Frame.io에서 성공적으로 권한을 부여받았습니다! 나머지 요청을 수행하는 데 필요하므로 이 값들을 잘 보관해 두세요. 페이로드에 무엇이 포함되어 있는지 살펴보겠습니다.

access_token: Frame.io 백엔드의 나머지 부분에 액세스하기 위한 키입니다. 이 튜토리얼에서 수행할 나머지 요청의 헤더에 이를 추가해야 합니다. expires_in: access_token이 만료될 때까지 남은 시간(초 단위)입니다. 토큰 시간이 만료되면 새로 고쳐야 하며, 이는 향후 튜토리얼에서 다룰 예정입니다. refresh_token: access_token을 관리하는 데 사용할 수 있는 토큰입니다. 대부분 권한 부여를 새로 고치는 데 사용되지만 권한 부여를 취소하는 데 사용할 수도 있습니다. token_type: C2C API의 경우 항상 bearer가 되며 추가적인 조치가 필요하지 않습니다.

실제로 프로젝트에 연결될 때까지 아직 몇 가지 단계가 남았으므로, 이 내용을 숙지한 상태로 계속 진행해 보겠습니다!

4단계: 계정 나열

다음으로 사용자가 연결할 수 있는 계정 목록을 가져와야 합니다. 이는 액세스 토큰이 필요한 첫 번째 호출이며, 헤더에 이를 추가할 것입니다.

$
curl -X GET https://api.frame.io/v2/devices/accounts \
>
    --header "x-client-version: 2.0.0" \
>
    --header "Authorization: Bearer [access_token]" \
>
    | python -m json.tool

이 호출은 사용자가 연결할 수 있는 계정 목록을 반환해야 합니다.

1
[
2
    {
3
        "_type": "account",
4
        "display_name": "Hogwarts General",
5
        "id": "46b7ea11-3041-4e2b-97f7-98fbf5c974c9"
6
    },
7
    {
8
        "_type": "account",
9
        "display_name": "Gryffindor",
10
        "id": "e6007a3d-cad7-4666-9ee3-23c1af032060"
11
    },
12
    {
13
        "_type": "account",
14
        "display_name": "QUIDDITCH LEGENDS -- LETS GOOOOOOOOOO",
15
        "id": "cc94119d-f957-4d6e-b8cf-0c095211b1b9"
16
    }
17
]

이 단계에서는 이 목록을 사용자에게 표시하고 연결할 계정을 선택하게 합니다. 그리고 다음 단계에서 계정 id를 사용하여 사용자가 C2C 디바이스를 연결할 수 있는 프로젝트를 나열합니다.

5단계: 프로젝트 나열

이제 관심 있는 계정의 프로젝트 목록을 가져와야 합니다.

$
curl -X GET https://api.frame.io/v2/devices/accounts/[account_id]/projects \
>
    --header "x-client-version: 2.0.0" \
>
    --header "Authorization: Bearer [access_token]" \
>
    | python -m json.tool

프로젝트를 나열하려는 account_id를 URL에 추가해야 합니다. 또한 전체 리소스 경로가 /devices/…로 시작한다는 점에 주목하세요. 단순히 모든 프로젝트를 나열하는 것이 아니라 사용자가 C2C 디바이스 관리 권한을 가진 프로젝트를 나열하는 것입니다. 사용자가 속한 프로젝트가 나열되지 않으면 해당 프로젝트에 대한 C2C 디바이스 관리 권한이 없다는 뜻입니다.

계정과 유사한 응답을 받게 됩니다.

1
[
2
    {
3
        "_type": "project",
4
        "id": "921480ec-1225-424a-9447-19c61a3a1ef2",
5
        "name": "Match Recordings"
6
    },
7
    {
8
        "_type": "project",
9
        "id": "ed5dbf4a-f146-416b-add0-74de98201876",
10
        "name": "Year Book Material"
11
    }
12
]

계정과 마찬가지로 이 목록을 사용자에게 표시하여 연결할 프로젝트를 선택하게 해야 하며, 계정과 마찬가지로 다음 단계를 위해 프로젝트 id가 필요합니다.

6단계: 프로젝트 연결

이제 사용자가 연결할 프로젝트를 선택했으므로 모든 준비가 완료되었습니다! 소프트웨어 디바이스를 Frame.io 프로젝트에 페어링하기 위한 마지막 단계만 남았습니다.

$
curl -X POST https://api.frame.io/v2/devices/connect?project_id={project_id} \
>
    --header "x-client-version: 2.0.0" \
>
    --header "Authorization: Bearer [access_token]" \
>
    | python -m json.tool

프로젝트 ID는 URL 쿼리 매개변수이며, 여전히 Authorization 헤더를 전달해야 합니다!

다음과 같은 응답을 받게 됩니다(간결성을 위해 일부 데이터 생략).

1
{
2
    "_type": "project_device",
3
    "asset_type": "video",
4
    "authorization": {
5
        "_type": "project_device_authorization",
6
        "creator": {
7
            "_type": "user",
8
            "account_id": "93f872fb-9924-4e31-a430-2574e0742260",
9
            "deleted_at": null,
10
            "email": "hpotter@hoggyhoggyhogwarts.edu",
11
            "id": "d473b5e1-08d2-4842-82ac-a6b01233dc2c",
12
            ...
13
            "name": "Harry Potter",
14
            ...
15
        },
16
        "creator_id": "d473b5e1-08d2-4842-82ac-a6b01233dc2c",
17
        "expires_at": null,
18
        "id": "ee9f5949-b7fa-4c71-8480-6d4c60877c51",
19
        "inserted_at": "2022-03-09T18:14:21.893283Z",
20
        "project_device_id": "6a55d7f6-dfb7-46a1-bff8-a3acb2d3d1aa",
21
        "scopes": {
22
            ...
23
            "asset_create": true,
24
            ...
25
            "id": "1e174fe9-5b53-48db-b556-c310c0848898",
26
            "offline": true,
27
            ...
28
        }
29
    },
30
    "channels": [
31
        {
32
            "_type": "project_device_channel",
33
            "asset_type": "video",
34
            ...
35
        }
36
    ],
37
    "creator_id": "d473b5e1-08d2-4842-82ac-a6b01233dc2c",
38
    "deleted_at": null,
39
    "device_id": "a8a4f3bf-196c-4748-832b-28f1d0801515",
40
    "id": "93af90e7-ee89-4b47-86e6-c2750f3790b6",
41
    ...
42
    "name": "MyApp-62f88d2a-1ae1-45e7-a6a0-81954e0cf2ff",
43
    "project": {
44
        "_type": "project",
45
        "id": "921480ec-1225-424a-9447-19c61a3a1ef2",
46
        "name": "Testbed"
47
    },
48
    "project_id": "921480ec-1225-424a-9447-19c61a3a1ef2",
49
    "status": "online",
50
    ...
51
}

응답 페이로드가 이와 같다면 축하합니다! 해내셨습니다! 첫 번째 Camera to Cloud 디바이스에 성공적으로 권한을 부여했습니다. 잠시 이 기쁨을 만끽하세요!

기쁨을 만끽한 후에는 사용자에게 프로젝트 이름을 표시하여 연결된 프로젝트를 올바르게 확인시켜 주어야 합니다.

서드 파티 OAuth 라이브러리 사용

Frame.io는 표준 OAuth 2.0 흐름을 사용합니다. 보안을 위해 PKCE를 강제합니다. 이러한 연동 부분을 대신 처리해 줄 수 있는 많은 라이브러리가 있습니다.

다음은 널리 사용되는 몇 가지 OAuth 라이브러리입니다.

문제 해결

여기까지 오셨다면 무언가 잘못된 것입니다! 어떤 종류의 오류도 발생하지 않는다면 서드 파티 연동이 아니겠죠? 이 섹션에서는 일반적인 문제들을 나열하고 이를 해결할 가능성이 가장 높은 단계를 안내합니다. 다음 목록을 살펴보고 귀하의 문제와 일치하는 사항이 있는지 확인해 보세요. 오류 가이드 역시 API 오류를 찾아보는 데 훌륭한 리소스입니다.

여기서 해결책을 찾지 못하셨다면 나중에 추가할 수 있도록 겪으신 문제를 공유해 주시면 감사하겠습니다!

연결하려는 계정이나 프로젝트가 반환되지 않음: 계정 및/또는 프로젝트를 나열할 때 연결하려는 항목이 나열되지 않는 경우 몇 가지 원인이 있을 수 있습니다. Frame.io에서 연결하려는 프로젝트로 이동하여 C2C Connections 탭을 클릭합니다. 무엇이 잘못되었는지 파악하는 데 도움이 될 것입니다.

• 계정에 대해 C2C가 활성화되지 않음: 화면이 비어 있고 계정에서 C2C를 사용할 수 없다는 메시지가 표시되는 경우, 계정 관리자가 계정 설정에서 프로젝트에 대해 C2C를 활성화해야 합니다!
• 디바이스 관리자가 아님: 화면이 비어 있고 권한이 없다는 메시지가 표시되는 경우, 계정 관리자가 C2C 디바이스를 연결할 수 있는 사용자의 권한을 변경하거나 귀하를 해당 권한이 있는 역할에 추가해야 합니다.

잘못된 클라이언트 오류: 제공한 디바이스 정보가 저희 시스템에 등록된 정보와 일치하지 않을 때 invalid_client가 반환됩니다. 이는 client_secret, client_id 또는 redirect_uri가 Frame.io 백엔드에 저장된 정보와 일치하지 않을 가능성이 높다는 것을 의미합니다. 잘못된 요청 오류: 요청 데이터의 형식이 잘못되었을 때 bad_request가 반환됩니다. 필드 이름의 철자가 틀렸거나 필수 필드를 누락하지 않았는지 다시 한번 확인하세요.

다음 단계

아직 문의하지 않으셨다면 저희 팀에 문의한 후 다음 가이드로 계속 진행하시기 바랍니다. 여러분의 연락을 기다리겠습니다!