TV 및 제한된 입력 기기에서 로그인

인터넷 연결 TV와 같이 입력 기능이 제한된 기기에서 사용자가 Google 계정으로 앱에 로그인하도록 할 수 있습니다.

앱이 사용자에게 단축 코드와 로그인 URL을 표시합니다. 그런 다음 사용자는 웹브라우저에서 로그인 URL을 열고 코드를 입력한 후 사용자의 로그인 정보에 액세스할 수 있는 권한을 앱에 부여합니다. 마지막으로 앱이 확인을 받고 사용자가 로그인됩니다.

이 로그인 흐름을 사용하려면 다음 기준을 충족하는 기기에서 앱을 실행해야 합니다.

  • 기기는 사용자에게 안내와 함께 40자 URL 및 15자 사용자 코드를 표시할 수 있어야 합니다.
  • 기기가 인터넷에 연결되어 있어야 합니다.

클라이언트 ID 및 클라이언트 보안 비밀번호 가져오기

Google의 로그인 엔드포인트에 요청하려면 앱에 OAuth 2.0 클라이언트 ID와 클라이언트 보안 비밀번호가 있어야 합니다.

프로젝트의 클라이언트 ID와 클라이언트 비밀번호를 찾으려면 다음 단계를 따르세요.

  1. 기존 OAuth 2.0 사용자 인증 정보를 선택하거나 사용자 인증 정보 페이지를 엽니다.
  2. 아직 하지 않은 경우 사용자 인증 정보 만들기 > OAuth 클라이언트 ID를 클릭하고 사용자 인증 정보를 만드는 데 필요한 정보를 제공하여 프로젝트의 OAuth 2.0 사용자 인증 정보를 만듭니다.
  3. OAuth 2.0 클라이언트 ID 섹션에서 클라이언트 ID를 찾습니다. 자세한 내용을 보려면 클라이언트 ID를 클릭하세요.

새 클라이언트 ID를 만드는 경우 TV 및 제한된 입력 기기 애플리케이션 유형을 선택합니다.

사용자 코드 및 인증 URL 가져오기

사용자가 Google 계정으로 로그인을 요청하면 OAuth 2.0 기기 엔드포인트인 https://oauth2.googleapis.com/device/code에 HTTP POST 요청을 전송하여 사용자 코드와 인증 URL을 가져옵니다. 요청에 클라이언트 ID와 필요한 범위 목록을 포함합니다. Google 계정으로만 사용자를 로그인 처리하려면 profile 및 email 범위만 요청합니다. 또는 사용자를 대신하여 지원되는 API를 호출할 수 있는 권한을 요청하려면 profile 및 email 범위 외에도 필요한 범위를 요청합니다.

다음은 사용자 코드 요청의 예입니다.

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_GOOGLE_CLIENT_ID&scope=email%20profile

curl 사용:

curl -d "client_id=YOUR_GOOGLE_CLIENT_ID&scope=email profile" https://oauth2.googleapis.com/device/code

응답은 JSON 객체로 반환됩니다.

 {
  "device_code" : "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code" : "GQVQ-JKEC",
  "verification_url" : "https://www.google.com/device",
  "expires_in" : 1800,
  "interval" : 5
}

앱은 user_code 및 verification_url 값을 사용자에게 표시하고 동시에 사용자가 로그인하거나 expires_in에서 지정한 시간이 지날 때까지 지정된 interval에서 로그인 엔드포인트를 폴링합니다.

사용자 코드 및 인증 URL 표시

기기 엔드포인트에서 사용자 코드와 인증 URL을 수신하면 이를 표시하고 사용자에게 URL을 열고 사용자 코드를 입력하도록 안내합니다.

verification_url 및 user_code의 값은 변경될 수 있습니다. 다음 제한사항을 처리할 수 있는 방식으로 UI를 디자인하세요.

  • user_code는 W 크기의 문자 15개를 처리할 수 있을 정도로 넓은 필드에 표시되어야 합니다.
  • verification_url는 40자(영문 기준) 길이의 URL 문자열을 처리하기에 충분한 필드 너비로 표시되어야 합니다.

두 문자열 모두 US-ASCII 문자 집합의 인쇄 가능한 문자를 포함할 수 있습니다.

user_code 문자열을 표시할 때 어떤 식으로든 문자열을 수정하지 마세요(예: 대소문자 변경 또는 다른 서식 지정 문자 삽입). 나중에 코드의 형식이 변경되면 앱이 중단될 수 있기 때문입니다.

