RP 자동 로그인 지원 가이드

이 문서는 Baron SSO의 userfront 연동 앱에서 RP를 클릭했을 때 별도 로그인 버튼 클릭 없이 OIDC 인증을 시작하려는 RP 등록자와 RP 개발자를 위한 기준입니다.

목적

자동 로그인은 userfront가 RP의 자체 로그인 시작 URL로 사용자를 보내고, RP가 그 진입점에서 OIDC Authorization Code + PKCE 흐름을 직접 시작하는 방식입니다.

Baron backend가 /oauth2/auth?... URL을 대신 만들어 넘기지 않는 이유는 RP가 직접 state, nonce, PKCE verifier/challenge, callback 검증 상태를 관리해야 하기 때문입니다. SPA나 모바일 웹앱은 이 상태가 RP 저장소에 있어야 callback을 안전하게 처리할 수 있습니다.

등록 메타데이터

RP는 Hydra client metadata에 다음 값을 저장합니다.

키	타입	설명
`auto_login_supported`	boolean	자동 로그인 지원 여부입니다. `true`일 때만 userfront가 자동 로그인 URL을 진입 URL로 사용합니다.
`auto_login_url`	string	RP가 OIDC 로그인을 시작하는 URL입니다. `http` 또는 `https` URL이어야 합니다.

devfront의 RP 일반 설정에서 다음 항목을 입력합니다.

자동 로그인 지원을 켭니다.
자동 로그인 시작 URL에 RP 로그인 시작 URL을 입력합니다.
Redirect URI 목록에는 RP callback URL을 등록합니다.
저장 후 userfront 연동 앱 카드에서 “연동앱 클릭 시 별도 로그인 없이 로그인할 수 있습니다.” 안내가 보이는지 확인합니다.

예시:

auto_login_supported: true
auto_login_url: https://org.example.com/login?auto=1
redirect_uri: https://org.example.com/auth/callback

RP 구현 요구사항

RP는 auto_login_url에서 다음 동작을 구현해야 합니다.

auto=1 쿼리를 읽습니다.
이미 RP 세션이 있으면 기본 화면 또는 returnTo 경로로 이동합니다.
RP 세션이 없고 auto=1이면 로그인 버튼을 기다리지 않고 OIDC authorization 요청을 시작합니다.
OIDC 요청 전에 state, nonce, PKCE code_verifier, code_challenge를 생성합니다.
state, nonce, code_verifier, returnTo는 RP origin의 안전한 저장소에 보관합니다.
callback에서 state를 검증하고, token 교환 시 code_verifier를 사용합니다.
인증 완료 후 저장된 returnTo가 있으면 해당 경로로 이동합니다.

권장 URL 형식:

https://rp.example.com/login?auto=1
https://rp.example.com/login?auto=1&returnTo=%2Fdashboard

Baron 내장 RP 기준

Baron 계열 RP는 다음 fallback을 사용합니다. env URL이 설정되어 있을 때만 자동 로그인 지원으로 간주합니다.

Client ID	Env	자동 로그인 URL
`adminfront`	`ADMINFRONT_URL`	`${ADMINFRONT_URL}/login?auto=1`
`devfront`	`DEVFRONT_URL`	`${DEVFRONT_URL}/login?auto=1&returnTo=%2Fclients`
`orgfront`	`ORGFRONT_URL`	`${ORGFRONT_URL}/login`

orgfront는 /login 진입부터 OIDC authorize 요청을 즉시 시작하며, 기본 callback 이후 이동 경로는 /chart입니다. 수동 로그인 화면 검증이 필요하면 /login?auto=0으로 자동 시작을 끌 수 있습니다.

userfront 동작

userfront는 backend의 linked RP 응답을 기준으로 진입 URL을 선택합니다.

status가 active가 아니면 진입 URL을 만들지 않습니다.
auto_login_supported=true이면 auto_login_url을 우선 사용합니다.
auto_login_url이 없으면 init_url을 사용합니다.
자동 로그인 미지원이면 init_url이 있어도 기존 url로 이동합니다.

이 기준 때문에 auto_login_supported=false인 RP는 accidental auto-login을 수행하지 않습니다.

검증 체크리스트

RP 등록자는 다음을 확인해야 합니다.

devfront에서 자동 로그인 지원이 켜져 있습니다.
자동 로그인 시작 URL이 실제 RP 로그인 진입점입니다.
auto_login_url에 직접 접속하면 로그인 버튼 클릭 없이 Baron OIDC authorize 요청이 시작됩니다.
callback URL이 Redirect URI에 등록되어 있습니다.
callback 이후 RP가 state, nonce, PKCE 검증을 통과합니다.
userfront 연동 앱 카드에 자동 로그인 안내 문구가 표시됩니다.
userfront에서 RP 카드를 클릭하면 RP 로그인 화면에 머물지 않고 OIDC 흐름으로 진입합니다.

orgfront 기준 검증 명령:

npm run test -- tests/orgfront-auto-login.spec.ts --project=chromium

실패 시 확인할 항목

증상	확인 항목
userfront에서 일반 URL로만 이동함	RP metadata의 `auto_login_supported`가 `true`인지 확인합니다.
userfront 카드에 안내 문구가 없음	backend `/api/v1/user/rp/linked` 응답에 `auto_login_supported=true`가 내려오는지 확인합니다.
RP 로그인 화면에 머무름	RP가 `auto=1` 쿼리를 읽어 자동으로 `signinRedirect` 또는 동일한 OIDC 시작 함수를 호출하는지 확인합니다.
callback에서 state 오류 발생	userfront나 backend가 만든 `/oauth2/auth?...` URL을 직접 쓰지 말고 RP 자체 로그인 시작 URL에서 OIDC 요청을 생성해야 합니다.
등록 저장이 실패함	`auto_login_supported=true`일 때 `auto_login_url`이 비어 있거나 `http/https` URL이 아닌지 확인합니다.

구현 예시

React RP 예시입니다. 실제 프로젝트에서는 사용하는 OIDC client 라이브러리의 API에 맞춰 적용합니다.

const returnTo = searchParams.get("returnTo") || "/";
const shouldAutoLogin = searchParams.get("auto") === "1";

useEffect(() => {
  if (auth.isAuthenticated) {
    navigate(returnTo, { replace: true });
    return;
  }
  if (!shouldAutoLogin || auth.isLoading || auth.activeNavigator) {
    return;
  }
  void auth.signinRedirect({
    state: { returnTo },
  });
}, [auth, navigate, returnTo, shouldAutoLogin]);

중요한 점은 signinRedirect가 RP에서 실행되어야 한다는 것입니다. 그래야 RP가 callback 검증에 필요한 상태를 보유할 수 있습니다.

6.2 KiB Raw Blame History