안녕하세요, 13년차의 서버실 주인장입니다. 오늘은 인프라 엔지니어라면 한 번쯤은 고민하고, 또 삽질하게 되는 주제, 바로 OIDC(OpenID Connect)와 SSO(Single Sign-On)를 활용한 사내 인증 시스템 통합 전략에 대해 이야기해보려고 합니다. 사내에 시스템이 한두 개가 아닐 텐데, 매번 다른 아이디와 비밀번호로 로그인하는 게 여간 귀찮은 일이 아니죠. 저도 처음엔 ‘그냥 다 개별적으로 관리하면 되지 뭐’라고 안일하게 생각했었는데, 시스템이 늘어날수록 사용자들의 불만이 폭주하더라고요. ‘로그인만 수십 번 하는 것 같다’는 피드백을 들었을 때는 정말 등골이 오싹했었습니다. 😱

이런 불편함을 해소하고 보안 강화는 물론, 사용자 경험 개선까지 동시에 잡을 수 있는 방법이 바로 SSO, 그리고 그 핵심에 있는 OIDC입니다. 저도 저희 회사 시스템들을 OIDC 기반으로 통합하면서 정말 많은 삽질을 했거든요. 오늘은 그 경험을 바탕으로 OIDC와 SSO가 무엇인지, 어떻게 통합해야 하는지, 그리고 어떤 문제들을 만날 수 있는지 솔직하게 풀어보겠습니다.

OIDC와 SSO를 활용한 사내 인증 시스템 통합의 전체 아키텍처 다이어그램입니다. 사용자가 SSO 포털을 통해 OIDC Provider에 인증하고, 여러 서비스에 접근하는 흐름을 한눈에 볼 수 있습니다.

SSO와 OIDC, 이 둘은 대체 뭘까요?

먼저 핵심 개념들을 쉽고 명확하게 정리해 볼게요. 저도 처음엔 OAuth랑 OIDC가 뭐가 다른지 헷갈려서 엄청 찾아봤거든요. 간단히 정리해볼게요.

SSO (Single Sign-On): 한 번의 로그인으로 만사형통!

SSO(Single Sign-On, 싱글 사인온)는 말 그대로 한 번의 인증(로그인)으로 여러 개의 서로 다른 애플리케이션이나 서비스에 접근할 수 있도록 해주는 인증 방식입니다. 예를 들어, 회사 포털에 한 번 로그인하면 그룹웨어, 메신저, 인사 시스템 등 모든 사내 시스템에 추가 로그인 없이 바로 접근할 수 있는 거죠. 사용자 입장에서는 정말 편리하고, 관리자 입장에서는 사용자 계정 관리가 훨씬 수월해집니다. 💡

OAuth 2.0 (Open Authorization): 권한 위임의 대명사

OAuth 2.0(Open Authorization)은 인증(Authentication) 프로토콜이 아닙니다. 정확히는 권한 위임(Authorization Delegation)을 위한 프레임워크라고 보시면 됩니다. ‘나’라는 사용자가 ‘서비스 A’에게 ‘서비스 B’에 있는 내 정보에 접근할 수 있는 권한을 위임할 때 사용됩니다. “카카오톡으로 로그인”이나 “구글로 로그인” 버튼을 눌렀을 때, 서비스 제공자가 내 개인 정보에 접근할 권한을 얻는 과정이 바로 OAuth 2.0을 통해 이루어집니다. 중요한 건, OAuth 2.0은 ‘누가 로그인했는지(인증)’보다는 ‘무엇에 접근할 수 있는지(권한)’에 초점을 맞춘다는 거죠.

OIDC (OpenID Connect): OAuth 2.0 위에서 동작하는 인증 프로토콜

드디어 오늘의 주인공, OIDC(OpenID Connect)입니다. OIDC는 OAuth 2.0 프레임워크 위에서 동작하는 인증(Authentication) 계층입니다. OAuth 2.0이 권한 위임에 집중했다면, OIDC는 ‘로그인한 사용자가 누구인지’를 확인하는 데 집중합니다. 사용자 정보를 담은 ID Token(아이디 토큰)을 발행하여, 클라이언트 애플리케이션이 사용자를 식별하고 인증할 수 있도록 해줍니다. 즉, OAuth 2.0은 “문 열어줄 권한”을 주고, OIDC는 “문 열고 들어온 사람이 누구인지 신분증 확인”까지 해준다고 생각하시면 쉽습니다.

