로그인 프로토콜 레퍼런스

로그인 프로토콜 레퍼런스 (Login Protocol Reference)

이 주제는 Terraform이 Terraform 네이티브 서비스를 제공하는 서버에 대해 인증할 때 사용하는 로그인 프로토콜에 대한 레퍼런스 정보를 제공해요. 이 레퍼런스 정보를 사용해 타사 시스템에서 Terraform 네이티브 서비스를 제공할 수 있어요.

출처: 문서

본문

소개 (Introduction)

terraform login 명령은 대상 호스트가 제공하는 구성을 사용해 OAuth 2.0 권한 부여 요청을 수행하는 것을 지원해요. Terraform 모듈 레지스트리 같은 Terraform 네이티브 서비스를 타사로 구현한다면 이 프로토콜을 구현할 수 있어요.

OAuth 구성 (OAuth Configuration)

Terraform은 원격 서비스 발견을 사용해 호스트의 OAuth 구성을 찾아요. 호스트는 login.v1 서비스 이름을 지원하고 여기에 OAuth 클라이언트 구성 값을 담은 객체를 정의해야 해요. 다음 예시는 포트 10000과 10010에서 인증하는 클라이언트를 설명해요.

{
  "login.v1": {
    "client": "terraform-cli",
    "grant_types": ["authz_code"],
    "authz": "/oauth/authorization",
    "token": "/oauth/token",
    "ports": [10000, 10010],
  }
}

발견 객체 안의 속성은 다음과 같아요.

  • client (필수): 요청 시 사용할 client_id 값으로, RFC 6749 섹션 2.2에 정의된 대로예요.
    • Terraform은 *공개 클라이언트(public client)*이므로(최종 사용자 시스템에 설치되어 OAuth 클라이언트 시크릿을 보호할 수 없어요) client_id는 순전히 참고용이며, 서버는 이것을 권한 부여 요청이 진짜 Terraform에서 온 것임을 보장하는 것으로 사용해서는 안 돼요.
  • grant_types (선택): 서버가 지원할 수 있는 OAuth 2.0 grant 타입 집합을 설명하는 JSON 문자열 배열. "grant type"은 OAuth 서버가 요청을 인증하고 권한 토큰을 발급하는 특정 메커니즘을 선택해요.
    • Terraform CLI는 단일 grant 타입을 지원해요: authz_code — authorization code grant. authz_code가 있으면 authz와 token 속성이 모두 필요해요.
    • 지정하지 않으면 grant_types는 ["authz_code"]로 기본 설정돼요.
  • authz (주어진 grant 타입에 필요하면 필수): 서버의 authorization endpoint. 상대 URL로 주어지면 서비스 발견 문서의 위치에서 해석돼요.
  • token (주어진 grant 타입에 필요하면 필수): 서버의 token endpoint. 상대 URL로 주어지면 서비스 발견 문서의 위치에서 해석돼요.
  • ports (선택): authorization code grant의 첫 단계를 위한 리다이렉션 엔드포인트를 제공하기 위해 Terraform이 시작할 임시 HTTP 서버에 사용할 수 있는 TCP 포트의 포함 범위를 주는 두 요소 JSON 배열. Terraform은 서버의 authorization endpoint에서 응답을 받기 위해 루프백 인터페이스에 TCP 수신 포트를 엽니다.
    • 지정하지 않으면 Terraform은 1024 이상의 어떤 TCP 포트든 선택할 수 있어요.
    • Terraform은 OAuth 서버 구현과의 상호 운용을 위해 이 포트 범위를 제한할 수 있어요. 각 client_id가 고정된 유효한 리다이렉션 엔드포인트 URL 집합과 연결되도록 요구하는 구현이 그런 경우예요. http://localhost:10000/ 형태의 연속적인 다른 포트 번호를 가진 URL 범위를 기대하도록 서버를 구성한 다음, ports로 그 포트 범위를 지정해요.
    • 가능하면 최소 10개의 서로 다른 포트 번호를 허용하고, 특정 시스템에서 가능한 모든 포트가 이미 사용 중일 위험을 최소화하기 위해 10000 이상의 번호에 할당할 것을 권장해요.

authorization code grant를 요청할 때 Terraform CLI는 리다이렉션 엔드포인트에 들어오는 요청을 시스템의 다른 애플리케이션이 가로채는 것을 방지하기 위해 Proof Key for Code Exchange 확장을 구현해요. 이 확장도 구현하고 token endpoint로 보내진 code challenge를 검증하는 OAuth 서버 구현을 선택할 것을 강력히 권장해요.

Terraform CLI는 OAuth refresh 토큰이나 토큰 만료를 지원하지 않아요. 서버가 시간 제한 토큰을 발급한다면, 토큰이 만료된 후 Terraform CLI는 권한 부여 오류를 받기 시작하며, 그 후 사용자는 새로운 토큰을 얻기 위해 terraform login을 다시 실행할 수 있어요.

참고: 특별한 경우로, Terraform은 app.terraform.io(HCP Terraform)와 상호작용할 때만 Resource Owner Password Credentials Grant를 사용할 수 있어요. 이는 OAuth 사양이 클라이언트와 서버가 밀접하게 관련될 때만 이 grant 타입을 사용하라고 권장하기 때문이에요. password grant 타입은 다른 어떤 호스트 이름에서도 지원되지 않으며 무시돼요.

더 알아보기 (Learn more)