Google은 블랙 커뮤니티를위한 인종적 평등을 추구하기 위해 노력하고 있습니다. 방법을보십시오.
이 페이지는 Cloud Translation API를 통해 번역되었습니다.
Switch to English

OAuth 2.0 인증 및 권한

Nest API는 인증 및 권한 부여에 OAuth 2.0 프로토콜을 사용합니다.

제품이 Nest API를 사용하여 개인 데이터에 액세스하려면 해당 API에 대한 액세스 권한을 부여하는 액세스 토큰을 확보해야합니다. 단일 액세스 토큰은 API의 여러 섹션에 다양한 수준의 액세스 권한을 부여 할 수 있습니다.

인증 순서는 제품이 요청 된 액세스를 나타내는 쿼리 매개 변수를 사용하여 브라우저를 Nest URL로 리디렉션 할 때 시작됩니다. Nest는 사용자 인증, 세션 선택 및 사용자 동의를 처리합니다. 결과는 제품이 액세스 토큰으로 교환 할 수있는 인증 코드입니다. 그런 다음 제품은 액세스 토큰을 사용하여 Nest API를 호출 할 수 있습니다.

OAuth 2.0 흐름
OAuth 2.0 흐름

Nest 클라이언트로 작업 구성

클라이언트의 OAuth 2.0 자격 증명을 찾으려면 클라이언트 페이지의 개요 탭을 확인하십시오.

URI 또는 ​​PIN 기반 인증을 리디렉션 하시겠습니까?

클라이언트를 구성 할 때 PIN 기반 권한 부여를 사용하려면 리디렉션 URI를 입력하거나 리디렉션 URI 필드를 비워 두라는 메시지가 표시됩니다.

제품이 연결된 앱 또는 웹 페이지가없는 장치 (예 : 피트니스 추적기, 어플라이언스 또는 보안 패널) 인 경우 리디렉션 URI 필드를 비워 두십시오.

제품에 브라우저 구성 요소가있는 경우 가장 좋은 방법은 리디렉션 URI를 포함하는 것입니다.

권한 요청

클라이언트 구성에는 권한 세트 (범위라고도 함)가 포함됩니다. 권한은 액세스 토큰이 허용하는 리소스 및 작업 집합을 제어하는 ​​변수 매개 변수입니다. 일반적으로 액세스 권한이 필요한 시점에 선행 권한이 아닌 점진적으로 권한을 요청하는 것이 가장 좋습니다.

결과

구성을 저장하면 클라이언트에 고유 한 클라이언트 ID 및 클라이언트 시크릿이 할당됩니다. 또한 고객에게 인증 URL이 할당됩니다.

권한 부여 URL에는 가능한 CSRF (Cross-Site Request Forgery) 공격을 테스트하는 데 사용할 수있는 상태 매개 변수가 포함되어 있습니다. CSRF 공격 테스트를 참조하십시오.

OAuth 세부 사항

인증 코드 요청

클라이언트가 구성되면 인증 코드 (PIN 코드라고도 함)를 요청할 수 있습니다. 인증 코드는 Nest를 호출하는 데 사용하는 최종 토큰이 아닙니다. OAuth 2.0 플로우의 다음 단계에서 실제 액세스 토큰과 교환하는 데 사용됩니다. 이 단계는 합의 된 액세스 권한으로 올바른 제품에 권한이 부여되고 있는지 Nest에서 사용자에게 직접 보증합니다.

사용자 경험

제품에 대한 액세스 권한을 사용자에게 요청하는 Works with Nest 페이지가 표시됩니다. 제품을 식별하고 제품이 요청한 특정 사용자 권한 (범위)을 간략하게 설명합니다. 화면의 단어는 클라이언트 구성에서 나옵니다.

직접 테스트하려면 1 단계의 인증 URL을 브라우저로로드하십시오. Works with Nest 액세스 요청 페이지가 표시되어야합니다.

Nest와 함께 작동