OIDC 기반 SSO, 실전 구현 삽질기

자, 이제 개념은 잡혔으니 실제로 어떻게 사내 시스템에 OIDC SSO 통합을 적용했는지 이야기해 볼까요? 저는 주로 Keycloak 같은 오픈소스 OIDC Provider를 활용하는 편입니다. 홈랩에서도 자주 써봤거든요. 여기서는 OIDC Provider(Keycloak 등)가 이미 구축되어 있고, 우리가 만든 서비스(Client Application)에 연동하는 과정을 중심으로 설명하겠습니다.

1단계: OIDC Provider에 클라이언트 등록

가장 먼저 할 일은 OIDC Provider에 우리 서비스(Client Application)를 클라이언트(Client)로 등록하는 겁니다. 이때 몇 가지 중요한 정보를 입력해야 해요.

• Client ID (클라이언트 ID): 우리 서비스를 식별하는 고유한 ID입니다.
• Client Secret (클라이언트 시크릿): 클라이언트의 비밀 키로, 보안상 매우 중요합니다. 절대 외부에 노출되면 안 돼요!
• Redirect URI (리다이렉트 URI): 인증이 성공했을 때 OIDC Provider가 사용자 에이전트(브라우저)를 다시 보낼 URL입니다. 이 URL은 정확해야 합니다. 제가 초반에 제일 삽질 많이 했던 부분이 이 리다이렉트 URI 오타나 불일치였어요. ⚠️
• Scope (스코프): 클라이언트가 사용자 정보 중 어떤 항목에 접근할 권한을 요청할지 정의합니다. 최소한 openid 스코프는 필수입니다. 보통 profile, email 등도 함께 요청하죠.

OIDC Provider(예: Keycloak)에 새로운 클라이언트를 등록하는 설정 화면입니다. Client ID, Client Secret, Redirect URI, Scope 등을 정확히 입력해야 합니다. 특히 Redirect URI는 오타 없이 정확하게 입력하는 것이 중요합니다.

2단계: 서비스 애플리케이션에 OIDC 클라이언트 연동

이제 우리 서비스 애플리케이션에서 OIDC Provider와 통신할 차례입니다. 저는 웹 서비스 앞단에 Nginx를 두고 OIDC 모듈을 연동하거나, 직접 애플리케이션 코드에 OIDC 클라이언트 라이브러리를 사용하는 방식을 선호합니다. 여기서는 Nginx를 이용한 간단한 연동 예시와 함께, OIDC 플로우의 핵심을 보여드릴게요.

Nginx OIDC 모듈을 사용한 연동 예시

Nginx를 리버스 프록시(Reverse Proxy)로 사용하고, nginx-auth-oidc 같은 모듈을 활용하면 애플리케이션 코드 수정 없이도 OIDC 인증을 붙일 수 있습니다. 정말 편리하더라고요.

# nginx.conf 예시 (http 블록 내 server 블록)

