목차
프로젝트 권한을 담은 n3r OIDC 토큰 (2026-11)
원문 정보
- 원문: 로그인 화면, 이제 만들지 마세요 - n3r OIDC (영상, 약 32분)
- 매체 · 공개일: NAVER Engineering Day 10th 세션 공개 영상 · 2026-11-08(PST)
- 발표자: 허신행 (YouTube 자동 자막 기준 표기)
- YouTube 한국어 자동 자막을 받아 인식 오류를 고친 뒤 재구성한 요약입니다. 슬라이드에만 있던 설정 예와 토큰 예시 값은 담지 못했습니다.
n3r 밖의 앱에 필요한 로그인
n3r은 네이버 사내 쿠버네티스 플랫폼으로, 이미 프로젝트 단위로 구성원과 권한을 관리합니다. 사용자 인증과 세션은 n3r 아이덴티티 프로바이더가 담당합니다. 권한 시스템에는 프로젝트별 롤과 그룹, 각 롤이 어떤 리소스에 어떤 작업을 할 수 있는지 정의한 폴리시가 있습니다. 그러나 프로젝트에 띄운 앱이나 Jenkins, Grafana 같은 외부 도구에서 이 기능을 사용할 방법은 없었고, 연결할 사내 OIDC도 없었습니다.
발표가 제시한 도입 배경은 네 가지입니다. AI 도구로 빠르게 만든 대시보드와 내부 도구는 로그인 없이 띄우면 주소를 아는 누구나 볼 수 있습니다. 기본 계정 비밀번호를 팀원끼리 공유하면 업무가 바뀐 사람도 계속 접근하고, 누가 무엇을 했는지 남지 않습니다. 지원이 끝난 사내 인증 플러그인에는 대체 수단이 필요합니다. 사용자 대신 n3r API를 호출하는 AI 에이전트에는 서버용 M2M 토큰이 아니라 사람이 권한을 위임한 토큰이 필요합니다.
앱마다 이를 직접 구현하려면 로그인 화면, 세션, 비밀번호 재설정, 사용자 식별, 권한 판정, 롤 변경을 반영하는 동기화 코드까지 마련해야 합니다. 사용자 키를 사번·이메일·uid 중 무엇으로 삼을지도 정해야 하고, UUID를 쓰면 사용자를 구분할 매핑 테이블도 필요합니다. 발표자는 이런 작업이 앱의 본질적인 기능이 아니며, 구현 방식이 제각각이면 재사용하기도 어렵다고 보았습니다. n3r OIDC는 기존 로그인과 권한을 표준으로 제공하려는 선택입니다. OpenID Connect로 로그인하고, OAuth 2.0 액세스 토큰으로 사용자를 대신해 n3r API를 호출하도록 했습니다.
authorization code와 PKCE로 이어지는 로그인 흐름
사용자가 앱에 접근하면 앱은 브라우저를 n3r.iam의 authorize 엔드포인트로 보냅니다. 이때 client ID, redirect URI, scope, state, PKCE 값을 함께 전달합니다. n3r은 세션 쿠키를 확인하고, 세션이 없으면 return-to를 지정해 기존 통합 로그인 화면으로 보냈다가 authorize로 돌아오게 합니다. 이미 n3r에 로그인한 사용자는 다시 로그인하지 않습니다.
세션을 확인한 n3r.iam은 authorization code를 발급하고, 등록된 redirect URI로 code와 state를 돌려줍니다. 앱 서버는 token 엔드포인트에 code를 보내 ID 토큰, 액세스 토큰, 리프레시 토큰으로 교환합니다. 이 과정에서 n3r.iam이 권한 시스템의 롤과 그룹을 조회해 토큰에 넣습니다. 앱은 JWKS 공개키로 서명을 검증한 뒤 클레임으로 권한을 결정합니다. 별도의 로그인 화면을 만들 필요 없이 OIDC 라이브러리를 설정하고 클레임을 읽는 정도로 연동할 수 있습니다.
로그인과 API 호출에 쓰는 ID 토큰과 액세스 토큰
앱은 누가 로그인했는지를 담은 ID 토큰으로 세션을 만듭니다. API를 호출할 때는 사용자가 무엇을 할 수 있는지를 담은 액세스 토큰을 사용합니다. 두 토큰은 모두 JWT이므로 앱이 프로바이더와 통신하지 않고도 JWKS 공개키로 검증할 수 있습니다.
ID 토큰과 액세스 토큰은 수명이 짧습니다. 만료되면 리프레시 토큰으로 재발급하며, 이 과정은 사용자에게 보이지 않습니다. 수명이 긴 리프레시 토큰은 앱 서버만 보관하고 OIDC 프로바이더에만 보냅니다.
프로젝트 접두사로 구분한 groups와 프로젝트별 roles
첫 번째 설계 결정은 프로젝트별 인가 정보를 ID 토큰과 액세스 토큰에 담는 것입니다. 표준 OIDC는 사용자가 누구인지까지만 정의합니다. JWT 액세스 토큰 표준인 RFC 9068에는 groups와 roles 클레임이 있지만, 이 클레임만으로는 어느 프로젝트의 그룹과 롤인지 구분할 수 없습니다. n3r은 groups에 프로젝트 접두사를 붙이고, 롤은 프로젝트별 맵 형태의 n3r roles 클레임에 넣어 이 구분을 표현했습니다.
두 클레임은 연동 대상이 필요로 하는 정보가 달라 함께 제공했습니다. Grafana나 Jenkins 같은 오픈소스는 토큰의 groups 클레임으로만 롤을 매핑할 수 있습니다. n3r 플랫폼에는 그룹보다 롤 정보가 필요하므로, n3r roles에는 그룹을 통해 받은 롤까지 포함했습니다. 앱은 토큰에서 이 정보를 읽어 매번 n3r을 다시 호출하지 않고도 권한을 판단할 수 있습니다.
커스텀 클레임은 사번, 그룹 정보, 프로젝트별 롤 정보의 세 가지로 나뉩니다.
- 사번이 있는 사용자라면 scope와 관계없이 사번을 항상 포함합니다.
groupsscope를 요청하면groups클레임에프로젝트/그룹명형식으로 그룹 정보를 넣습니다.n3r projectscope를 요청하면 n3r project와 n3r roles에 프로젝트별 롤 정보를 넣습니다. 그룹을 통해 받은 롤도 포함합니다.
권한 정보를 토큰에 담으면서 토큰은 길어졌습니다. 토큰을 짧게 유지해야 하거나, 항상 최신 권한이 필요하거나, groups와 n3r roles 클레임으로 연동할 수 없는 앱에는 userinfo 엔드포인트로 실시간 권한을 조회하는 방법도 제공합니다.
클라이언트 등록 주체에 따라 달라지는 audience
두 번째 결정은 로그인으로 받은 액세스 토큰을 n3r API에서도 받아들이되, 클라이언트를 등록한 주체에 따라 토큰의 범위를 제한하는 것입니다. OIDC 표준이 이 토큰으로 호출할 수 있다고 정한 API는 userinfo 하나뿐입니다. 다른 API가 토큰을 받아들일지는 프로바이더가 정합니다.
기존 n3r API는 서비스 어카운트 토큰만 받았습니다. 앱이 사용자 대신 API를 호출하려면 사용자의 서비스 어카운트 토큰을 복사해 받아야 했습니다. 이제 앱은 로그인으로 받은 액세스 토큰을 Authorization 헤더에 넣어 보낼 수 있습니다. n3r API가 이 헤더를 그대로 n3r.iam에 넘기면, n3r.iam이 서명·발급자·만료·토큰 종류·audience를 검증하고 감사 로그에 사용자와 OIDC 클라이언트를 남깁니다.
이때 프로젝트 어드민이 등록한 클라이언트로 받은 토큰에 사용자의 모든 프로젝트 권한을 허용해서는 안 됩니다. 표준에서는 앱이 요청하고 사용자가 동의(consent)한 scope로 권한 범위를 정하지만, n3r에는 consent가 없고 권한이 프로젝트 단위로 나뉘어 있습니다. n3r은 클라이언트 등록 주체를 기준으로 audience와 클레임의 범위를 정했습니다.
n3r 관리자가 등록한 글로벌 클라이언트는 n3r 플랫폼 전용입니다. audience는 n3r 전체이며, 요청한 scope에 따라 모든 프로젝트의 롤과 그룹을 토큰에 포함합니다. 프로젝트 어드민이 등록한 클라이언트의 audience는 해당 프로젝트로 제한합니다. 사용자가 다른 프로젝트에도 속해 있더라도 토큰에는 클라이언트가 등록된 프로젝트의 롤과 그룹만 넣습니다.
제한을 audience에 둔 이유는 인증 단계에서 요청을 거부하기 위해서입니다. 그래야 인가를 별도로 확인하지 않는 API에서도 범위를 벗어난 토큰을 막을 수 있습니다. 이 선택에 따라 프로젝트 클라이언트의 토큰 클레임은 언제나 해당 프로젝트로 제한됩니다.
토큰의 롤로 범위를 제한한 인가 판정
audience를 제한하는 것만으로는 프로젝트별 권한 범위가 유지되지 않습니다. 토큰이 audience 검증을 통과한 뒤 인가 단계에서 사용자의 현재 권한 전체를 조회해 적용하면, 그 토큰으로 사용자의 모든 프로젝트 권한을 행사할 수 있기 때문입니다.
세 번째 결정은 이 문제를 막기 위해 인가에 사용할 롤을 토큰의 n3r roles 클레임으로 한정하는 것입니다. RFC 9068은 리소스 서버가 roles와 groups 클레임으로 인가하도록 하지만, 구체적인 판정 방법은 정하지 않습니다. n3r.iam은 기존에 호출자의 현재 권한 전체를 사용했으나, OIDC 액세스 토큰을 받을 때는 토큰에 담긴 롤만 사용하고 사용자가 지금도 그 롤을 보유하는지는 다시 확인하지 않습니다.
이 방식에서도 액션과 리소스의 허용 여부는 권한 시스템이 판정합니다. n3r은 프로젝트마다 롤과 폴리시가 다르고, 어떤 액션으로 어떤 리소스에 접근할 수 있는지를 폴리시로 정의합니다. 토큰에는 롤 이름만 넣고, 그 롤로 요청한 작업을 할 수 있는지는 폴리시를 가진 권한 시스템에 맡깁니다. 요청마다 사용자의 롤 보유 여부를 다시 조회하지 않으므로 권한 시스템 호출이 줄어듭니다. 롤 변경은 수명이 짧은 액세스 토큰을 재발급할 때 반영합니다.
그만큼 토큰의 롤은 발급 시점에 머뭅니다. 새로 부여받은 롤은 재발급 전까지 사용할 수 없고, 사용자에게서 회수한 롤도 토큰이 만료될 때까지 유효합니다. 다만 롤이나 폴리시 자체를 삭제하면 권한을 부여할 폴리시가 사라지므로 토큰은 바로 거부됩니다.
introspection을 대신하는 짧은 액세스 토큰 수명
네 번째 결정은 introspection을 제공하지 않고 짧은 토큰 수명으로 권한 변경을 반영하는 것입니다. RFC 7662에 정의된 introspection은 리소스 서버가 프로바이더에 토큰의 유효성을 다시 묻는 방식입니다. n3r.iam은 이 엔드포인트를 두지 않았습니다. 대신 액세스 토큰의 유효 기간을 최대한 짧게 정하고, 재발급할 때 롤과 그룹을 갱신합니다.
발표자는 서버 부하와 변경 전파의 범위를 함께 고려했다고 설명했습니다. 권한 변경을 즉시 반영하려면 리소스 서버가 요청마다 introspection을 호출해야 하므로 권한 서버 부하와 통신량이 크게 늘어납니다. 그런데 대부분의 오픈소스와 토큰만 보고 권한을 판단하는 리소스 서버는 introspection을 호출하지 않습니다. 엔드포인트를 제공해도 이들에는 권한 변경이 전파되지 않는다는 한계가 있습니다.
발표에서 모든 리소스 서버에 변경을 전파할 방법으로 선택한 것은 토큰 재발급입니다. 재발급 시 n3r.iam은 권한 시스템에서 현재 롤과 그룹을 다시 읽고, 프로젝트 같은 클레임 필터를 적용해 토큰을 만듭니다.
권한 회수는 즉시 이뤄지지 않습니다. 롤을 잃은 사용자도 토큰이 만료될 때까지 예전 권한을 사용할 수 있습니다. 앱이 권한을 세션에 따로 저장한다면 그 기간은 세션이 끝날 때까지 이어질 수 있습니다.
디스커버리 문서로 확인하는 지원 범위
연동을 시작하려면 OIDC 클라이언트를 등록해야 합니다. 프로젝트 어드민이 n3r 웹의 프로젝트 IAM 메뉴에서 이름, redirect URI, 허용 scope, public 여부를 입력하는 방식이며, 발표 당시에는 등록 화면의 배포를 준비 중이었습니다. 등록하면 client ID와 secret을 받습니다. secret은 그때 한 번만 보여 주므로 잃어버리면 재발급해야 합니다. CLI나 SPA처럼 secret을 보관할 서버가 없는 환경은 public 클라이언트로 등록하고, 이 경우 PKCE가 필수입니다.
엔드포인트와 설정은 디스커버리 문서에서 확인할 수 있습니다. 라이브러리가 디스커버리를 지원하면 issuer 주소 하나로 나머지 정보를 읽습니다. 지원하는 엔드포인트는 discovery, authorize, token, userinfo, JWKS, revoke입니다. introspection, dynamic registration, device flow, 로그아웃 전파는 지원하지 않습니다.
| 항목 | 지원 값 |
|---|---|
| scope | 표준 openid, profile, email + 커스텀 groups, n3r project |
| grant type | authorization code, refresh token |
| response type | code만 |
| PKCE | S256 |
| 토큰 서명 | RS256, JWKS에 여러 키를 노출해 kid로 선택 |
| 클라이언트 인증 | secret을 Basic 헤더 또는 요청 본문으로, public 클라이언트는 none |
서명 키가 로테이션돼도 JWKS에서 kid로 키를 선택하므로 앱 설정을 바꿀 필요가 없습니다. 리프레시 토큰은 사용할 때마다 새로 발급하고 이전 토큰을 폐기합니다. 난수로 만들며 서버에는 해시만 저장합니다. 발표에서는 Spring Security와 Grafana 설정 예도 화면으로 보여 줬습니다.
실제 연동에서는 다음 항목을 확인해야 합니다.
- redirect URI는 등록한 값과 정확히 일치해야 하며, 토큰 교환 때도 같은 값을 보내야 합니다.
- state와 nonce를 사용하고, PKCE는 code challenge method를 S256으로 명시합니다.
- ID 토큰은 서명·audience·nonce를 검증합니다. 액세스 토큰을 직접 검증하는 API는 audience까지 확인해야 합니다.
- 권한은
groups또는 n3r roles 클레임으로 판단합니다. 권한 변경 반영은 액세스 토큰 기준 최대 5분, ID 토큰 기준 최대 10분까지 늦을 수 있습니다. - 사용자 키는 subject를 사용합니다. 사내 다른 시스템과 연동해야 하면 사번을 사용합니다.
- 같은 리프레시 토큰으로 동시에 갱신하면 하나만 성공하므로, 인스턴스가 여러 개라면 한 곳에서만 갱신합니다.
배포를 준비하는 클라이언트 등록 화면과 검토 중인 n3r CLI 로그인
발표에서 제시한 다음 단계는 세 가지입니다.
- 프로젝트 어드민이 n3r 웹에서 OIDC 클라이언트를 직접 등록·관리할 화면의 배포를 준비하고 있습니다. 프로젝트만 만들면 외부 앱 연동을 시작할 수 있도록 하는 작업입니다.
- OIDC 액세스 토큰으로 호출할 수 있는 n3r 플랫폼 API를 늘릴 예정입니다. 발표 시점에는 일부 플랫폼 API만 지원하며, 이를 모든 플랫폼으로 확대하려고 합니다.
- n3r CLI에 사용자 로그인을 도입하는 방안을 검토하고 있습니다. 현재는 서비스 어카운트 토큰을 사용해 감사 로그에 실행한 사람이 남지 않습니다. 사용자 로그인으로 바꾸면 감사 로그에 본인이 남게 됩니다.
consent 화면, 로그아웃 전파, introspection 엔드포인트는 아직 제공할 계획이 없다고 밝혔습니다.