OpenID 연결

Google의 OpenID Connect 엔드 포인트는 OpenID 인증을 받았습니다.

Google의 OAuth 2.0 API는 인증과 승인 모두에 사용할 수 있습니다. 이 문서는 우리의 OAuth를받는 준수 인증을위한 2.0 구현에 대해 설명 오픈 ID 연결 사양이며 오픈 ID 인증을 . OAuth 2.0을 사용하여 Google API에 액세스 에있는 문서도이 서비스에 적용됩니다. 이 프로토콜을 대화식으로 탐색하려면 Google OAuth 2.0 Playground를 권장합니다. Stack Overflow 에 대한 도움을 받으려면 'google-oauth'로 질문에 태그를 지정하세요.

OAuth 2.0 설정

애플리케이션이 사용자 로그인에 Google의 OAuth 2.0 인증 시스템을 사용하려면 먼저 Google API Console에서 프로젝트를 설정하여 OAuth 2.0 자격 증명을 얻고 리디렉션 URI를 설정하고 (선택적으로) 사용자가 사용자에게 표시하는 브랜딩 정보를 사용자 정의해야합니다. 동의 화면. API Console을 사용하여 서비스 계정을 만들고, 결제를 활성화하고, 필터링을 설정하고, 기타 작업을 수행 할 수도 있습니다. 자세한 내용은 Google API Console 도움말을 참조하십시오.

OAuth 2.0 사용자 인증 정보 얻기

사용자를 인증하고 Google API에 액세스하려면 클라이언트 ID 및 클라이언트 비밀번호를 포함한 OAuth 2.0 사용자 인증 정보가 필요합니다.

지정된 OAuth 2.0 자격 증명에 대한 클라이언트 ID 및 클라이언트 암호를 보려면 다음 텍스트를 클릭하십시오. 자격 증명 선택 . 열리는 창에서 프로젝트 및 원하는 자격 증명을 선택한 다음 보기 를 클릭하십시오.

또는 API Console 의 Credentials (인증 정보) 페이지 에서 고객 ID와 고객 비밀번호를 확인하십시오.

  1. Go to the Credentials page.
  2. 신임 정보 또는 연필 ( ) 아이콘을 클릭하십시오. 고객 ID와 비밀번호는 페이지 상단에 있습니다.

리디렉션 URI 설정

API Console에 설정 한 리디렉션 URI는 Google이 인증 요청에 대한 응답을 보내는 위치를 결정 합니다 .

지정된 OAuth 2.0 자격 증명에 대한 리디렉션 URI를 만들거나 보거나 편집하려면 다음을 수행하십시오.

  1. Go to the Credentials page.
  2. 페이지의 OAuth 2.0 클라이언트 ID 섹션에서 신임 정보를 클릭하십시오.
  3. 리디렉션 URI를 보거나 편집하십시오.

자격 증명 페이지에 OAuth 2.0 클라이언트 ID 섹션이 없으면 프로젝트에 OAuth 자격 증명이없는 것입니다. 자격 증명 을 만들려면 자격 증명 만들기를 클릭합니다.

사용자 동의 화면 사용자 지정

사용자의 경우 OAuth 2.0 인증 환경에는 사용자가 공개하는 정보와 적용되는 약관을 설명하는 동의 화면이 포함됩니다. 예를 들어 사용자가 로그인하면 앱에 이메일 주소 및 기본 계정 정보에 대한 액세스 권한을 부여하라는 메시지가 표시 될 수 있습니다. 앱이 인증 요청에 포함하는 scope 매개 변수를 사용하여이 정보에 대한 액세스를 요청 합니다. 범위를 사용하여 다른 Google API에 대한 액세스를 요청할 수도 있습니다.

사용자 동의 화면에는 제품 이름, 로고 및 홈페이지 URL과 같은 브랜드 정보도 표시됩니다. API Console에서 브랜딩 정보를 제어합니다.

프로젝트의 동의 화면을 활성화하려면 :

  1. 열기 Consent Screen page 에서 Google API Console .
  2. If prompted, select a project, or create a new one.
  3. 양식을 작성하고 저장을 클릭 하십시오 .

다음 동의 대화 상자는 OAuth 2.0 및 Google 드라이브 범위의 조합이 요청에있을 때 사용자에게 표시되는 내용을 보여줍니다. (이 일반 대화 상자는 Google OAuth 2.0 Playground를 사용하여 생성되었으므로 API Console에 설정되는 브랜딩 정보가 포함되지 않습니다.)

동의 페이지 스크린 샷

서비스에 액세스

Google 및 타사는 사용자 인증 및 Google API에 대한 액세스 권한을 얻기위한 여러 구현 세부 정보를 처리하는 데 사용할 수있는 라이브러리를 제공합니다. 예를 들어 다양한 플랫폼에서 사용할 수있는 Google 로그인Google 클라이언트 라이브러리 가 있습니다.

