시작하기 · Issuary

issuary를 통해 사용자를 인증하려는 애플리케이션은 먼저 OAuth/OIDC 클라이언트로 등록해야 해요. 클라이언트 등록은 config.yaml의 clients 섹션에서 할 수 있어요.

# config.yaml
clients:
  - id: my-app
    name: My Application
    client_id: my-app-client-id
    client_secret: my-app-client-secret
    redirect_uris:
      - https://myapp.example.com/callback
    response_types:
      - code
    grant_types:
      - authorization_code
      - refresh_token
    scope: openid profile email

설정 항목

항목	필수	설명
`id`	O	클라이언트의 내부 고유 식별자예요.
`name`	O	사용자에게 표시될 애플리케이션 이름이에요. 동의 화면에서 보여요.
`logo_uri`	X	동의 화면에 표시될 로고 이미지 URL이에요.
`client_id`	O	OAuth 요청에서 사용하는 공개 클라이언트 식별자예요.
`client_secret`	△	클라이언트 시크릿이에요. 기밀 클라이언트(서버 측 앱)에서만 필요하며, 공개 클라이언트(SPA/모바일)에서는 생략해요.
`redirect_uris`	O	인증 후 리다이렉트할 수 있는 허용 URL 목록이에요.
`response_types`	O	허용할 OAuth 응답 유형이에요. 일반적으로 `code`를 사용해요.
`grant_types`	O	허용할 OAuth 권한 부여 유형이에요.
`scope`	O	허용할 OAuth 스코프(공백으로 구분)예요.

기밀 클라이언트 vs 공개 클라이언트

OAuth에서는 클라이언트를 두 가지 유형으로 구분해요.

기밀 클라이언트 (Confidential Client)

서버 측에서 시크릿을 안전하게 보관할 수 있는 애플리케이션이에요. client_secret을 설정하며, 토큰 교환 시 시크릿을 함께 전송해요.

Next.js, Express, Spring Boot 등 서버 사이드 앱
client_secret이 필수

clients:
  - id: web-server-app
    name: Web Server App
    client_id: web-server-client
    client_secret: ${WEB_SERVER_SECRET}
    redirect_uris:
      - https://myapp.com/api/callback
    response_types:
      - code
    grant_types:
      - authorization_code
      - refresh_token
    scope: openid profile email

공개 클라이언트 (Public Client)

클라이언트 측 코드에서 시크릿을 안전하게 보관할 수 없는 애플리케이션이에요. client_secret을 생략하며, 대신 PKCE 를 사용하여 보안을 확보해요.

React SPA, Vue SPA, 모바일 앱 등
client_secret 생략

clients:
  - id: spa-app
    name: Single Page App
    client_id: spa-client
    redirect_uris:
      - https://myapp.com/callback
    response_types:
      - code
    grant_types:
      - authorization_code
      - refresh_token
    scope: openid profile email

OIDC Discovery

등록된 클라이언트 애플리케이션은 issuary의 OIDC Discovery 엔드포인트를 사용하여 인증에 필요한 정보를 자동으로 가져올 수 있어요.

{server.public_origin}/.well-known/openid-configuration

이 엔드포인트는 인증, 토큰, 사용자 정보, JWKS 등의 엔드포인트 URL을 반환해요. 대부분의 OIDC 클라이언트 라이브러리는 이 URL만으로 자동 설정이 가능해요.

다음 단계

클라이언트를 등록한 후 실제 애플리케이션에 연동하는 방법은 다음 가이드를 참고해 주세요.

Next.js 연동 - 서버 사이드 앱 (기밀 클라이언트)
React SPA 연동 - 클라이언트 사이드 앱 (공개 클라이언트)

권한 동의와 자사 앱

로그인·회원가입 화면에는 앱이나 권한 배너를 표시하지 않아요. 인증과 필수 약관 처리를 완료한 뒤, 클라이언트로 돌아가기 직전에 필요한 경우에만 OAuth 권한 동의를 받아요.

일반 앱은 skip_consent를 생략하거나 false로 두고, 보통 prompt도 생략해요. 최초에 승인한 권한은 이후 동일하거나 더 적은 권한의 요청에서 재사용해요. 권한 추가나 동의 철회 시에는 다시 동의가 필요해요.

자사 앱은 관리자가 등록된 권한을 사전 승인하도록 skip_consent: true를 설정할 수 있어요.

clients:
  - id: first-party-web
    name: First-party Web App
    client_id: first-party-web
    redirect_uris:
      - https://app.example.com/callback
    response_types: [code]
    grant_types: [authorization_code, refresh_token]
    scope: openid profile email offline_access
    skip_consent: true

이 예제는 공개 클라이언트이므로 S256 PKCE를 사용해야 해요. 기밀 클라이언트는 client_secret도 설정하세요.

사전 승인은 등록된 권한에만 적용되며, 허용된 offline_access도 포함해요. 로그인, 이메일 인증, 필수 2단계 인증, 필수 약관, 리다이렉트 URI 및 PKCE 검증은 생략하지 않아요. Device Authorization의 기기 승인도 계속 필요해요.

인증 요청	동작
`prompt` 생략	세션·기존 승인·서버 정책에 따라 필요한 화면만 표시해요.
`prompt=login`	재인증해요. 권한 동의는 클라이언트 정책을 따라요.
`prompt=consent`	사전 승인된 앱도 명시적인 동의를 받아요.
`prompt=none`	화면을 표시하지 않아요. 처리가 불가능하면 `login_required`, `consent_required`, `interaction_required` 등을 반환해요.

사전 승인으로 생략한 동의는 사용자 동의 기록으로 저장하지 않아요. 설정을 끄면 다음 인증 요청부터 실제 사용자 동의 이력을 사용하며, 이력이 없으면 동의를 받아요. 사용자 동의를 철회해도 관리자의 사전 승인이 취소되지는 않아요. 설정 변경은 기존 토큰을 폐기하지 않으므로, 필요하면 토큰 폐기나 클라이언트 관리 기능을 사용하세요.

오프라인 접근

Authorization Code Flow에서 offline_access는 앱의 사전 승인, prompt=consent 요청, 또는 유효한 기존 오프라인 접근 동의가 있을 때 유지해요. Issuary는 명시적으로 승인한 오프라인 접근을 철회 전까지 지속되는 승인으로 취급해요. 동의 화면에도 사용자 부재 중 접근과 철회 전까지 권한이 유지된다는 의미를 안내해요.

승인 근거가 없으면 offline_access를 제외하고 나머지 권한으로 진행해요. 인가 코드를 반환하지 않는 요청에서도 이 권한을 제외해요. 동의 화면·저장된 동의·인가 코드·토큰 응답은 실제 승인되는 권한을 사용해요. offline_access가 승인되고 클라이언트가 refresh_token grant를 허용해야 refresh token을 발급해요.

일반 앱이 처음 오프라인 접근을 요청할 때는 prompt=consent를 사용하세요. 승인 후에는 prompt를 생략할 수 있어요. 사전 승인된 자사 앱은 최초부터 생략할 수 있어요.

OIDC 권한 동의와 오프라인 접근 규격을 참고하세요.