콘텐츠로 이동
≡

Administrator

Developer

Tools

External Tools

13. Admin UI 사용법#

Admin UI는 KADA REST API의 관리자 웹 인터페이스로 자체 인증 모드(LOCAL 모드)에서만 유효하다. Admin UI를 통하여 API Key 관리, 권한 설정, 테넌트 DB계정 생성 등의 작업을 수행할 수 있다.

13.1 개요#

주요 기능#

기능 설명
초기 설정 Setup Token을 사용하여 첫 번째 Admin API Key 생성
API Key 관리 클라이언트별 API Key 생성, 조회, 삭제
권한 관리 API Key별 권한(READ, WRITE, CREATE, DROP, SHARED) 설정
테넌트 DB 계정 테넌트별 전용 데이터베이스 계정 생성

접속 방법#

REST API 서버 실행 후 다음 URL로 접속한다. /api는 REST 서버의 context path이며, 환경 설정에 따라 변경될 수 있다.

http://{서버IP}:{SERVER_PORT}/api/admin-ui/

예: http://localhost:8080/api/admin-ui/

13.2 초기 설정(Initial Setup)#

REST API 서버를 처음 실행하면, 서버 콘솔에 Setup Token이 출력되는데, 이 토큰을 이용하여 최초의 Admin API Key를 생성해야 한다.

Initial Setup 절차#

  1. 서버 콘솔에서 Setup Token 확인한다.
  2. 브라우저에서 Admin UI에 접속한다.
  3. Setup Token과 Admin Client ID를 입력하여 Admin API Key를 생성한다.
  4. 생성된 Admin API Key를 안전한 곳에 저장한다.
  5. 생성 완료 후 로그인 한다.

Setup Token 확인#

서버 시작 시 콘솔에 다음과 같이 Setup Token이 출력된다.

+------------------------------------------------------------------+
|  Altibase Document Access REST API                               |
|  Server started on port 8080                                     |
|                                                                  |
|  [!] INITIAL SETUP REQUIRED                                      |
|                                                                  |
|  No admin API keys found in database.                            |
|  Please complete initial setup via Admin UI:                     |
|                                                                  |
|  URL: http://localhost:8080/api                                  |
|  Admin UI: http://localhost:8080/api/admin-ui                    |
|                                                                  |
|  Setup Token: SETUP-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx         |
|                                                                  |
|  [!] Token expires at: yyyy-MM-dd HH:mm:ss                       |
+------------------------------------------------------------------+

Important

  • Setup Token은 30분 동안 유효하다.
  • Setup Token은 최초의 Admin Key 생성 후 즉시 무효화된다.
  • 기존 Setup Token이 아직 만료되지 않은 경우에는 서버를 재시작하더라도 동일한 토큰이 다시 사용될 수 있다.

Initial Setup#

REST API 서버를 실행 후Admin UI 에 최초 접속하면, Initial Setup 화면이 다음과 같이 나타난다. Setup Token 과 Admin Client ID를 입력한 후 Create Admin API Key 버튼을 클릭하면 Admin API Key가 생성된다.

입력 항목

항목 필수 설명
Setup Token ✓ 서버 콘솔에 출력된 Setup Token
Admin Client ID ✓ 관리자 클라이언트 ID (예: admin)
Description 클라이언트 설명 (선택)

Admin API Key 생성 완료#

Admin API Key 생성이 완료되면 생성된 API Key가 모달 창에 표시된다. Continue to Login 버튼을 선택하면 자동으로 로그인된다.

Important

생성된 API Key는 이 화면에서만 확인할 수 있으므로, 반드시 안전한 곳에 저장해야 한다.

로그인#

Initial Setup 이 완료되면 Continue to Login 버튼을 통해 로그인 화면으로 이동한다. 관리자 클라이언트 ID와 API Key를 입력하여 로그인 한다.

입력 항목

항목 설명
Client ID 관리자 클라이언트 ID
Admin API Key 관리자 API Key

인증 방식

  • Admin UI는 JWT 토큰기반 인증을 사용한다.
  • 로그인 성공 시 Access Token과 Refresh Token이 발급된다.
  • Access Token 만료 시 Refresh Token을 사용하여 자동 갱신된다.