라이브러리를 사용하지 않으려면 사용 가능한 라이브러리의 기본이되는 HTTP 요청 흐름을 설명하는이 문서의 나머지 부분에있는 지침을 따르십시오.

사용자 인증

사용자 인증에는 ID 토큰 획득 및 유효성 검증이 포함됩니다. ID 토큰 은 인터넷에서 ID 주장을 공유하는 데 사용하도록 설계된 OpenID Connect 의 표준화 된 기능입니다.

사용자를 인증하고 ID 토큰을 얻기 위해 가장 일반적으로 사용되는 접근 방식을 "서버"흐름과 "암시 적"흐름이라고합니다. 서버 흐름을 통해 애플리케이션의 백엔드 서버는 브라우저 또는 모바일 장치를 사용하는 사람의 신원을 확인할 수 있습니다. 암시 적 흐름은 클라이언트 측 애플리케이션 (일반적으로 브라우저에서 실행되는 JavaScript 앱)이 백엔드 서버를 통하지 않고 API에 직접 액세스해야 할 때 사용됩니다.

이 문서는 사용자 인증을 위해 서버 흐름을 수행하는 방법을 설명합니다. 암시 적 흐름은 클라이언트 측에서 토큰을 처리하고 사용할 때 보안 위험이 있으므로 훨씬 더 복잡합니다. 암시 적 흐름을 구현해야하는 경우 Google 로그인을 사용하는 것이 좋습니다.

서버 흐름

이러한 프로토콜을 사용하고 사용자를 인증 할 수 있도록 API Console에서 앱설정 했는지 확인하십시오. 사용자가 Google로 로그인을 시도 할 때 다음을 수행해야합니다.

  1. 위조 방지 상태 토큰 생성
  2. Google에 인증 요청 보내기
  3. 위조 방지 상태 토큰 확인
  4. 액세스 토큰 및 ID 토큰의 교환 code
  5. ID 토큰에서 사용자 정보 얻기
  6. 사용자 인증

1. 위조 방지 상태 토큰 생성

요청 위조 공격을 방지하여 사용자의 보안을 보호해야합니다. 첫 번째 단계는 앱과 사용자의 클라이언트간에 상태를 유지하는 고유 한 세션 토큰을 만드는 것입니다. 나중에이 고유 한 세션 토큰을 Google OAuth 로그인 서비스에서 반환 한 인증 응답과 일치시켜 사용자가 악의적 인 공격자가 아닌 요청을하고 있는지 확인합니다. 이러한 토큰은 종종 CSRF (Cross-Site Request Forgery ) 토큰이라고합니다.

상태 토큰에 대한 한 가지 좋은 선택은 고품질 난수 생성기를 사용하여 구성된 30 자 정도의 문자열입니다. 다른 하나는 백엔드에서 비밀로 유지되는 키로 세션 상태 변수 중 일부에 서명하여 생성 된 해시입니다.

다음 코드는 고유 한 세션 토큰 생성을 보여줍니다.

PHP

이 샘플을 사용하려면 PHP 용 Google API 클라이언트 라이브러리를 다운로드해야합니다.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

자바

이 샘플을 사용하려면 자바 용 Google API 클라이언트 라이브러리를 다운로드해야합니다.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

파이썬

이 샘플을 사용하려면 Python 용 Google API 클라이언트 라이브러리를 다운로드해야합니다.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Google에 인증 요청 보내기

다음 단계는 적절한 URI 매개 변수를 사용하여 HTTPS GET 요청을 구성하는 것입니다. 이 프로세스의 모든 단계에서 HTTP 대신 HTTPS를 사용합니다. HTTP 연결이 거부됩니다. authorization_endpoint 메타 데이터 값을 사용하여 Discovery 문서 에서 기본 URI를 검색해야합니다. 다음 설명에서는 기본 URI가 https://accounts.google.com/o/oauth2/v2/auth 라고 가정합니다.