계속해서 [ACCEPT]를 클릭하면 사용자가 보는 것을 볼 수 있습니다. [ACCEPT] 버튼을 클릭하면 사용자는 제품의 데이터 액세스 요청을 승인합니다.

PIN 경험

클라이언트 구성에서 URI 리디렉션 필드를 비워두면 사용자는 PIN (권한 코드)을 표시하는 Nest 페이지로 리디렉션됩니다. 그러면 장치 UI에 PIN을 수동으로 입력하라는 메시지가 표시됩니다.

핀 코드

URI 경험 리디렉션

클라이언트 구성에 경로 재 지정 URI를 포함하면 사용자가 클라우드 (또는 로컬 호스트)의 페이지로 경로 재 지정되고 Nest는 자동으로 인증 코드를 사용자의 디바이스로 보냅니다.

CSRF 공격 테스트

인증 코드를 승인하기 전에 제품은 state 매개 변수에 리턴 된 값이 원래 인증 요청의 상태 값과 일치하는지 확인해야합니다. 이를 통해 악의적 인 스크립트가 아닌 실제 사용자를 처리 할 수 ​​있습니다. 상태 값이 일치하지 않으면 응답으로 401 Unauthorized HTTP 오류 코드를 발생시켜야합니다.

CSRF 공격은 최종 사용자가 현재 인증 된 웹 응용 프로그램에서 원치 않는 동작을 실행하도록하는 공격입니다.

CSRF 공격
CSRF 공격

CSRF 공격을 방지하려면 권한 부여를 요청할 때 항상 추측 할 수없는 state 제출하는 것이 좋습니다.

이러한 방식으로 Works with Nest 통합을 통해 Nest 클라우드에서 얻은 액세스 코드가 다른 제품이 아닌 제품의 요청에 응답하는지 확인할 수 있습니다.

예:

클라이언트 구성에서 리디렉션 URI를 지정한다고 가정 해 보겠습니다.

 http://localhost:5000/callback
 

클라이언트가 승인 URL에 7tvPJiv8StrAqo9IQE9xsJaDso4 상태를 전송한다고 가정 해 보겠습니다.

 https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
 

사용자는 요청에 동의합니다.

Nest 클라우드는 상태 매개 변수를 경로 재 지정 URI의 일부로 리턴합니다.

 127.0.0.1 - - [02/Jun/2017 13:18:58] "GET /callback?state=7tvPJiv8StrAqo9IQE9xsJaDso4&code=5N4CFK8E8TCFW7PM HTTP/1.1" 302 -
127.0.0.1 - - [02/Jun/2017 13:18:58] "GET / HTTP/1.1" 200 -
 

제품은이 상태 값을 받고 검증 가능한 상태의 리디렉션 만 허용하도록 프로그래밍해야합니다.

추측 할 수없는 상태 매개 변수를 생성하는 방법에는 여러 가지가 있습니다. 메모리에 저장된 사전 또는 재 계산 가능한 값에서 무작위 상태 값을 제공 할 수 있습니다. 쉽게 확인할 수있는 변수 (예 : 클라이언트 ID 및 세션 쿠키)와 함께 개인 키를 사용하여 해시 값을 계산할 수 있습니다. 개인 키 없이는 추측하기 어려운 바이트 값이 생성됩니다. 또 다른 제안은 현재 날짜와 시간을 해시하는 것입니다. 이 접근 방식을 사용하면 응용 프로그램은 전송 시간을 저장하여 확인하거나 유효 기간이 미끄러지도록해야합니다 (예 : TOTP (Time-based One-Time Password) 알고리즘 사용).

HMAC (keyed-hash message authentication code)를 계산 한 후 base-64로 인코딩하여 상태 매개 변수로 Nest 클라우드에 전달합니다.

다음은 datetime 을 사용하는 Python 예제입니다.

 import base64
import datetime
import hmac
import hashlib

def generate_state_parameter(client_id, private_key):
    date = datetime.datetime.today()
    raw_state = str(date) + client_id
    hashed = hmac.new(private_key, raw_state, hashlib.sha1)
    state = base64.b64encode(hashed.digest())
    return (state, date)
 