13.3. API Key 관리#

API Key 목록#

메인 화면에서 등록된 모든 API Key의 목록을 확인할 수 있다.

표시 정보

컬럼 설명
Client ID 클라이언트 고유 식별자
Role 역할 (ADMIN 또는 CLIENT)
Permissions 부여된 권한 목록
Status 상태 (Active/Inactive)
Created At 생성 일시
Created By 생성자
Description 설명
Actions Edit Permissions(), Create DB User(), Delete API Key()

Note

Create DB User 버튼은 ADMIN 권한이 없는 일반 클라이언트 키에만 표시된다.

부가 기능

  • 검색 : 상단 검색창에서 Client ID로 검색
  • 새로고침 : 새로고침 버튼으로 목록 갱신
  • 페이징 : 하단 페이지네이션으로 페이지 이동

새 API Key 생성#

Create New Key 버튼을 클릭하여 새 API Key를 생성할 수 있다.

입력 항목

항목 필수 설명
Client ID ✓ 고유한 클라이언트 식별자
Permissions ✓ 부여할 권한 (최소 1개 이상)
Description 클라이언트 설명

Permissions 항목에서는 READ, WRITE, CREATE 권한이 기본 선택된다.

권한 종류:

권한 설명
READ 문서 조회 권한
WRITE 문서 생성/수정/삭제 권한
CREATE 컬렉션 생성 권한
DROP 컬렉션 삭제 권한
SHARED 공유 컬렉션 접근 권한

API Key 생성 완료#

API Key 생성 성공 시 생성된 Key가 표시된다. 이때 생성된 API Key는 이후 다시 확인할 수 없으므로, 반드시 안전한 곳에 저장해야 한다.

API Key 권한 수정#

API Key 목록에서 Edit Permissions()을 클릭하여 권한을 수정한 다음, Save Changes 버튼을 클릭한다.

API Key 삭제#

API Key 목록에서 Delete API Key()를 클릭하여 API Key를 삭제한다.

삭제된 API Key는 복구할 수 없으며, 해당 클라이언트는 더 이상 API에 접근할 수 없다.

Note

API Key 삭제 시 Tenant DB 계정으로 생성된 데이터베이스 사용자(user)는 자동 삭제되지 않는다. 필요한 경우 별도로 삭제해야 한다.

13.4 테넌트 DB 계정 생성#

테넌트별로 전용 데이터베이스 계정을 생성할 수 있다. 이 계정을 사용하면 DBeaver 등 외부 도구를 통해 직접 데이터에 접근할 수 있다.

DB 계정 생성#

API Key 목록에서 Create DB User()을 클릭하여 DB 계정 생성 모달을 연다. 데이터베이스 사용자는 Client ID 기반으로 자동 생성되므로 Client ID는 수정할 수 없다. 사용할 비밀번호를 입력한 다음 Create Account 버튼을 클릭하면 DB 계정이 생성된다.

입력 항목

항목 필수 설명
Client ID 자동 입력된다. (읽기 전용)
Password ✓ DB 사용자 비밀번호 (8자 이상)를 설정한다.

생성 결과

DB 계정 생성 시 다음 작업이 수행된다.

  • Client ID 기반으로 데이터베이스 사용자가 생성된다.
  • 해당 테넌트의 컬렉션 테이블에 대한 시노님(synonym)이 생성된다.

DB 계정 생성이 완료되면 DB Account created successfully for "{Client ID}"! 의 메시지를 확인할 수 있다.

13.5 오류 처리#

일반 오류#

오류 메시지 원인 해결 방법
Invalid credentials 잘못된 Client ID 또는 API Key 올바른 인증 정보 입력
Token expired Access Token 만료 자동 갱신됨, 실패 시 재로그인
Forbidden 권한 부족 ADMIN 권한이 있는 계정으로 로그인
Setup token not found 잘못된 Setup Token 서버 콘솔에서 Setup Token 재확인

연결 오류#

서버와의 연결할 수 없는 경우에는 다음 항목을 확인한다.

  1. REST API 서버가 실행 중인지 확인
  2. 네트워크 연결 상태 확인
  3. CORS 설정 확인 (다른 도메인에서 접속 시)