기본 요청의 경우 다음 매개 변수를 지정하십시오.

  • API Console Credentials page에서 얻은 client_id .
  • response_type , 기본 인증 코드 흐름 요청에서 code 여야합니다. (자세한 내용은 response_type 에서 읽으십시오.)
  • scope , 기본 요청에서 openid email 이어야합니다. ( scope 에서 자세히 읽어보십시오.)
  • redirect_uri 는 Google에서 응답을받을 서버의 HTTP 엔드 포인트 여야합니다. 값은 API Console Credentials page에서 구성한 OAuth 2.0 클라이언트에 대해 승인 된 리디렉션 URI 중 하나와 정확히 일치해야합니다. 이 값이 승인 된 URI와 일치하지 않으면 redirect_uri_mismatch 오류와 함께 요청이 실패합니다.
  • state 에는 위조 방지 고유 세션 토큰의 값과 사용자가 애플리케이션으로 돌아올 때 컨텍스트를 복구하는 데 필요한 기타 정보 (예 : 시작 URL)가 포함되어야합니다. ( state 에서 더 많은 것을 읽으십시오.)
  • nonce 는 존재하는 경우 재생 보호를 활성화하는 앱에서 생성 된 임의의 값입니다.
  • login_hint 는 사용자의 이메일 주소이거나 사용자의 Google ID에 해당하는 sub 문자열 일 수 있습니다. login_hint 제공하지 않고 사용자가 현재 로그인되어있는 경우 동의 화면에 사용자의 이메일 주소를 앱에 공개하기위한 승인 요청이 포함됩니다. ( login_hint 에서 자세히 알아보십시오.)
  • hd 매개 변수를 사용하여 특정 G Suite 도메인 사용자를위한 OpenID Connect 흐름을 최적화합니다. ( hd 에서 더 많은 것을 읽으십시오.)

다음은 가독성을 위해 줄 바꿈 및 공백이있는 전체 OpenID Connect 인증 URI의 예입니다.

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

앱에서 새로운 정보를 요청하거나 앱에서 이전에 승인하지 않은 계정 액세스를 요청하는 경우 사용자는 동의해야합니다.

3. 위조 방지 상태 토큰 확인

응답은 요청 에서 지정한 redirect_uri 로 전송됩니다. 모든 응답은 아래와 같이 쿼리 문자열로 반환됩니다.

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

서버에서 Google에서받은 state 1 단계 에서 생성 한 세션 토큰과 일치하는지 확인해야합니다. 이 왕복 확인은 악의적 인 스크립트가 아닌 사용자가 요청을하고 있는지 확인하는 데 도움이됩니다.

다음 코드는 1 단계에서 생성 한 세션 토큰을 확인하는 방법을 보여줍니다.

PHP

이 샘플을 사용하려면 PHP 용 Google API 클라이언트 라이브러리를 다운로드해야합니다.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

자바

이 샘플을 사용하려면 자바 용 Google API 클라이언트 라이브러리를 다운로드해야합니다.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

파이썬

이 샘플을 사용하려면 Python 용 Google API 클라이언트 라이브러리를 다운로드해야합니다.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. 액세스 토큰 및 ID 토큰에 대한 code 교환

응답에는 서버가 액세스 토큰 및 ID 토큰으로 교환 할 수있는 일회성 인증 코드 인 code 매개 변수가 포함됩니다. 서버는 HTTPS POST 요청을 보내이 교환을 수행 POST . POST 요청은 token_endpoint 메타 데이터 값을 사용하여 Discovery 문서 에서 검색해야하는 토큰 엔드 포인트로 전송됩니다. 다음 설명에서는 엔드 포인트가 https://oauth2.googleapis.com/token 이라고 가정합니다. 요청은 POST 본문에 다음 매개 변수를 포함해야합니다.

필드
code 초기 요청 에서 반환 된 인증 코드입니다.
client_id OAuth 2.0 사용자 인증 정보 얻기에 설명 된대로 API Console Credentials page에서 얻은 클라이언트 ID입니다.
client_secret OAuth 2.0 자격 증명 얻기에 설명 된대로 API Console Credentials page에서 얻은 클라이언트 암호입니다.
redirect_uri 리디렉션 URI 설정에 설명 된대로 API Console Credentials page에 지정된 지정된 client_id 대한 승인 된 리디렉션 URI입니다.
grant_type 이 필드는 OAuth 2.0 사양에 정의 된대로 authorization_code 값을 포함해야합니다.

실제 요청은 다음 예와 같습니다.

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

이 요청에 대한 성공적인 응답에는 JSON 배열에 다음 필드가 포함됩니다.

필드
access_token Google API로 보낼 수있는 토큰입니다.
expires_in 액세스 토큰의 남은 수명 (초)입니다.
id_token Google에서 디지털 서명 한 사용자에 대한 ID 정보가 포함 된 JWT 입니다.
scope 공백으로 구분되고 대소 문자를 구분하는 문자열 목록으로 표현되는 access_token 의해 부여 된 액세스 범위입니다.
token_type 반환 된 토큰 유형을 식별합니다. 이때이 필드는 항상 Bearer 값을 갖습니다.
refresh_token (선택 과목)

이 필드는 인증 요청 에서 access_type 매개 변수가 offline 으로 설정된 경우에만 존재합니다. 자세한 내용은 새로 고침 토큰을 참조하십시오.

5. ID 토큰에서 사용자 정보 얻기

