ACL AWS IAM 인증 메서드 구성 참조

ACL AWS IAM 인증 메서드 구성 참조 (ACL AWS IAM Auth Method Configuration Reference)

AWS Identity and Access Management(IAM) 인증 메서드 유형을 사용하면 AWS IAM 역할과 사용자로 Consul에 인증해 Consul 토큰을 얻을 수 있어요. 이 페이지는 해당 인증 메서드의 구성 매개변수와 인증 절차를 설명해요.

출처: 문서

본문

AWS Identity and Access Management(IAM) 인증 메서드 유형을 사용하면 AWS IAM 역할과 사용자로 Consul에 인증해 Consul 토큰을 얻을 수 있어요.

이 페이지는 AWS IAM에 대한 일반 지식과 주요 인증 메서드 문서에 설명된 개념을 가정해요.

개요 (Overview)

Consul의 AWS IAM 인증 메서드는 Vault의 IAM 인증 메서드에서 사용하는 접근 방식의 변형을 사용해요. 특히 Consul의 IAM 인증 메서드는 클라이언트가 사전 서명된 AWS API 요청을 제공하도록 요구함으로써 Consul 서버에 AWS 자격 증명을 구성할 필요를 없애요.

IAM 역할이나 사용자는 특정 JSON 형식의 일부 서명된 AWS API 요청을 제시해 인증해요. 클라이언트는 AWS Signature v4 알고리즘을 사용해 자신의 AWS 자격 증명으로 필요한 AWS API 요청에 서명해요. 인증 메서드가 서명된 AWS API 요청을 받으면 AWS로 요청을 전달해요. AWS는 클라이언트의 서명을 검증하고, 서명이 유효하면 클라이언트의 ID 세부 정보로 응답해요. sts:GetCallerIdentity 요청에 대해 AWS가 수행하는 서명 검증은 인증 메서드에 클라이언트 ID에 대한 강력한 보증을 제공해요. 인증 메서드는 클라이언트의 Amazon 리소스 이름(ARN)을 BoundIAMPrincipalARNs 목록과 비교해 클라이언트가 로그인할 수 있는지 결정해요.

구성 매개변수 (Config parameters)

