토큰 유형

이 페이지에서는 Google API, Google Cloud 서비스, Google Cloud에 호스팅된 고객 생성 서비스에 대한 인증에 사용되는 토큰 유형에 대해 설명합니다.

클라이언트 라이브러리를 사용하여 Google API 및 서비스에 액세스하는 경우 애플리케이션 기본 사용자 인증 정보를 설정할 수 있고 클라이언트 라이브러리가 토큰을 처리합니다. 이것이 권장 방법입니다.

토큰이란 무엇인가요?

인증 및 승인의 경우 토큰은 요청을 수행하는 주 구성원의 ID 및 이들에게 승인된 액세스 종류에 대한 정보가 포함된 디지털 객체입니다. 대부분의 인증 흐름에서 애플리케이션 또는 애플리케이션에 사용되는 라이브러리는 애플리케이션이 액세스하도록 승인된 리소스를 결정하는 토큰에 대한 사용자 인증 정보를 교환합니다.

토큰 유형

서로 다른 환경에서 다양한 유형의 토큰이 사용됩니다. 이 페이지에서는 다음과 같은 토큰 유형에 대해 설명합니다.

이 페이지에서는 사용자 인증 정보로 고려되는 API 키 또는 클라이언트 ID에 대해 설명하지 않습니다.

액세스 토큰

액세스 토큰은 OAuth 2.0 프레임워크를 준수하는 불투명 토큰입니다. 여기에 승인 정보가 포함되지만 ID 정보는 포함되지 않습니다. 인증을 수행하고 Google API에 승인 정보를 제공하기 위해 사용됩니다.

애플리케이션 기본 사용자 인증 정보(ADC) 및 Cloud 클라이언트 라이브러리 또는 Google API 클라이언트 라이브러리를 사용하는 경우 액세스 토큰을 관리할 필요가 없습니다. 라이브러리가 사용자 인증 정보를 자동으로 검색하고, 액세스 토큰으로 교환하고, 필요에 따라 액세스 토큰을 새로고침합니다.

액세스 토큰 콘텐츠

액세스 토큰은 불투명 토큰이며, 이는 독점적 형식임을 의미합니다. 애플리케이션이 이를 검사할 수 없습니다. Google OAuth 2.0 tokeninfo 엔드포인트를 사용하여 유효한(만료되거나 취소되지 않은) 액세스 토큰에서 정보를 가져올 수 있습니다.

ACCESS_TOKEN을 유효한 만료되지 않은 액세스 토큰으로 바꿉니다.

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

이 명령어는 다음 예시와 비슷한 결과를 반환합니다.

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

다음 표에서는 알아야 할 가장 중요한 필드를 보여줍니다.

필드 설명
azp 토큰을 요청한 애플리케이션의 프로젝트, 이메일, 서비스 계정 ID입니다. 이 값은 범위 목록에 https://www.googleapis.com/auth/userinfo.email이 지정된 경우에만 포함됩니다.
scope 이 액세스 토큰에 추가된 OAuth 범위입니다. Google Cloud 서비스의 경우 권장사항은 세부적인 액세스 제어를 제공하는 Identity and Access Management(IAM)와 함께 모든 Google Cloud API를 포함하는 https://www.googleapis.com/auth/cloud-platform 범위를 사용하는 것입니다.
expires_in 토큰이 만료되기 전까지 시간(초)입니다. 자세한 내용은 액세스 토큰 수명을 참조하세요.

액세스 토큰 수명

기본적으로 액세스 토큰은 1시간(3,600초) 동안 유효합니다. 액세스 토큰이 만료되면 토큰 관리 코드가 새 토큰을 가져와야 합니다.

수명이 길거나 짧은 액세스 토큰이 필요한 경우 serviceAccounts.generateAccessToken 메서드를 사용하여 토큰을 만들 수 있습니다. 이 메서드를 사용하면 토큰 수명을 최대 12시간으로 선택할 수 있습니다.

토큰 수명을 기본값 이상으로 연장하려면 iam.allowServiceAccountCredentialLifetimeExtension 제약조건을 사용 설정하는 조직 정책을 만들어야 합니다. 사용자 인증 정보 또는 외부 ID에 대해서는 수명이 긴 액세스 토큰을 만들 수 없습니다. 자세한 내용은 단기 액세스 토큰 만들기를 참조하세요.

ID 토큰

ID 토큰은 OpenID Connect(OIDC) 사양을 준수하는 JSON 웹 토큰(JWT)입니다. 클레임이라는 키-값 쌍 집합으로 구성됩니다.

애플리케이션이 검사할 수 없는 불투명 객체인 액세스 토큰과 달리 ID 토큰은 애플리케이션에서 검사하고 사용하도록 되어 있습니다. 토큰에 서명한 사용자 또는 ID 토큰이 발급된 ID와 같은 토큰의 정보가 애플리케이션에서 사용하도록 제공됩니다.

Google의 OIDC 구현에 대한 자세한 내용은 OpenID Connect를 참조하세요. JWT 작업에 대한 권장사항은 JSON 웹 토큰 최신 권장사항을 참조하세요.

ID 토큰 콘텐츠

Google OAuth 2.0 tokeninfo 엔드포인트를 사용하여 유효한(만료되거나 취소되지 않은) ID 토큰을 검사할 수 있습니다.

ID_TOKEN을 유효한 만료되지 않은 ID 토큰으로 바꿉니다.

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

이 명령어는 다음 예시와 비슷한 결과를 반환합니다.

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

다음 표에서는 필수 또는 일반적으로 사용되는 ID 토큰 클레임에 대해 설명합니다.