ID 토큰은 JWT (JSON 웹 토큰), 즉 암호화 방식으로 서명 된 Base64 인코딩 JSON 개체입니다. 일반적으로 ID 토큰 을 사용하기 전에 유효성검사하는 것이 중요하지만, 중개없는 HTTPS 채널을 통해 Google과 직접 통신하고 클라이언트 암호를 사용하여 Google에 자신을 인증하므로 토큰이 수신은 실제로 Google에서 제공되며 유효합니다. 서버가 ID 토큰을 앱의 다른 구성 요소에 전달하는 경우 다른 구성 요소 가 토큰 을 사용하기 전에 토큰의 유효성을 검사하는 것이 매우 중요합니다.

대부분의 API 라이브러리는 유효성 검사와 base64url로 인코딩 된 값을 디코딩하고 JSON을 구문 분석하는 작업을 결합하므로 ID 토큰의 클레임에 액세스 할 때 어쨌든 토큰 유효성을 검사하게됩니다.

ID 토큰의 페이로드

ID 토큰은 이름 / 값 쌍 집합이 포함 된 JSON 개체입니다. 다음은 가독성을 위해 형식이 지정된 예입니다.

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Google ID 토큰에는 다음 필드 ( 클레임이라고 함 )가 포함될 수 있습니다.

청구 제공 기술
aud 항상 이 ID 토큰이 대상으로하는 대상입니다. 애플리케이션의 OAuth 2.0 클라이언트 ID 중 하나 여야합니다.
exp 항상 ID 토큰이 허용되지 않아야하는 만료 시간입니다. Unix 시간 (정수 초)으로 표시됩니다.
iat 항상 ID 토큰이 발행 된 시간입니다. Unix 시간 (정수 초)으로 표시됩니다.
iss 항상 응답 발행자에 대한 발행자 식별자입니다. Google ID 토큰의 경우 항상 https://accounts.google.com 또는 accounts.google.com 입니다.
sub 항상 모든 Google 계정에서 고유하며 재사용되지 않는 사용자의 식별자입니다. Google 계정은 서로 다른 시점에 여러 이메일 주소를 가질 수 있지만 sub 값은 변경되지 않습니다. 애플리케이션 내에서 sub 를 사용자의 고유 식별자 키로 사용하십시오. 대소 문자를 구분하는 ASCII 문자의 최대 길이는 255 자입니다.
at_hash 액세스 토큰 해시. 액세스 토큰이 ID 토큰에 연결되어 있는지 확인합니다. 서버 흐름에서 access_token 값을 사용하여 ID 토큰이 발급 된 경우이 클레임은 항상 포함됩니다. 이 클레임은 교차 사이트 요청 위조 공격으로부터 보호하기위한 대체 메커니즘으로 사용할 수 있지만 1 단계3 단계 를 수행하는 경우 액세스 토큰을 확인할 필요가 없습니다.
azp 승인 된 발표자의 client_id 입니다. 이 클레임은 ID 토큰을 요청하는 당사자가 ID 토큰의 대상과 동일하지 않은 경우에만 필요합니다. 웹 애플리케이션과 Android 앱이 서로 다른 OAuth 2.0 client_id 있지만 동일한 Google API 프로젝트를 공유하는 하이브리드 앱용 Google의 경우 일 수 있습니다.
email 사용자의 이메일 주소입니다. 이 값은이 사용자에게 고유하지 않을 수 있으며 기본 키로 사용하기에 적합하지 않습니다. 범위에 email 범위 값이 포함 된 경우에만 제공됩니다.
email_verified 사용자의 전자 메일 주소가 확인 된 경우 True입니다. 그렇지 않으면 거짓입니다.
family_name 사용자의 성 또는 성입니다. name 주장이있을 때 제공 될 수 있습니다.
given_name 사용자의 이름 또는 이름입니다. name 주장이있을 때 제공 될 수 있습니다.
hd 사용자의 호스팅 된 G Suite 도메인입니다. 사용자가 호스팅 된 도메인에 속한 경우에만 제공됩니다.
locale BCP 47 언어 태그로 표시되는 사용자의 로케일입니다. name 주장이있을 때 제공 될 수 있습니다.
name 표시 가능한 형식으로 된 사용자의 전체 이름입니다. 다음과 같은 경우 제공 될 수 있습니다.
  • 요청 범위에 "profile"문자열이 포함되었습니다.
  • 토큰 새로 고침에서 ID 토큰이 반환됩니다.

name 클레임이있는 경우이를 사용하여 앱의 사용자 레코드를 업데이트 할 수 있습니다. 이 주장이 존재한다는 보장은 없습니다.

nonce 인증 요청에서 앱이 제공 한 nonce 의 값입니다. 재생 공격이 한 번만 표시되도록하여 보호를 강화해야합니다.
picture 사용자 프로필 사진의 URL입니다. 다음과 같은 경우 제공 될 수 있습니다.
  • 요청 범위에 "profile"문자열이 포함되었습니다.
  • 토큰 새로 고침에서 ID 토큰이 반환됩니다.

