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 JavaScript 라이브러리를 사용하는 경우는 다음과 같습니다.

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 토큰의 전체 기간 이후에도 사용자의 로그인 상태를 유지하려면 액세스 토큰 갱신을 참고하세요.
  • 백엔드 서버로 인증해야 하는 경우 백엔드 서버로 인증에서 안전하게 인증하는 방법을 알아보세요.