OIDC 인증에 Okta 사용하기
OIDC 인증에 Okta 사용하기
- Authorization Server가 생성되었는지 확인합니다. Setting 페이지에 표시된 "Issuer" 필드가
oidc_discovery_url로 사용될 거예요. - Applications > Add Application (Web)을 방문합니다.
- Login redirect URIs를 구성합니다. 저장합니다.
- 클라이언트 ID와 시크릿을 저장합니다.
완전한 프로필("Fat Token")을 얻으려면 정책에 oidc_scopes가 profile을 포함해야 한다는 점을 기억하세요. 기본 인증 서버를 사용한다면 "bound_audiences": ["api://default", "0a4........."] 같은 줄로 bound audience도 구성해야 해요.
출처: 문서
본문
선택적 Okta 전용 구성 (Optional Okta-specific configuration)
Okta는 기본 인증 서버 그룹 클레임 한도(100개 이상 그룹)에 속하는 사용자의 ID 토큰에서 groups 클레임을 조용히 잘라내요. Vault는 잘림이 발생할 때를 감지하고 Okta Groups API에서 완전한 그룹 목록을 직접 검색하는 Okta 전용 처리를 제공해요.
설정 (Setup)
Okta 전용 처리를 설정하려면 다음이 필요해요.
- 전용 Okta 서비스 계정 사용자. Okta Admin Console의 Directory > People > Add person 아래에 만드세요. 개인 관리자 계정보다 전용 서비스 계정을 강력히 권장해요.
- 그 서비스 계정에 할당된 사용자 지정 관리자 역할로, View users and their details와 View groups and their details만 부여하세요. Okta Admin Console의 Security > Administrators > Create new role 아래에서 사용자 지정 역할을 만들고 할당하세요. 내장 Read-Only Administrator 역할도 작동하지만 필요 이상으로 더 넓은 접근을 부여해요.
- 그 서비스 계정에 대해 Okta Admin Console의 Security > API > Tokens 아래에서 생성된 Okta API 토큰(SSWS). 생성 직후 토큰 값을 복사하세요.
Vault는 SSWS API 토큰으로 Okta Groups 엔드포인트(/api/v1/users/{userId}/groups)에 인증해 잘린 groups 클레임을 처리해요. 인증 제약은 Vault가 아니라 Okta에서 오는 것이에요. Groups 엔드포인트는 관리자 전용이므로, 부여된 okta.* 스코프와 무관하게 Vault는 최종 사용자 OAuth 액세스 토큰을 사용할 수 없어요.
구성 (Configuration)
provider(string: <required>)— 프로바이더 이름."okta"로 설정해야 해요.fetch_groups(bool: false)—fetch_groups가false이면 Vault는 항상 ID 토큰에 있는 그룹을 사용하는데, 100개 이상 그룹의 사용자에게는 불완전할 수 있어요.fetch_groups가true이면 Vault는 ID 토큰의groups클레임이 없거나groups_cap에 도달했는지 확인해요. 클레임을 사용할 수 없으면 Vault는 Okta Groups API에서 완전한 그룹 목록을 가져와요.org_url(string: "")—https://를 포함한 전체 Okta org 기본 URL. 예:https://example.okta.com.org_url을 설정하지 않으면 Vault는oidc_discovery_url에서 스킴과 호스트를 사용하되/oauth2/...같은 사용자 지정 authorization server 경로는 제거해 URL을 파생해요. OIDC discovery URL이 vanity 도메인이나 Okta org와 다른 다른 도메인을 사용할 때만 org URL을 명시적으로 설정하면 돼요.api_token(string: "")— 서비스 계정의 Okta API 토큰(SSWS).fetch_groups가true일 때 Vault는 API 토큰을 요구해요. API 토큰을 설정하지 않으면groups_cap에 도달하는 사용자의 로그인 시 Vault는 인증 오류를 반환해요. Vault는 API 토큰을 민감 필드로 취급하고 감사 로그와vault read출력에서 값을 마스킹해요.user_id_claim(string: <user_claim>)— Okta API 호출에서 사용자를 식별하는 ID 토큰 클레임. Okta는 사용자 ID, 로그인(이메일/UPN), 또는 고유 로그인 단축 이름을 수락해요.groups_cap(int: 100)— Vault가groups클레임을 잠재적으로 잘렸다고 취급하는 임계값. 클레임이 없거나 그 길이가groups_cap과 같으면fetch_groups가true일 때 Vault는 Okta API에서 완전한 목록을 가져와요. cap 값은 Okta authorization server에 구성된 그룹 클레임 한도와 일치해야 해요.groups_filter(string: "")— Vault가 정책 매핑에 수락하는 그룹 이름을 정의하는 Go 정규식. Vault는 ID 토큰과 Okta API에서 온 그룹에 필터를 일관되게 적용해요. 필터링은 사용자가 많은 Okta 그룹에 속하지만 하위 집합만 Vault에 관련이 있을 때 유용해요. Okta가 반환하는 모든 그룹을 통과시키려면groups_filter를 설정하지 않은 채로 두세요.
예시 구성:
vault write auth/oidc/config - <<EOF
{
"oidc_discovery_url": "https://example.okta.com/oauth2/default",
"oidc_client_id": "your_client_id",
"oidc_client_secret": "your_client_secret",
"default_role": "your_default_role",
"provider_config": {
"provider": "okta",
"fetch_groups": true,
"org_url": "https://example.okta.com",
"api_token": "00ABCxyz...",
"groups_cap": 100,
"user_id_claim": "sub",
"groups_filter": "^vault-"
}
}
EOF
역할 (Role)
Vault는 provider_config에서 user_id_claim을 비워 두면 Okta API 조회의 폴백 사용자 식별자로 역할의 user_claim 값을 사용해요. user_claim을 Okta가 사용자 식별자로 수락하는 클레임(예: email)으로 설정하세요.
예시 역할:
vault write auth/oidc/role/your_default_role \
allowed_redirect_uris="http://localhost:8200/ui/vault/auth/oidc/oidc/callback,http://localhost:8250/oidc/callback" \
user_claim="sub" \
groups_claim="groups" \
oidc_scopes="openid profile groups email" \
bound_audiences="api://default,0a4........." \
policies="default"