[Infra Ops] SAML/OAuth 기반 싱글사인온 구성과 장애 분석

# application.yml (Spring Boot + Spring Security SAML)
spring:
  security:
    saml2:
      relyingparty:
        registration:
          adfs:
            entity-id: https://our-app.com/saml/metadata   # SP Entity ID
            asserting-party:
              metadata-uri: https://idp.company.com/FederationMetadata/2007-06/FederationMetadata.xml
            acs:
              location: "{baseUrl}/saml/acs"                # ACS URL
            signing:
              credentials:
                - private-key-location: classpath:saml/sp-private.key
                  certificate-location: classpath:saml/sp-cert.crt

# SP 앞에 Nginx가 있는 경우 ACS URL이 정확히 프록시 되어야 함
location /saml/ {
    proxy_pass http://backend:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # X-Forwarded-Proto를 SP가 읽어 ACS URL에 https를 붙여야 함
    # 미설정 시 ACS URL이 http://로 생성되어 IdP와 불일치
}

# 브라우저 Network 탭에서 ACS POST 요청의 SAMLResponse 값을 복사 후 분석
# URL 인코딩된 경우 먼저 디코딩 필요

SAML_RESPONSE="BASE64_ENCODED_SAML_RESPONSE_HERE"

# base64 디코딩 후 XML 포맷팅
echo "$SAML_RESPONSE" | base64 -d | xmllint --format - 2>/dev/null | head -80

# NameID (사용자 식별자) 확인
echo "$SAML_RESPONSE" | base64 -d | xmllint --format - 2>/dev/null \
  | grep -E "NameID|NameIdentifier"
# 출력 예: <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
#            user@company.com
#          </saml:NameID>

# Attribute (역할, 부서 등 추가 정보) 확인
echo "$SAML_RESPONSE" | base64 -d | xmllint --format - 2>/dev/null \
  | grep -A 3 "Attribute"
# 출력 예: <saml:Attribute Name="role">
#            <saml:AttributeValue>admin</saml:AttributeValue>
#          </saml:Attribute>

# InResponseTo 확인 (SP-initiated는 있어야 함)
echo "$SAML_RESPONSE" | base64 -d | xmllint --format - 2>/dev/null \
  | grep "InResponseTo"

# 어설션 유효 시간 확인 (서버 시간 차이 문제 진단)
echo "$SAML_RESPONSE" | base64 -d | xmllint --format - 2>/dev/null \
  | grep -E "NotBefore|NotOnOrAfter"
# NotBefore와 NotOnOrAfter 사이여야 유효
# 서버 시간이 5분 이상 차이나면 어설션이 expired로 거부됨

# NTP 동기화 상태 확인
timedatectl status
# "System clock synchronized: yes"가 있어야 함

# IdP와 SP 서버 시간 차이 허용 범위: 보통 ±5분
# 차이가 크면 "Assertion not yet valid" 또는 "Assertion expired" 에러
date -u     # SP 서버 UTC 시간

# 5단계: authorization code → access_token 교환
curl -X POST https://auth.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_STEP4" \
  -d "client_id=my-client-id" \
  -d "client_secret=my-client-secret" \
  -d "redirect_uri=https://our-app.com/oauth/callback"

# 응답 예시:
# {
#   "access_token": "eyJhbGciOiJ...",
#   "token_type": "Bearer",
#   "expires_in": 3600,
#   "refresh_token": "1//0eGxH...",
#   "scope": "openid email profile"
# }

# access_token으로 사용자 정보 조회
curl https://www.googleapis.com/userinfo/v2/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

# refresh_token으로 access_token 갱신 (만료 후)
curl -X POST https://auth.example.com/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=my-client-id" \
  -d "client_secret=my-client-secret"

[브라우저]  앱의 "구글로 로그인" 클릭
   │
   ① 앱 → IdP 인가 요청 리다이렉트  (프런트채널, authorization request)
   │     ?client_id=..&redirect_uri=..&scope=openid email
   │     &state=xyz(CSRF 방지) &code_challenge=..(PKCE)
   │
   ② IdP 화면에서 사용자 로그인 + 권한 동의(consent)
   │
   ③ IdP → 앱으로 리다이렉트  (프런트채널)
   │     redirect_uri?code=AUTH_CODE&state=xyz   ← 단기·1회용 code만 전달
   │     앱은 받은 state가 ①에서 보낸 값과 같은지 먼저 검증
   │
   ④ 앱 백엔드 → IdP 토큰 엔드포인트  (백채널, 서버↔서버)
   │     code + client_secret + code_verifier(PKCE) 제출
   │
   ⑤ IdP → 토큰 응답  (백채널)
   │     access_token(API 호출용) + id_token(OIDC 신원, JWT) + refresh_token
   │
   ⑥ 앱: id_token 서명 검증(IdP 공개키 = JWKS) → 로그인 세션 생성
   │     이후 access_token 을 Authorization: Bearer 로 리소스 API 호출
   ▼
[앱]  로그인 완료 · access 만료되면 refresh_token 으로 조용히 갱신

# 개발/테스트용 Keycloak 실행
docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:latest \
  start-dev

# http://localhost:8080/admin 접속 후 설정:
# 1. Realm 생성 (예: my-company)
# 2. Client 생성 → Client type: SAML 또는 OpenID Connect
# 3. Valid redirect URIs: https://our-app.com/*
# 4. 메타데이터 URL 확인: http://localhost:8080/realms/my-company/protocol/saml/descriptor

# IdP 메타데이터 XML 확인 (SP 설정에 필요한 IdP 정보 포함)
curl -s http://localhost:8080/realms/my-company/protocol/saml/descriptor \
  | xmllint --format - | grep -E "EntityID|SingleSignOn|X509Certificate"

# OIDC Well-known 설정 확인 (OAuth/OIDC 설정에 필요)
curl -s http://localhost:8080/realms/my-company/.well-known/openid-configuration \
  | python3 -m json.tool | grep -E "issuer|authorization_endpoint|token_endpoint"