다음은 aws-iam 유형의 인증 메서드에 대한 Config 매개변수예요:

  • BoundIAMPrincipalARNs (array<string>: <required>) — 로그인이 허용된 IAM 역할 또는 IAM 사용자 ARN 목록이에요. Consul에 인증하는 클라이언트는 이 목록의 ARN 중 하나와 일치하는 ARN을 가져야 해요.
    • EnableIAMEntityDetails=false인 경우 바운드 ARN은 역할 또는 사용자의 전체 경로를 포함해서는 안 되며 와일드카드는 지원되지 않아요. 예를 들어 arn:aws:iam::123456789012:user/MyUserName은 "MyUserName"이라는 IAM 사용자가 로그인하도록 허용하고, arn:aws:iam::123456789012:role/MyRoleName은 "MyRoleName"이라는 IAM 역할이 로그인하도록 허용해요.
    • EnableIAMEntityDetails=true인 경우 전체 경로가 있는 바운드 ARN을 사용해야 해요(예: arn:aws:iam::123456789012:role/path/to/MyRoleName). 또한 ARN에는 단일 후행 와일드카드가 포함될 수 있어요. 예를 들어 arn:aws:iam::123456789012:*는 계정 123456789012의 모든 역할 또는 사용자가 로그인하도록 허용하고, arn:aws:iam::123456789012:role/path/to/roles/*는 /path/to/roles/ 경로의 역할만 허용해요.
  • EnableIAMEntityDetails (bool: <false>) — 인증 메서드가 태그와 전체 역할 또는 사용자 경로를 포함한 IAM 역할 또는 IAM 사용자 세부 정보를 가져올 수 있게 해요. 활성화하면 클라이언트는 consul login에 -aws-include-entity 옵션을 전달해야 해요. 또한 로그인을 시도하는 IAM 역할 또는 사용자는 자신을 검색하기 위해 각각 iam:GetRole 또는 iam:GetUser 권한이 있어야 해요. 이 설정은 IAM 사용자 또는 역할의 전체 경로와 태그를 가져오고 BoundIAMPrincipalARNs에서 와일드카드를 사용하기 위해 필요해요.
  • IAMEntityTags (array<string>: []) — IAM 역할 또는 사용자에서 검색되어 바인딩 규칙에 사용 가능해지는 태그 키 목록이에요. 태그는 EnableIAMEntityDetails=true일 때만 지원돼요. 기본적으로 바인딩 규칙에 사용 가능한 태그는 없어요. IAMEntityTags 목록의 각 태그는 바인딩 규칙에서 entity_tags.<tag>를 사용해 참조할 수 있어요. 예를 들어 IAMEntityTags에 service-name이 포함되고 IAM 역할 또는 사용자에 service-name 태그가 있으면 바인딩 규칙에서 entity_tags.service-name으로 태그 값을 참조할 수 있어요. 태그가 IAM 역할 또는 사용자에 없으면 바인딩 규칙에서 entity_tags.service-name은 빈 문자열로 평가돼요.
  • ServerIDHeaderValue (string: "") — 로그인 요청의 X-Consul-IAM-ServerID 헤더에 요구되는 값이에요. 설정되면 클라이언트는 인증 메서드에 로그인하는 데 사용되는 AWS API 요청에 X-Consul-IAM-ServerID 헤더를 포함해야 하며, 성공적으로 로그인하려면 클라이언트가 제공한 헤더 값이 이 설정과 일치해야 해요. 설정하지 않으면 헤더가 요구되거나 검증되지 않아요. 이는 다양한 유형의 재생(replay) 공격(예: 개발 서버로 보낸 서명된 요청이 프로덕션 서버로 다시 전송되는 경우)으로부터 보호하는 데 사용할 수 있어요. Consul 서버의 DNS 이름으로 설정하는 것을 고려해요. 설정되면 클라이언트는 consul login 명령에 -aws-server-id-header-value 옵션을 전달해야 해요.
  • MaxRetries (integer: 0) — AWS API 요청을 할 때 복구 가능한 오류에 사용할 최대 재시도 횟수예요.
  • IAMEndpoint (string: "") — iam:GetRole 및 iam:GetUser 요청이 전송되는 URL이에요. 비공개 엔드포인트나 네트워크 프록시를 통해 요청을 보내는 데 사용할 수 있어요.
  • STSEndpoint (string: "") — sts:GetCallerIdentity 요청이 전송되는 URL이에요. 비공개 엔드포인트나 네트워크 프록시를 통해 요청을 보내는 데 사용할 수 있어요.
  • AllowedSTSHeaderValues (array<string>: []) — sts:GetCallerIdentity 요청에서 허용되는 추가 헤더 목록이에요. 어떤 경우든 AWS STS가 예상하는 기본 헤더 목록은 허용돼요.

샘플 (Sample)

{
    "Name": "example-iam-auth",
    "Type": "aws-iam",
    "Description": "Example AWS IAM auth method",
    "Config": {
      "BoundIAMPrincipalARNs": ["arn:aws:iam::123456789012:role/MyRoleName"],
      "EnableIAMEntityDetails": true,
      "IAMEntityTags": ["consul-namespace"],
      "ServerIDHeaderValue": "my.consul.server.example.com",
      "MaxRetries": 3,
      "IAMEndpoint": "https://iam.amazonaws.com/",
      "STSEndpoint": "https://sts.us-east-1.amazonaws.com/",
      "AllowedSTSHeaderValues": ["X-Extra-Header"]
    }
}

신뢰된 ID 속성 (Trusted identity attributes)

인증 단계는 바인딩 규칙 선택기와 바인드 이름 보간에 사용할 다음 신뢰된 ID 속성을 반환해요. 이 속성들은 모두 보간할 수 있는 문자열이며 다음 선택기 연산을 지원해요: Equal, Not Equal, In, Not In, Matches, Not Matches

속성 설명 요구 사항
entity_name IAM 역할 또는 사용자의 이름
entity_id IAM 역할 또는 사용자의 고유 ID
account_id IAM 역할 또는 사용자의 AWS 계정 ID
entity_path IAM 역할 또는 사용자의 경로 EnableIAMEntityDetails=true
entity_tags.<key> IAM 역할 또는 사용자에 있는 태그의 값 EnableIAMEntityDetails=true 및 IAMEntityTags에 <key> 포함

IAM 정책 (IAM policies)

EnableIAMEntityDetails=false일 때는 특정 IAM 정책이 필요하지 않아요.

EnableIAMEntityDetails=true일 때 인증하는 클라이언트는 서명된 iam:GetRole 또는 iam:GetUser 요청을 제공해야 해요. 이 요청은 클라이언트의 AWS 자격 증명으로 서명되므로 클라이언트는 각각 역할 또는 사용자를 가져올 권한이 있어야 해요.

  • 인증하는 클라이언트가 IAM 역할이라면 클라이언트는 자신의 역할을 가져오기 위한 iam:GetRole 권한이 있어야 해요. 다음은 이 권한을 부여하는 AWS IAM 정책 문서의 예시예요:
{
  "Statement": [
      {
          "Action": ["iam:GetRole"],
          "Effect": "Allow",
          "Resource": ["arn:aws:iam::123456789012:role/MyRoleName"]
      }
  ],
  "Version": "2012-10-17"
}
  • 인증하는 클라이언트가 IAM 사용자라면 클라이언트는 자신의 역할을 가져오기 위한 iam:GetUser 권한이 있어야 해요. 다음은 이 권한을 부여하는 AWS IAM 정책 문서의 예시예요:
{
  "Statement": [
      {
          "Action": ["iam:GetUser"],
          "Effect": "Allow",
          "Resource": ["arn:aws:iam::123456789012:user/MyUserName"]
      }
  ],
  "Version": "2012-10-17"
}

인증 절차 (Authentication procedure)

EnableIAMEntityDetails=false라면 클라이언트는 다음 consul login 명령으로 로그인해야 해요.

$ consul login -type aws-iam -aws-auto-bearer-token ...

이 명령은 다음을 수행해요:

  • sts:GetCallerIdentity 요청 형식을 만들고 서명
  • 요청 세부 정보를 JSON으로 형식화해 bearer 토큰 생성
  • bearer 토큰을 IAM 인증 메서드로 보내 인증

그렇지 않고 EnableIAMEntityDetails=true라면 클라이언트는 bearer 토큰에 서명된 iam:GetRole 또는 iam:GetUser 요청을 포함하기 위해 다음 consul login 명령으로 로그인해야 해요.

$ consul login -type aws-iam -aws-auto-bearer-token -aws-include-entity ...

이 명령은 다음을 수행해요:

  • sts:GetCallerIdentity 요청을 만들어 자신의 역할 또는 사용자 이름을 결정
  • 새 sts:GetCallerIdentity 요청 형식을 만듦
  • sts:GetCallerIdentity 요청의 헤더에 서명된 iam:GetRole 또는 iam:GetUser 요청을 포함
  • sts:GetCallerIdentity 요청에 서명
  • 요청 세부 정보를 JSON으로 형식화해 bearer 토큰 생성
  • bearer 토큰을 IAM 인증 메서드로 보내 인증

Consul 서버에서 IAM 인증 메서드는 인증 메서드에 로그인(Login to Auth Method) API 요청 중에 다음 단계를 사용해 클라이언트의 ID를 검증해요:

  • bearer 토큰에서 sts:GetCallerIdentity 요청을 디코딩
  • 선택적으로, 인증 메서드 구성에서 EnableIAMEntityDetails=true인 경우 bearer 토큰에서 iam:GetRole 또는 iam:GetUser 요청을 디코딩
  • sts:GetCallerIdentity 요청을 AWS로 전송. 이 요청은 클라이언트가 사전 서명하므로 이 요청을 만드는 데 다른 자격 증명이나 권한이 필요하지 않아요. AWS는 요청을 받으면 클라이언트의 서명을 검증해요. 서명이 유효하면 AWS는 응답에서 클라이언트의 ID를 반환해요. 이는 클라이언트 ID에 대한 강력한 보증이에요.
  • 선택적으로, 인증 메서드 구성에서 EnableIAMEntityDetails=true인 경우 인증 메서드는 iam:GetRole 또는 iam:GetUser 요청을 AWS로 전송해요. 이 요청은 클라이언트가 사전 서명하므로 요청을 만드는 데 다른 자격 증명이나 권한이 필요하지 않아요. iam:GetRole 또는 iam:GetUser 권한이 필요한 것은 클라이언트뿐이에요. AWS는 요청을 받으면 클라이언트의 서명을 검증해요. 서명이 유효하면 AWS는 IAM 역할 또는 사용자 세부 정보를 반환해요. 이 응답은 클라이언트 ID를 보장하지 않아요. 요청에 어떤 역할이나 사용자 이름도 포함될 수 있기 때문이에요. 따라서 인증 메서드는 IAM 역할 또는 사용자가 sts:GetCallerIdentity 응답과 고유 ID 일치하도록 요구해요.
  • 마지막으로 인증 메서드는 인증 결정을 내려요. 클라이언트의 IAM 역할 또는 사용자 ARN이 구성된 BoundIAMPrincipalARNs 중 하나와 일치하면 클라이언트는 로그인할 수 있어요.

더 알아보기 (Learn more)