경고: 이 데이터는 Google 사용자 데이터 정책에 따라 제공됩니다. 정책을 검토하고 준수하시기 바랍니다. 이렇게 하지 않으면 프로젝트 또는 계정이 정지될 수 있습니다.

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 계정으로만 사용자를 로그인시키려면 profileemail 범위만 요청하세요. 또는 사용자를 대신하여 지원되는 API를 호출할 권한을 요청하려면 profileemail 범위 외에 필수 범위를 요청합니다.

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

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

client_id=CLIENT_ID&scope=email%20profile

curl 사용:

curl -d "client_id=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_codeverification_url 값을 사용자에게 표시하는 동시에 사용자가 로그인하거나 expires_in에서 지정한 시간이 경과할 때까지 지정된 interval에서 로그인 엔드포인트를 폴링합니다.

사용자 코드 및 인증 URL 표시

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

verification_urluser_code의 값은 변경될 수 있습니다. 다음 한도를 처리할 수 있는 방식으로 UI를 설계합니다.

  • user_code은 15개의 W 크기 문자를 처리할 수 있을 만큼 넓은 입력란에 표시되어야 합니다.
  • verification_url은 40자 길이의 URL 문자열을 처리할 수 있을 만큼 넓은 필드에 표시되어야 합니다.

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

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

원하는 경우 표시용으로 URL에서 스키마를 삭제하여 verification_url 문자열을 수정할 수 있습니다. 사용 중이라면 앱에서 'http&quot' 및 'https://quot' 변이를 모두 처리할 수 있는지 확인해야 합니다. 그렇지 않으면 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=CLIENT_ID&client_secret=CLIENT_SECRET&code=DEVICE_CODE&grant_type=http://oauth.net/grant_type/device/1.0

curl 사용:

curl -d "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code=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(id_token);

// 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 토큰의 전체 기간을 초과하여 사용자를 로그인 상태로 유지하려면 액세스 토큰 새로고침을 참조하세요.
  • 백엔드 서버로 인증해야 하는 경우 이 작업에 대한 자세한 내용은 백엔드 서버로 인증을 참조하세요.