클레임 설명
iss 토큰의 발급기관 또는 서명자입니다. Google 서명 ID 토큰의 경우 이 값은 https://accounts.google.com입니다.
azp 선택사항. 토큰이 발급된 대상입니다.
aud 토큰의 사용 대상입니다. 이 클레임의 값은 토큰을 사용하여 요청을 인증하는 애플리케이션 또는 서비스와 일치해야 합니다. 자세한 내용은 ID 토큰 aud 클레임을 참조하세요.
sub 제목: 요청을 수행하는 주 구성원을 나타내는 ID입니다.
iat 토큰이 발급된 Unix epoch 시간입니다.
exp 토큰이 만료되는 Unix epoch 시간입니다.

발급기관 및 애플리케이션에 따라 다른 클레임이 있을 수 있습니다.

ID 토큰 aud 클레임

aud 클레임은 이 토큰을 호출하기 위해 만든 서비스 이름을 설명합니다. 서비스에 ID 토큰이 수신되면 무결성(서명), 유효성(만료 여부), aud 클레임이 예상 이름과 일치하는지 여부를 확인해야 합니다. 일치하지 않으면 다른 시스템을 위한 재생일 수 있으므로 서비스가 토큰을 거부해야 합니다.

일반적으로 ID 토큰을 가져올 때는 사용자 인증 정보 대신 서비스 계정에서 제공된 사용자 인증 정보를 사용합니다. 사용자 인증 정보를 사용하여 생성된 ID 토큰에 대한 aud 클레임이 애플리케이션에 정적으로 바인딩되기 때문입니다. 서비스 계정을 사용하여 ID 토큰을 가져올 때는 aud 클레임에 대해 다른 값을 지정할 수 있습니다.

ID 토큰 수명

ID 토큰은 최대 1시간(3,600초) 동안 유효합니다. ID 토큰이 만료되면 새 항목을 가져와야 합니다.

ID 토큰 검증

서비스 또는 애플리케이션에 Cloud Run, Cloud Functions, IAP(Identity-Aware Proxy)와 같은 Google 서비스가 사용되는 경우 Google이 ID 토큰을 검증합니다. 이러한 경우 ID 토큰이 Google에서 서명되어야 합니다.

애플리케이션 내에서 ID 토큰을 검증해야 할 경우에는 고급 워크플로의 경우에도 이렇게 할 수 있습니다. 자세한 내용은 ID 토큰 검증을 참조하세요.

자체 서명 JSON 웹 토큰(JWT)

API 게이트웨이로 배포된 API를 인증하려면 자체 서명된 JWT가 필요합니다. 또한 승인 서버에서 액세스 토큰을 가져오지 않아도 자체 서명 JWT를 사용하여 일부 Google API를 인증할 수 있습니다.

Google API에 액세스하기 위해 자체 클라이언트 라이브러리를 만드는 경우에는 자체 서명 JWT를 만드는 것이 권장되지만, 고급 워크플로입니다. 자체 서명 JWT에 대한 자세한 내용은 자체 서명된 JSON 웹 토큰 만들기를 참조하세요. JWT 작업에 대한 권장사항은 JSON 웹 토큰 최신 권장사항을 참조하세요.

갱신 토큰

기본적으로 액세스 토큰과 ID 토큰은 1시간 동안 유효합니다. 갱신 토큰은 추가 액세스 토큰 또는 ID 토큰을 가져오기 위해 사용되는 특수 토큰입니다. 애플리케이션은 처음 인증될 때 액세스 토큰 또는 ID 토큰과 갱신 토큰을 받습니다. 나중에 애플리케이션이 리소스에 다시 액세스해야 하고 이전에 제공된 토큰이 만료되었으면 갱신 토큰을 사용하여 새 토큰을 요청합니다. 갱신 토큰은 Cloud ID 또는 Google Workspace와 같은 사용자 인증에만 사용됩니다.

갱신 토큰은 설정된 수명이 없습니다. 토큰이 만료될 수 있지만, 그렇지 않으면 계속 사용할 수 있습니다. Google Workspace 또는 Cloud ID Premium Edition에서 사용자 액세스의 경우 Google Cloud 서비스에 대한 액세스 권한을 유지하기 위해 사용자가 정기적으로 로그인하도록 세션 길이를 구성할 수 있습니다.

애플리케이션이 자체 토큰을 만들고 관리하는 경우 갱신 토큰도 관리해야 합니다. 자세한 내용은 다음 링크를 참조하세요.

제휴 토큰

제휴 토큰은 워크로드 아이덴티티 제휴에서 중간 단계로 사용됩니다. 제휴 토큰은 보안 토큰 서비스에서 반환되며 직접 사용할 수 없습니다. 서비스 계정 가장을 사용하여 액세스 토큰으로 교환해야 합니다.

Bearer 토큰

Bearer 토큰은 토큰을 소유한 사람에게 액세스 권한을 부여하는 일반적인 토큰 클래스입니다. 액세스 토큰, ID 토큰, 자체 서명 JWT는 모두 Bearer 토큰입니다.

인증에 Bearer 토큰을 사용하려면 HTTPS와 같은 암호화된 프로토콜로 제공되는 보안이 필요합니다. Bearer 토큰을 가로채면 악의적인 행위자가 이를 사용하여 액세스 권한을 얻을 수 있습니다.

Bearer 토큰이 사용 사례에 충분한 보안을 제공하지 않으면 또 다른 암호화 레이어를 추가하거나 BeyondCorp Enterprise와 같이 신뢰할 수 있는 기기의 인증된 사용자만으로 액세스를 제한하는 상호 전송 계층 보안(mTLS)을 사용하는 것이 좋습니다.

다음 단계