picture 클레임이있는 경우이를 사용하여 앱의 사용자 레코드를 업데이트 할 수 있습니다. 이 주장이 존재한다는 보장은 없습니다.

profile 사용자 프로필 페이지의 URL입니다. 다음과 같은 경우 제공 될 수 있습니다.
  • 요청 범위에 "profile"문자열이 포함되었습니다.
  • 토큰 새로 고침에서 ID 토큰이 반환됩니다.

profile 클레임이있는 경우이를 사용하여 앱의 사용자 레코드를 업데이트 할 수 있습니다. 이 주장이 존재한다는 보장은 없습니다.

6. 사용자 인증

ID 토큰에서 사용자 정보를 얻은 후 앱의 사용자 데이터베이스를 쿼리해야합니다. 사용자가 이미 데이터베이스에있는 경우 모든 로그인 요구 사항이 Google API 응답에 의해 충족되면 해당 사용자에 대한 애플리케이션 세션을 시작해야합니다.

사용자가 사용자 데이터베이스에없는 경우 사용자를 새 사용자 등록 흐름으로 리디렉션해야합니다. Google에서받은 정보를 기반으로 사용자를 자동 등록하거나 최소한 등록 양식에 필요한 많은 필드를 미리 채울 수 있습니다. ID 토큰의 정보 외에도 사용자 프로필 엔드 포인트에서 추가 사용자 프로필 정보 를 얻을 수 있습니다.

고급 주제

다음 섹션에서는 Google OAuth 2.0 API에 대해 자세히 설명합니다. 이 정보는 인증 및 권한 부여와 관련된 고급 요구 사항이있는 개발자를위한 것입니다.

다른 Google API에 대한 액세스

인증을 위해 OAuth 2.0을 사용하는 이점 중 하나는 사용자를 인증하는 동시에 애플리케이션이 사용자를 대신하여 다른 Google API (예 : YouTube, Google 드라이브, 캘린더 또는 연락처)를 사용할 수있는 권한을 얻을 수 있다는 것입니다. 이렇게하려면 Google에 보내는 인증 요청에 필요한 다른 범위를 포함하세요. 예를 들어 사용자의 연령대를 인증 요청에 추가하려면 openid email https://www.googleapis.com/auth/profile.agerange.read 의 범위 매개 변수를 전달합니다. 사용자에게 동의 화면 에 적절하게 메시지가 표시됩니다. Google에서 다시받은 액세스 토큰을 사용하면 요청하고 부여한 액세스 범위와 관련된 모든 API에 액세스 할 수 있습니다.

토큰 새로 고침

API 액세스 요청에서 code 교환 중에 반환되는 새로 고침 토큰을 요청할 수 있습니다. 새로 고침 토큰은 사용자가 애플리케이션에없는 동안 Google API에 대한 지속적인 액세스를 앱에 제공합니다. 새로 고침 토큰을 요청하려면 인증 요청 에서 set the access_type 매개 변수를 offline 으로 추가하세요.

고려 사항 :

  • 코드 교환 흐름을 처음 수행 할 때만 새로 고침 토큰을 얻을 수 있으므로 새로 고침 토큰을 안전하고 영구적으로 저장해야합니다.
  • 발급되는 새로 고침 토큰 수에는 제한이 있습니다. 클라이언트 / 사용자 조합 당 한도, 모든 클라이언트의 사용자 당 한도입니다. 애플리케이션에서 너무 많은 새로 고침 토큰을 요청하면 이러한 제한에 도달 할 수 있으며이 경우 이전 새로 고침 토큰이 작동을 중지합니다.

자세한 내용 은 액세스 토큰 새로 고침 (오프라인 액세스)을 참조하십시오.

인증 요청 에서 prompt 매개 변수를 consent 로 설정하여 사용자에게 앱을 다시 승인하라는 메시지를 표시 할 수 있습니다. prompt=consent 가 포함되면 모든 범위가 이전에 Google API 프로젝트에 부여 된 경우에도 앱이 액세스 범위 승인을 요청할 때마다 동의 화면이 표시됩니다. 이러한 이유로 필요한 경우에만 prompt=consent 포함하십시오.

prompt 매개 변수에 대한 자세한 내용은 인증 URI 매개 변수 표의 prompt 를 참조하십시오.

인증 URI 매개 변수

다음 표는 Google의 OAuth 2.0 인증 API에서 허용하는 매개 변수에 대한 자세한 설명을 제공합니다.