server {
    listen 80;
    server_name your.service.com;

    # OIDC 설정 블록
    location / {
        # OIDC Provider의 Well-Known Configuration 엔드포인트
        # 예: https://idp.example.com/auth/realms/your-realm/.well-known/openid-configuration
        auth_request /_oauth2_proxy_auth; # 이 경로는 실제 인증 프록시 엔드포인트와 맞춰야 합니다.
        error_page 401 = /_oauth2_proxy_auth; # 401 에러 발생 시 인증 프록시로 리다이렉트

        # 인증이 성공하면 애플리케이션으로 트래픽 전달
        proxy_pass http://your_backend_service;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # OIDC 인증 프록시 설정 (이 부분은 실제 OIDC 모듈 설정에 따라 달라질 수 있습니다)
    location = /_oauth2_proxy_auth {
        internal; # 외부에서 직접 접근 불가
        proxy_pass http://localhost:PORT/auth; # 실제 OIDC 인증 프록시 서버 주소
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Original-URI $request_uri;
        # 여기에 OIDC Client ID, Secret, Redirect URI 등의 환경 변수나 설정 파일 경로 지정
        # 예: proxy_set_header X-OIDC-Client-ID "your_client_id";
        # proxy_set_header X-OIDC-Client-Secret "your_client_secret";
        # proxy_set_header X-OIDC-Redirect-URI "https://your.service.com/oauth2/callback";
    }

    # OIDC 콜백 엔드포인트
    location = /oauth2/callback {
        proxy_pass http://localhost:PORT/callback; # OIDC 인증 프록시 콜백 엔드포인트
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

위 Nginx 설정은 개념적인 예시이며, 실제 nginx-auth-oidc 모듈이나 oauth2_proxy 같은 솔루션을 사용할 경우 설정 방식이 조금 다를 수 있습니다. 핵심은 사용자가 보호된 리소스에 접근하려 할 때, Nginx가 이를 가로채 OIDC Provider로 인증을 위임하고, 인증이 완료되면 원래 요청을 백엔드 서비스로 전달하는 흐름입니다.

OIDC 플로우 간략 설명 (Authorization Code Flow 기준)

1. 사용자가 보호된 리소스(예: your.service.com/dashboard)에 접근합니다.
2. 서비스 애플리케이션(또는 Nginx 프록시)은 사용자가 인증되지 않았음을 감지하고, OIDC Provider의 Authorization Endpoint(인가 엔드포인트)로 사용자를 리다이렉트합니다. 이때 Client ID, Redirect URI, Scope 등을 쿼리 파라미터로 넘깁니다.
3. 사용자는 OIDC Provider 로그인 페이지에서 아이디/비밀번호를 입력하여 인증합니다.
4. 인증 성공 시, OIDC Provider는 미리 등록된 Redirect URI로 Authorization Code(인가 코드)를 포함하여 사용자를 다시 우리 서비스로 리다이렉트합니다.
5. 우리 서비스는 받은 Authorization Code를 이용해 OIDC Provider의 Token Endpoint(토큰 엔드포인트)로 Access Token과 ID Token을 요청합니다. 이때 Client Secret도 함께 전송하여 클라이언트의 신원을 증명합니다.
6. OIDC Provider는 Access Token과 ID Token을 발급해줍니다.
7. 우리 서비스는 ID Token을 검증하여 사용자 신원을 확인하고, Access Token을 사용하여 필요한 경우 사용자 정보(Userinfo Endpoint)를 추가로 조회하거나, 다른 리소스에 접근할 수 있습니다.
8. 사용자는 이제 서비스에 로그인된 상태가 됩니다. 🎉

주의사항과 트러블슈팅: 삽질은 나의 힘!

이런 시스템 통합 작업은 늘 예상치 못한 문제의 연속이더라고요. 제가 겪었던 대표적인 삽질 경험과 해결책을 공유합니다.

• ⚠️ Redirect URI 불일치: OIDC Provider에 등록된 Redirect URI와 실제 요청하는 URI가 단 한 글자라도 다르면 인증 플로우가 진행되지 않습니다. 심지어 http와 https, 마지막 슬래시 / 유무까지 정확히 일치해야 합니다.

  해결책: OIDC Provider 설정 화면과 애플리케이션 코드/설정 파일을 꼼꼼히 대조하고, 브라우저 개발자 도구(F12)의 네트워크 탭에서 실제 리다이렉트되는 URL을 확인하며 디버깅하세요.

  
          # curl 명령어로 .well-known/openid-configuration 확인하여 정확한 endpoint 정보 파악
          curl -s https://idp.example.com/auth/realms/your-realm/.well-known/openid-configuration | jq .
          

  이 명령어를 통해 OIDC Provider가 제공하는 정확한 엔드포인트와 정보들을 확인할 수 있습니다. 특히 authorization_endpoint, token_endpoint, jwks_uri 등을 잘 봐야 합니다.

• ⚠️ Scope/Claim 누락: 필요한 사용자 정보(예: 이메일, 이름)가 ID Token이나 Userinfo Endpoint에서 넘어오지 않을 때가 있습니다. 이는 보통 클라이언트 등록 시 요청하는 Scope(스코프)가 부족하거나, OIDC Provider에서 해당 Claim(클레임)을 발행하도록 설정되지 않았기 때문입니다.

  해결책: 클라이언트 등록 시 openid profile email 등 필요한 스코프를 모두 요청했는지 확인하고, OIDC Provider의 사용자 속성(User Attributes) 또는 클레임 매핑 설정을 확인하세요.

• ⚠️ Token 검증 실패: ID Token의 Signature(서명) 검증에 실패하거나, 유효 기간(exp 클레임)이 만료된 토큰을 사용하는 경우가 있습니다. 이는 주로 OIDC Provider의 JWKS(JSON Web Key Set) 엔드포인트 설정 오류, 서버 시간 동기화 문제, 또는 토큰 캐싱 문제에서 발생합니다.

  해결책: OIDC Provider의 JWKS URI가 정확한지 확인하고, 애플리케이션 서버의 시간이 NTP 등으로 정확하게 동기화되어 있는지 확인하세요. 토큰을 캐싱한다면 만료 시간을 고려해야 합니다.

• ⚠️ Client Secret 노출 위험: Client Secret은 정말 중요합니다. 절대 하드코딩하거나 Git 저장소에 올리면 안 돼요.

  해결책: 환경 변수(Environment Variable), HashiCorp Vault 같은 Secrets Management 솔루션, 또는 Kubernetes Secret 등을 활용하여 안전하게 관리해야 합니다.

  
          # 환경 변수로 Client Secret 설정 예시 (애플리케이션 실행 시)
          export OIDC_CLIENT_SECRET="your_very_secret_key"
          python your_app.py
          

  이런 방식으로 서버 시작 시에만 접근하도록 하는 것이 안전합니다.

검증 및 결과 확인: 드디어 로그인 성공!

위의 삽질들을 거쳐서 드디어 OIDC 기반 SSO가 정상적으로 동작하는 것을 확인했습니다. 보통 다음과 같은 방법으로 검증합니다.

1. 서비스 접근 및 로그인 시도: 웹 브라우저로 서비스 URL에 접속했을 때, OIDC Provider의 로그인 페이지로 정확히 리다이렉트되는지 확인합니다.
2. 로그인 후 서비스 접근: 로그인 성공 후, 서비스의 메인 페이지나 보호된 리소스에 정상적으로 접근되는지 확인합니다.
3. ID Token 및 Access Token 내용 확인: 개발자 도구 또는 애플리케이션 로그를 통해 발급된 ID Token(JWT 형식)을 jwt.io 같은 사이트에서 디코딩하여, 사용자 정보(sub, name, email 등)가 올바르게 포함되어 있는지 확인합니다. Access Token은 불투명할 수 있지만, OIDC Provider의 Userinfo Endpoint를 통해 사용자 정보를 가져올 때 사용됩니다.
4. 세션 관리 확인: 한 번 로그인하면 다른 사내 시스템(OIDC Client로 등록된)에 추가 로그인 없이 접근되는지 확인합니다.

OIDC 기반 SSO 로그인 성공 후, 사용자 정보가 표시되는 웹 애플리케이션 대시보드와 JWT 토큰 디코딩 결과 화면입니다. 토큰에 담긴 사용자 정보가 정확한지 확인하는 과정이 중요합니다.

마무리: OIDC SSO, 선택이 아닌 필수

OIDC와 SSO를 사내 시스템에 통합하는 과정은 결코 쉽지 않습니다. 저도 수많은 시행착오와 삽질을 거쳤고, 밤샘 디버깅도 여러 번 했거든요. 하지만 고생 끝에 낙이 온다고, 제대로 구축된 OIDC 기반 SSO는 사용자 경험 개선, 보안 강화, 그리고 중앙 집중식 계정 관리라는 세 마리 토끼를 동시에 잡을 수 있게 해줍니다.

OIDC 기반 SSO의 주요 장점을 요약한 인포그래픽입니다. 사용자 경험 개선부터 보안 강화, 관리 효율성 증대까지 다양한 이점을 명확하게 보여줍니다.

만약 여러분의 사내 시스템이 아직도 각자도생의 길을 걷고 있다면, 지금 바로 OIDC 기반 SSO 통합을 진지하게 고민해 보시길 강력히 권해드립니다. 처음엔 어렵겠지만, 장기적으로는 훨씬 더 견고하고 효율적인 인프라를 만들 수 있을 거예요. 다음번에는 OIDC와 연동하여 RBAC(Role-Based Access Control, 역할 기반 접근 제어)를 어떻게 구현하는지에 대한 경험담을 풀어볼까 합니다. 궁금하신 점이 있다면 언제든 댓글 남겨주세요! 😉