연동 개발 가이드

로그인은 Authorization Code + PKCE, 사용자 식별은 OIDC, API 호출은 JWT Bearer access token을 씁니다.

반드시 지킬 것

모든 Client가 PKCE(S256)를 씁니다. secret이 없는 앱(public client)은 예외 없이 필수입니다.
redirect URI는 등록한 값과 정확히 같아야 합니다. wildcard는 등록할 수 없습니다.
회원 식별자는 sub(회원번호)입니다. 이메일은 바뀔 수 있으므로 식별자로 쓰지 않습니다.
Resource Server는 서명, iss, aud, 만료를 모두 검증합니다. SMTOWN API의 audience는 smtown-api입니다.
refresh token은 쓸 때마다 새 값으로 바뀝니다. 이전 값을 다시 쓰면 로그인 전체가 폐기됩니다.
implicit, password grant는 지원하지 않습니다.

Endpoint

이름	메서드	경로	설명
Discovery	GET	`/.well-known/openid-configuration`	issuer, endpoint, 지원 알고리즘
인가	GET	`/oauth2/authorize`	response_type=code, client_id, redirect_uri, scope, state, code_challenge(S256) 필수
token	POST	`/oauth2/token`	authorization_code(+code_verifier), refresh_token, client_credentials
UserInfo	GET	`/userinfo`	Bearer access token. scope에 따라 sub, name, email
JWK Set	GET	`/oauth2/jwks`	서명 검증용 공개 키(kid)
폐기	POST	`/oauth2/revoke`	RFC 7009. Client 인증 필요
introspection	POST	`/oauth2/introspect`	RFC 7662. Client 인증 필요
로그아웃	GET	`/connect/logout`	OIDC RP-Initiated Logout. id_token_hint, post_logout_redirect_uri

scope

scope	내용	API
`openid`	OIDC 로그인. ID token 발급	-
`profile`	이름	/api/v1/me, /api/v1.1/me, /api/about/me
`email`	이메일(UserInfo)	-
`passport`	패스포트·스탬프	/api/v1/me/passports/**, /api/v1/me/stamps
`profile.info`	레거시 이름. 전환 기간에만 profile과 같게 처리	profile과 같음

Spring Boot Client 예

spring:
  security:
    oauth2:
      client:
        registration:
          app-login:
            provider: sm-oauth
            client-id: ${CLIENT_ID}
            client-secret: ${CLIENT_SECRET}
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
            scope: [openid, profile]
        provider:
          sm-oauth:
            issuer-uri: https://auth.smtown.com

PKCE는 OAuth2AuthorizationRequestCustomizers.withPkce()로 켭니다. 전체 예제는 저장소의 service-client 모듈을 보세요.

기존 서버 경로(지원하지 않음)

새 서버에서는 동작하지 않습니다. 새 경로로 바꿔 연동해 주세요.

기존 서버	새 서버
`/oauth/authorize`	/oauth2/authorize
`/oauth/token`	/oauth2/token
`/oauth/check_token`	JWT 직접 검증(issuer-uri, audiences)
`GET /oauth/revoke`	POST /oauth2/revoke