매개 변수 필수 기술
client_id (필수) OAuth 2.0 사용자 인증 정보 얻기에 설명 된대로 API Console Credentials page에서 얻은 클라이언트 ID 문자열입니다.
nonce (필수) 재생 보호를 활성화하는 앱에서 생성 된 임의의 값입니다.
response_type (필수) 값이 code 이면 토큰을 얻기 위해 토큰 끝점에 대한 POST 를 요구하는 기본 인증 코드 흐름을 시작합니다. 값이 token id_token 또는 id_token token 이면 암시 적 흐름을 시작하여 URI #fragment 식별자 에서 토큰을 검색하려면 리디렉션 URI에서 JavaScript를 사용해야합니다.
redirect_uri (필수) 응답이 전송되는 위치를 결정합니다. 이 매개 변수의 값은 API Console Credentials page에서 설정 한 승인 된 리디렉션 값 중 하나와 정확히 일치해야합니다 (HTTP 또는 HTTPS 체계, 대소 문자 및 후행 '/'포함).
scope (필수)

범위 매개 변수는 openid 값으로 시작하고 profile 값, email 값 또는 둘 다를 포함해야합니다.

profile 범위 값이있는 경우 ID 토큰에 사용자의 기본 profile 클레임을 포함 할 수 있지만 보장되지는 않습니다.

email 범위 값이있는 경우 ID 토큰에는 emailemail_verified 클레임이 포함됩니다.

이러한 OpenID 특정 범위 외에도 범위 인수에 다른 범위 값이 포함될 수 있습니다. 모든 범위 값은 공백으로 구분되어야합니다. 예를 들어 사용자의 Google 드라이브에 대한 파일 별 액세스를 원하는 경우 범위 매개 변수는 openid profile email https://www.googleapis.com/auth/drive.file 일 수 있습니다.

사용 가능한 범위에 대한 자세한 내용은 Google API 용 OAuth 2.0 범위 또는 사용하려는 Google API 설명서를 참조하세요.

state (선택 사항이지만 적극 권장)

프로토콜에서 라운드 트립되는 불투명 한 문자열입니다. 즉, 기본 흐름에서는 URI 매개 변수로 반환되고 암시 적 흐름에서는 URI #fragment 식별자로 반환됩니다.

state 는 요청과 응답을 연관시키는 데 유용 할 수 있습니다. redirect_uri 를 추측 할 수 있기 때문에 state 값을 사용하면 들어오는 연결이 앱에서 시작한 인증 요청의 결과라는 확신을 높일 수 있습니다. 이 state 변수에서 임의의 문자열생성 하거나 일부 클라이언트 상태 (예 : 쿠키)의 해시를 인코딩하면 요청과 응답이 동일한 브라우저에서 시작되었는지 추가로 확인하기 위해 응답의 유효성을 검사 할 수 있습니다. 이것은 교차 사이트 요청 위조와 같은 공격으로부터 보호합니다.

access_type (선택 과목) 허용되는 값은 offlineonline 입니다. 효과는 오프라인 액세스에 설명되어 있습니다. 액세스 토큰이 요청되는 경우 클라이언트는 offline 값을 지정하지 않는 한 새로 고침 토큰을 수신하지 않습니다.
display (선택 과목) 권한 부여 서버가 인증 및 동의 사용자 인터페이스 페이지를 표시하는 방법을 지정하는 ASCII 문자열 값입니다. 다음 값이 지정되고 Google 서버에서 허용되지만 page , popup , touchwap 은 동작에 영향을주지 않습니다.
hd (선택 과목)

hd (호스팅 된 도메인) 매개 변수는 G Suite 호스팅 계정의 로그인 프로세스를 간소화합니다. G Suite 사용자의 도메인 (예 : mycollege.edu )을 포함하여 계정 선택 UI가 해당 도메인의 계정에 최적화되어야 함을 나타낼 수 있습니다. 일반적으로 하나의 도메인 대신 G Suite 계정을 최적화하려면 별표 ( * ) : hd=* 값을 설정합니다.

클라이언트 측 요청을 수정할 수 있으므로 앱에 액세스 할 수있는 사용자를 제어하기 위해이 UI 최적화에 의존하지 마세요. 확인하는 유효성토큰을 반환 IDhd 경기가 예상 무엇을 주장 값 (예 mycolledge.edu ). 요청 매개 변수와 달리 ID 토큰 hd 클레임은 Google의 보안 토큰에 포함되어 있으므로 값을 신뢰할 수 있습니다.

include_granted_scopes (선택 과목) 이 매개 변수가 true 값과 함께 제공되고 권한 요청이 부여 된 경우 권한에는 다른 범위에 대해이 사용자 / 애플리케이션 조합에 부여 된 이전 권한이 포함됩니다. 증분 인증을 참조하십시오.

설치된 앱 흐름으로는 증분 인증을 수행 할 수 없습니다.