원하는 경우 표시 목적으로 URL에서 스키마를 삭제하여 verification_url 문자열을 수정할 수 있습니다. 그렇게 하는 경우 앱에서 'http' 및 'https' 변형을 모두 처리할 수 있는지 확인합니다. 그 외에는 verification_url 문자열을 수정하지 마세요.

사용자가 확인 URL로 이동하면 다음과 유사한 페이지가 표시됩니다.

코드를 입력하여 기기를 연결하세요.

사용자가 사용자 코드를 입력하면 Google 로그인 사이트에 다음과 비슷한 동의 화면이 표시됩니다.

기기 클라이언트의 동의 화면 예

사용자가 허용을 클릭하면 앱은 사용자를 식별하는 ID 토큰, Google API를 호출하기 위한 액세스 토큰, 새 토큰을 획득하기 위한 갱신 토큰을 가져올 수 있습니다.

ID 토큰 및 갱신 토큰 가져오기

앱에 사용자 코드와 인증 URL이 표시되면 기기 엔드포인트에서 수신한 기기 코드로 토큰 엔드포인트 (https://oauth2.googleapis.com/token)를 폴링합니다. interval 값으로 지정된 간격(초)으로 토큰 엔드포인트를 폴링합니다.

다음은 요청의 예입니다.

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_GOOGLE_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

curl 사용:

curl -d "client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=YOUR_DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0" https://oauth2.googleapis.com/token

사용자가 아직 요청을 승인하지 않은 경우 응답은 다음과 같습니다.

{
  "error" : "authorization_pending"
}

앱은 interval 값을 초과하지 않는 속도로 이러한 요청을 반복해야 합니다. 앱이 너무 빨리 폴링하면 응답은 다음과 같습니다.

{
  "error" : "slow_down"
}

사용자가 로그인하여 요청된 범위에 대한 액세스 권한을 앱에 부여하면 앱의 다음 요청에 대한 응답에 ID 토큰, 액세스 토큰, 갱신 토큰이 포함됩니다.

{
  "access_token": "ya29.AHES6ZSuY8f6WFLswSv0HZLP2J4cCvFSj-8GiZM0Pr6cgXU",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "1/551G1yXUqgkDGnkfFk6ZbjMMMDIMxo3JFc8lY8CAR-Q",
  "id_token": "eyJhbGciOiJSUzI..."
}

이 응답을 받으면 앱은 ID 토큰을 디코딩하여 로그인한 사용자에 관한 기본 프로필 정보를 가져오거나 앱의 백엔드 서버로 ID 토큰을 전송하여 서버에 안전하게 인증할 수 있습니다. 또한 앱은 액세스 토큰을 사용하여 사용자가 승인한 Google API를 호출할 수 있습니다.

ID 및 액세스 토큰에는 수명이 제한되어 있습니다. 토큰의 수명 이후에도 사용자가 로그인 상태를 유지하게 하려면 갱신 토큰을 저장하고 이를 사용하여 새 토큰을 요청하세요.

ID 토큰에서 사용자 프로필 정보 가져오기

JWT 디코딩 라이브러리로 ID 토큰을 디코딩하여 로그인한 사용자에 대한 프로필 정보를 가져올 수 있습니다. 예를 들어 Auth0 jwt-decode 자바스크립트 라이브러리를 사용합니다.

var user_profile = jwt_decode(<var>id_token</var>);

// The "sub" field is available on all ID tokens. This value is unique for each
// Google account and can be used to identify the user. (But do not send this
// value to your server; instead, send the whole ID token so its authenticity
// can be verified.)
var user_id = user_profile["sub"];

// These values are available when you request the "profile" and "email" scopes.
var user_email = user_profile["email"];
var email_verified = user_profile["email_verified"];
var user_name = user_profile["name"];
var user_photo_url = user_profile["picture"];
var user_given_name = user_profile["given_name"];
var user_family_name = user_profile["family_name"];
var user_locale = user_profile["locale"];

추가 정보

  • ID 토큰의 전체 기간 이후에도 사용자의 로그인 상태를 유지하려면 액세스 토큰 갱신을 참조하세요.
  • 백엔드 서버로 인증해야 하는 경우 백엔드 서버로 인증에서 안전하게 인증하는 방법을 참고하세요.