인증 코드 오류 메시지

인증 코드 요청이 실패하면 사용자에게 오류 메시지가 표시됩니다. 이러한 메시지에 대한 자세한 정보와이를 방지하는 방법은 Authorization Reference를 참조하십시오 .

액세스 토큰에 대한 교환 인증 코드

액세스 토큰을 얻는 마지막 단계는 제품이 방금 얻은 인증 코드를 사용하여 요청하는 것입니다. "x-www-form-urlencoded"HTTP POST 요청을 수행하면됩니다.

요청에 아래 매개 변수를 포함하십시오. 네 가지 매개 변수가 모두 필요합니다.

모수 기술
client_id 1 단계의 클라이언트 ID
client_secret 1 단계의 고객 비밀
암호 2 단계에서받은 인증 코드
grant_type 이 필드의 값은 항상 다음과 같아야합니다. authorization_code

각 POST 호출 전에 새 인증 코드를 받으십시오. 이렇게하려면 인증 URL을 다시로드하십시오. 그런 다음 POST의 code 매개 변수를 변경하여 새 인증 코드를 포함하십시오.

코드 예 (인증)

다양한 언어로 된 예를 참조하십시오 .

우편 배달부 예 (인증)

Postman은 OAuth 요청을 쉽게 테스트 할 수있는 방법을 제공합니다.

헤더 탭에서 Content-Type = application/x-www-form-urlencoded 인지 확인하십시오.

액세스 토큰을 가져 오는 POST 헤더

본문 탭에서 다음 키 : 값 쌍을 포함시킵니다.

액세스 토큰을 얻는 POST 본문

액세스 토큰 응답

요청이 성공하면 다음 필드가 포함 된 JSON 객체가 반환됩니다.

  • access_token — 사용자의 액세스 토큰. 이 값은 안전하게 유지해야합니다.
  • expires_in — 토큰이 만료되기 전에 요청 된 시간부터 남은 시간 (초)입니다.

액세스 토큰 오류 메시지

요청이 실패하면 HTTP 상태 코드 형식의 오류가 수신됩니다. 이러한 오류 및 오류 방지 방법에 대한 자세한 정보는 Authorization Reference를 참조하십시오 .

인증 된 요청

제품은 액세스 토큰을 확보 한 후 토큰을 HTTP 권한 부여 헤더의 Nest API로 보냅니다. URI 쿼리 문자열 매개 변수로 토큰을 보낼 수는 있지만 URI 매개 변수는 완전히 안전하지 않은 로그 파일로 끝날 수 있으므로 권장하지 않습니다.

액세스 토큰은 토큰 요청 범위에 설명 된 일련의 작업 및 리소스에만 유효합니다. 예를 들어, Nest Thermostat API에 대한 액세스 토큰이 발행되면 Nest Camera API에 대한 액세스 권한이 부여되지 않습니다.

코드 예제 (읽기 / 쓰기)

우편 배달부 예 (읽기 / 쓰기)

Postman은 Content-Type = application/json 사용하여 API 호출을 테스트하는 쉬운 방법을 제공합니다.

데이터를 읽으려면 GET

잘못된 토큰

유효하지 않은 토큰을 사용하여 API를 호출하면 서버로부터 401 Unauthorized 응답을 다시받습니다. 다음과 같은 이유로 토큰이 유효하지 않고 재생성이 필요할 수 있습니다.

  • 만료되었습니다
  • 사용자가 처음에 제품에 부여한 권한을 취소했습니다

사용자를 권한 부여 워크 플로우 시작으로 다시 리디렉션하여 401 Unauthorized 오류를 올바르게 처리하도록 제품을 코딩하는 것이 중요합니다.

Nest 연결이 닫힌 상태에서 작동

사용자가 Works with Nest 연결을 제거하면 제품이 auth_revoked 이벤트를 수신하고 연결이 닫힙니다.