login_hint (선택 과목) 앱이 인증하려는 사용자를 알고 있으면이 매개 변수를 인증 서버에 대한 힌트로 제공 할 수 있습니다. 이 힌트를 전달하면 계정 선택기가 표시되지 않고 로그인 양식의 이메일 상자가 미리 채워지거나 적절한 세션 (사용자가 멀티 로그인을 사용하는 경우)을 선택하여 앱에서 발생하는 문제를 방지 할 수 있습니다. 잘못된 사용자 계정에 로그인합니다. 값은 이메일 주소 또는 사용자의 Google ID에 해당하는 sub 문자열 일 수 있습니다.
prompt (선택 과목) 권한 부여 서버가 사용자에게 재 인증 및 동의를 요청하는지 여부를 지정하는 공백으로 구분 된 문자열 값 목록입니다. 가능한 값은 다음과 같습니다.
  • none

    권한 부여 서버는 인증 또는 사용자 동의 화면을 표시하지 않습니다. 사용자가 아직 인증되지 않았고 요청 된 범위에 대한 동의를 미리 구성하지 않은 경우 오류를 반환합니다. none 을 사용하여 기존 인증 및 / 또는 동의를 확인할 수 있습니다.

  • consent

    권한 부여 서버는 정보를 클라이언트에 반환하기 전에 사용자에게 동의를 요청합니다.

  • select_account

    권한 부여 서버는 사용자에게 사용자 계정을 선택하라는 메시지를 표시합니다. 이를 통해 권한 부여 서버에 여러 계정을 가진 사용자는 현재 세션이있을 수있는 여러 계정 중에서 선택할 수 있습니다.

값이 지정되지 않고 사용자에게 이전에 액세스 권한이 부여되지 않은 경우 사용자에게 동의 화면이 표시됩니다.

ID 토큰 유효성 검사

Google에서 직접 온 것을 알지 못하는 경우 서버의 모든 ID 토큰을 확인해야합니다. 예를 들어 서버는 클라이언트 앱에서 수신하는 모든 ID 토큰을 인증해야합니다.

다음은 서버에 ID 토큰을 보낼 수있는 일반적인 상황입니다.

  • 인증이 필요한 요청과 함께 ID 토큰을 보냅니다. ID 토큰은 요청을하는 특정 사용자와 해당 ID 토큰이 부여 된 클라이언트를 알려줍니다.

ID 토큰은 민감하며 가로 채면 오용 될 수 있습니다. 이러한 토큰은 HTTPS를 통해서만 전송하고 POST 데이터 또는 요청 헤더 내에서만 전송하여 안전하게 처리되도록해야합니다. 서버에 ID 토큰을 저장하는 경우에도 안전하게 저장해야합니다.

ID 토큰을 유용하게 만드는 한 가지는 앱의 여러 구성 요소에 전달할 수 있다는 사실입니다. 이러한 구성 요소는 앱과 사용자를 인증하는 경량 인증 메커니즘으로 ID 토큰을 사용할 수 있습니다. 그러나 ID 토큰의 정보를 사용하거나 사용자가 인증 한 어설 션으로 사용하려면 먼저 유효성을 검사 해야 합니다.

ID 토큰의 유효성 검사에는 여러 단계가 필요합니다.

  1. 발급자가 ID 토큰에 올바르게 서명했는지 확인합니다. Google에서 발급 한 토큰은 Discovery 문서jwks_uri 메타 데이터 값에 지정된 URI에있는 인증서 중 하나를 사용하여 서명됩니다.
  2. ID 토큰의 iss 클레임 값이 https://accounts.google.com 또는 accounts.google.com 과 같은지 https://accounts.google.com accounts.google.com .
  3. ID 토큰의 aud 클레임 값이 앱의 클라이언트 ID와 같은지 확인합니다.
  4. ID 토큰의 만료 시간 ( exp 클레임)이 exp 않았는지 확인합니다.
  5. 요청에 hd 매개 변수 값을 지정한 경우 ID 토큰에 허용 된 G Suite 호스팅 도메인과 일치하는 hd 클레임이 있는지 확인합니다.

2 ~ 5 단계에는 매우 간단한 문자열 및 날짜 비교 만 포함되므로 여기서 자세히 설명하지 않겠습니다.

첫 번째 단계는 더 복잡하며 암호화 서명 검사를 포함합니다. 디버깅 목적으로 Google의 tokeninfo 엔드 포인트를 사용하여 서버 또는 기기에 구현 된 로컬 처리와 비교할 수 있습니다. ID 토큰의 값이 XYZ123 이라고 가정합니다. 그런 다음 URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 역 참조합니다. 토큰 서명이 유효한 경우 응답은 디코딩 된 JSON 개체 형식의 JWT 페이로드입니다.

