Grafana Entra ID OAuth 설정 가이드

개요

Microsoft Entra ID (구 Azure Active Directory)를 통해 Grafana에 OAuth 로그인을 연동함으로써, 조직의 통합 인증 환경을 구성할 수 있습니다. 본 가이드는 Helm 기반 Grafana 배포에 Entra ID OAuth를 적용하는 과정을 단계별로 설명합니다.

구성 요소 및 사전 요구 사항

Grafana 버전	11.4.0
배포 방식	Helm + Kustomize
인증 방식	Entra ID (OAuth 2.0, Authorization Code Grant)
리디렉션 URI	https://<도메인>/login/generic_oauth
Secret 방식	Kubernetes Secret + __file 방식

설정 단계

1. Azure Portal에서 앱 등록

1. Azure Portal 접속: https://portal.azure.com
2. Azure Active Directory → 앱 등록 → 새 등록
3. 설정:
   • 이름: Grafana OAuth
   • 리디렉션 URI: https://<Domain>/login/generic_oauth
   • 지원되는 계정 유형: 조직 디렉터리의 계정만
4. 등록 클릭

2. 클라이언트 ID와 시크릿 생성

1. 애플리케이션 ID (클라이언트 ID) 복사
2. 인증서 및 비밀 → 새 클라이언트 비밀
   • 설명: Grafana OAuth Secret
   • 만료: 24개월
   • 추가 → 값 복사 (이 값은 한 번만 표시됨)

3. 테넌트 ID 확인

1. Azure Active Directory → 개요
2. 테넌트 ID 복사

4. 도메인 확인

1. Azure Active Directory → 사용자
2. 사용자 이메일 도메인 확인 (예: yourcompany.com)

5. Kubernetes Secret 생성

# Secret 생성
kubectl apply -f grafana-oauth-secret.yaml -n monitoring

# grafana-oauth-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: grafana-oauth-secret
  namespace: monitoring
type: Opaque
stringData:
  client_id: "<클라이언트 ID>"
  client_secret: "<클라이언트 시크릿>"

6. values.yaml (grafana.ini 설정)

다음 값들을 실제 값으로 교체:

[server]
domain = <domain>
root_url = %(protocol)s://%(domain)s/

[auth.generic_oauth]
enabled = true
name = Azure AD
allow_sign_up = true
client_id = $__file{/etc/secrets/grafana-oauth/client_id}
client_secret = $__file{/etc/secrets/grafana-oauth/client_secret}
scopes = openid email profile
auth_url = https://login.microsoftonline.com/<TENANT_ID>/oauth2/authorize
token_url = https://login.microsoftonline.com/<TENANT_ID>/oauth2/token
api_url = https://graph.microsoft.com/v1.0/me
email_attribute_path = userPrincipalName
name_attribute_path = displayName
login_attribute_path = userPrincipalName
# allowed_domains = yourcompany.com (선택사항)

[auth]
disable_signout_menu = false
oauth_auto_login = false
disable_login_form = false

[auth.anonymous]
enabled = true  # 테스트용, 운영 시 false로 변경 권장

7. values.yaml 내 Secret 마운트 설정

extraSecretMounts:
  - name: grafana-oauth-secret-mount
    secretName: grafana-oauth-secret
    mountPath: /etc/secrets/grafana-oauth
    readOnly: true

8. Azure AD 앱 권한 설정

1. Azure Portal → 앱 등록 → Grafana OAuth
2. API 권한 → 권한 추가
   • Microsoft Graph → 위임된 권한
   • 다음 권한 추가:
     • User.Read (사용자 프로필 읽기)
     • email (이메일 주소 읽기)
     • profile (프로필 읽기)
     • openid (사용자 로그인)
3. 관리자 동의 부여

설정 확인

Grafana Pod 상태 확인

kubectl get pods -n monitoring -l app.kubernetes.io/name=grafana

Grafana 로그 확인

kubectl logs -n monitoring -l app.kubernetes.io/name=grafana --tail=50

3. OAuth 설정 확인

1. Grafana UI 접속: https://monitoring.xxx.nip.io
2. 로그인 페이지에서 "Azure AD" 버튼 확인
3. Azure AD 로그인 테스트

문제 해결

일반적인 문제들

1. 리디렉션 URI 오류
   • Azure Portal에서 리디렉션 URI 정확히 설정
   • 프로토콜(https) 포함 확인
2. 권한 오류
   • Azure AD에서 필요한 권한 추가
   • 관리자 동의 부여 확인
3. 도메인 제한 오류
   • allowed_domains 설정 확인
   • 사용자 이메일 도메인과 일치하는지 확인
4. Secret 마운트 오류
   • Secret이 올바른 네임스페이스에 생성되었는지 확인
   • extraSecretMounts 설정 확인

로그 확인

# Grafana 로그에서 OAuth 관련 오류 확인
kubectl logs -n monitoring -l app.kubernetes.io/name=grafana | grep -i oauth

Grafana OAuth 설정 로딩	성공
/login/generic_oauth 접근	성공 (302 응답 → Azure AD로 리디렉션)
사용자 인증 진행	🔄 Azure 측에서 인증 후 redirect_uri로 응답 전송 예정

참고 사항

• 보안: 클라이언트 시크릿은 안전하게 관리
• 만료: 클라이언트 시크릿은 24개월 후 만료되므로 주기적 갱신 필요
• 백업: 관리자 계정은 별도로 유지하여 OAuth 장애 시 접근 가능하도록 설정

참고 문서

• Grafana OAuth 공식 문서
• Microsoft Graph 권한 설명
• Azure Portal - 앱 등록