SAML 인증 트러블슈팅

SAML 인증 트러블슈팅 (Troubleshooting SAML authentication)

Grafana에서 SAML 인증을 구성할 때 흔히 겪는 문제들과 해결 방법을 정리한 문서예요. 무한 리다이렉트 루프, 개인 키 형식 오류, CSRF 관련 origin not allowed, login session has expired 오류, 그리고 Entra ID의 Graph API 문제를 다룹니다.

출처: Troubleshooting SAML authentication

본문

디버그 로깅 활성화

더 많은 로그 정보를 얻어 트러블슈팅하려면 구성 파일에서 SAML 디버그 로깅을 활성화해요.

[log]
filters = saml.auth:debug

무한 리다이렉트 루프 / IdP 측 로그인 성공 후 로그인 페이지로 리다이렉트

auto_login = true일 때 무한 리다이렉트 루프가 발생하거나 성공적인 로그인 후 로그인 페이지로 리다이렉트된다면, grafana_session 쿠키의 SameSite 설정이 Strict로 설정되어 있을 가능성이 높아요. 이 설정은 교차 사이트 요청 중에 grafana_session 쿠키가 Grafana로 전송되는 것을 막아요. 이 문제를 해결하려면 Grafana 구성 파일에서 security.cookie_samesite 옵션을 Lax로 설정하세요.

`asn1: structure error: tags don't match` 오류로 SAML 인증 실패

Grafana는 오직 한 가지 개인 키 형식만 지원해요: PKCS#8. 키가 다른 형식(PKCS#1 또는 PKCS#12)이라면 개인 키 형식을 변환해야 할 수 있어요. 다음 명령은 pkcs8 키 파일을 만들어요.

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

개인 키 형식을 base64로 변환

다음 명령은 키를 base64 형식으로 변환해요. (-w0 스위치는 Mac에서는 필요 없고 Linux에서만 필요해요.)

$ base64 -w0 key.pem > key.pem.base64
$ base64 -w0 cert.pem > cert.pem.base64

base64 인코딩된 값(key.pem.base64, cert.pem.base64 파일)은 certificate와 private_key에 사용돼요. 제공하는 키는 개인 키 모양([REDACTED PRIVATE KEY]로 시작하는 PEM 블록)이어야 해요.

`origin not allowed` 응답으로 SAML 로그인 실패

사용자가 SAML로 로그인할 때 origin not allowed가 표시되면, 사용자가 IdP 서비스에서 로그인을 시작했거나 리버스 프록시 뒤에 있을 수 있어요. 이는 Grafana의 CSRF 검사가 요청을 유효하지 않은 것으로 간주하기 때문에 발생할 수 있어요. CSRF에 대한 자세한 내용은 관련 문서를 참고하세요.

이 문제를 해결하려면 SAML 구성에서 csrf_trusted_origins 또는 csrf_additional_headers 옵션을 구성할 수 있어요.

구성 파일 예시:

# config.ini
...
[security]
csrf_trusted_origins = https://grafana.example.com
csrf_additional_headers = X-Forwarded-Host
...

`login session has expired` 응답으로 SAML 로그인 실패

Grafana 서버의 루트 URL이 아닌 URL에서 Grafana 로그인 페이지에 접근하면 인스턴스가 "login session has expired" 오류를 반환할 수 있어요.

프록시 서버를 통해 Grafana에 접근한다면 쿠키가 Grafana의 루트 URL로 올바르게 재작성되는지 확인하세요. 쿠키는 Grafana의 root_url과 같은 URL에 설정되어야 해요. 이는 보통 리버스 프록시의 도메인/주소예요.
프록시 서버 구성의 쿠키 설정을 검토해 쿠키가 폐기되지 않는지 확인하세요.
Grafana 구성에서 다음 설정을 검토해요.

[security]
cookie_samesite = lax

이 설정은 Grafana 세션 쿠키가 리다이렉트와 함께 올바르게 동작하도록 lax로 설정해야 해요.

[security]
cookie_secure = true

향상된 보안을 위해 cookie_secure를 true로 설정하면 쿠키가 HTTPS로만 전송되도록 강제해요.

Graph API 호출 트러블슈팅

Entra ID로 SAML 인증을 설정할 때 Graph API 호출에서 문제가 발생할 수 있어요. 이는 Entra ID 애플리케이션이 Graph API 접근을 허용하도록 제대로 구성되지 않은 경우에 발생할 수 있어요. 다음 명령으로 Graph API 호출을 테스트해 보세요.

curl -X POST "{token_url}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}&scope=https://graph.microsoft.com/.default"

여기서 다음 값은 SAML 구성에서 온 것이에요.

token_url: Entra ID 애플리케이션의 토큰 URL
client_id: Entra ID 애플리케이션의 client ID
client_secret: Entra ID 애플리케이션의 client secret

응답은 다음과 같아야 해요.

{
  "access_token": "...ACCESS_TOKEN...",
  "token_type": "Bearer",
  "expires_in": 3600
}

access_token으로 Graph API 호출을 테스트해요.

curl -X GET "https://graph.microsoft.com/v1.0/groups" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json"

응답은 다음과 같아야 해요.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(Edm.String)",
  "value": ["29f2e7c8-9b9d-443c-bc62-7d8cdcfcfe59", "f0224e82-0eb8-4eda-8979-0c36e98deb00"]
}

두 번째 호출이 401 또는 403으로 실패하면 Entra ID 애플리케이션 설정을 확인해 Graph API 접근이 활성화되어 있는지 확인해야 해요.

SAML 인증 트러블슈팅