tokeninfo 엔드 포인트는 디버깅에 유용하지만 프로덕션 목적으로 키 엔드 포인트에서 Google의 공개 키를 검색하고 로컬에서 유효성 검사를 수행합니다. jwks_uri 메타 데이터 값을 사용하여 Discovery 문서 에서 키 URI를 검색해야합니다. 디버깅 끝점에 대한 요청이 제한되거나 간헐적 인 오류가 발생할 수 있습니다.

Google은 공개 키를 자주 변경하지 tokeninfo HTTP 응답의 캐시 지시문을 사용하여이를 캐시 할 수 있으며 대부분의 경우 tokeninfo 엔드 포인트를 사용하는 것보다 훨씬 효율적으로 로컬 유효성 검사를 수행 할 수 있습니다. 이 유효성 검사를 수행하려면 인증서를 검색 및 구문 분석하고 서명을 확인하기위한 적절한 암호화 호출을 수행해야합니다. 다행히도이를 수행하기 위해 다양한 언어로 제공되는 잘 디버깅 된 라이브러리가 있습니다 ( jwt.io 참조).

사용자 프로필 정보 얻기

사용자에 대한 추가 프로필 정보를 얻으려면 액세스 토큰 (응용 프로그램이 인증 흐름 중에 수신함) 및 OpenID Connect 표준을 사용할 수 있습니다.

  1. OpenID를 준수하려면 인증 요청openid profile 범위 값을 포함해야합니다.

    당신이 사용자의 이메일 주소를 포함 할 경우의 추가 범위의 값을 지정할 수 있습니다 email . profileemail 모두 지정하려면 인증 요청 URI에 다음 매개 변수를 포함 할 수 있습니다.

    scope=openid%20profile%20email
  2. 권한 헤더에 액세스 토큰을 추가하고 userinfo_endpoint 메타 데이터 값을 사용하여 Discovery 문서 에서 검색해야하는 userinfo 엔드 포인트에 HTTPS GET 요청을 수행합니다. userinfo 응답에는 OpenID Connect Standard Claims 및 Discovery 문서의 claims_supported 메타 데이터 값에 설명 된대로 사용자에 대한 정보가 포함됩니다. 사용자 또는 해당 조직은 특정 필드를 제공하거나 보류하도록 선택할 수 있으므로 승인 된 액세스 범위에 대한 모든 필드에 대한 정보를 얻지 못할 수 있습니다.

디스커버리 문서

OpenID Connect 프로토콜은 사용자를 인증하고 토큰, 사용자 정보 및 공개 키를 포함한 리소스를 요청하기 위해 여러 끝점을 사용해야합니다.

구현을 단순화하고 유연성을 높이기 위해 OpenID Connect는 인증 URI를 포함하여 OpenID Connect 제공자의 구성에 대한 세부 사항을 제공하는 키-값 쌍을 포함하는 잘 알려진 위치에서 발견되는 JSON 문서 인 "검색 문서"를 사용할 수 있습니다. , 토큰, 해지, 사용자 정보 및 공개 키 끝점. Google의 OpenID Connect 서비스에 대한 Discovery 문서는 다음에서 검색 할 수 있습니다.

https://accounts.google.com/.well-known/openid-configuration

Google의 OpenID Connect 서비스를 사용하려면 Discovery-document URI ( https://accounts.google.com/.well-known/openid-configuration )를 애플리케이션에 하드 코딩해야합니다. 애플리케이션은 문서를 가져오고 응답에 캐싱 규칙을 적용한 다음 필요에 따라 문서에서 엔드 포인트 URI를 검색합니다. 예를 들어 사용자를 인증하기 위해 코드는 다음으로 전송되는 인증 요청의 기본 URI로 authorization_endpoint 메타 데이터 값 (아래 예의 https://accounts.google.com/o/oauth2/v2/auth 을 검색합니다. 구글.

다음은 그러한 문서의 예입니다. 필드 이름은 OpenID Connect Discovery 1.0에 지정된 이름입니다 (의미에 대해서는 해당 문서 참조). 값은 실제 Google Discovery 문서의 최신 버전에서 복사되었지만 순전히 설명 용이며 변경 될 수 있습니다.

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Discovery 문서의 값을 캐싱하여 HTTP 왕복을 피할 수 있습니다. 표준 HTTP 캐싱 헤더가 사용되며이를 준수해야합니다.

클라이언트 라이브러리

다음 클라이언트 라이브러리는 인기있는 프레임 워크와 통합하여 OAuth 2.0 구현을 더 간단하게 만듭니다.

OpenID Connect 규정 준수

Google의 OAuth 2.0 인증 시스템은 OpenID Connect Core 사양의 필수 기능 을 지원합니다. OpenID Connect와 함께 작동하도록 설계된 모든 클라이언트는이 서비스와 상호 운용되어야합니다 ( OpenID 요청 객체 제외).