AXHub

커넥터 등록하고 승인하기

회사 데이터베이스를 커넥터로 등록하고, 누가 어디까지 조회할 수 있는지 grant로 승인하는 방법이에요.

회사에서 쓰는 데이터베이스를 앱에서 조회할 수 있게 열어 주는 일이에요.
연결 등록과 접근 승인 두 가지를 하면, 그다음부터는 승인받은 사람이 각자 자기 앱에서 가져다 써요.

접속 정보는 AxHub가 맡아 관리해서 앱 코드에는 회사 DB 비밀번호가 전혀 남지 않아요.

준비물

  • 회사 관리자 권한 — 커넥터 등록과 승인은 관리자만 할 수 있어요
  • CLI 로그인 — axhub로 시작하는 명령어 도구예요

연결 등록

회사 데이터베이스를 커넥터로 등록해요. Google Drive는 터미널에서 바로 연결할 수 있어요.

axhub connectors google start        # 브라우저 인가 URL 받기
axhub connectors google finalize     # 인가 후 커넥터 생성

등록된 커넥터에 어떤 테이블 · 리소스가 있는지는 탐색(discovery)을 실행해 목록으로 만들어요. 이 목록이 있어야 범위를 지정해 승인할 수 있어요.

axhub connectors discover <connector_id> --execute

<connector_id>에는 axhub connectors list --json의 .data[].id(UUID)를 넣어요. 막 등록한 커넥터는 아직 grant가 없어서 axhub connectors mine에는 나오지 않아요.

AxHub 앱의 DB도 커넥터로 열 수 있어요. 어떤 앱이 쌓은 데이터를 다른 사람이 조회하게 하고 싶을 때 써요.

axhub connectors app-db eligible-apps        # 열 수 있는 앱 목록
axhub connectors app-db create --app <앱> --execute

접근 승인 (grant)

커넥터가 있어도 승인 없이는 아무도 조회할 수 없어요. grant로 네 가지를 정해서 승인해요.

정하는 것내용
누가subject — 사람 · 그룹 · 조직 단위
어떤 커넥터를등록해 둔 커넥터 중 하나
어떤 액션 묶음으로preset — 예: 읽기 전용
(선택) 어떤 테이블 범위까지범위를 지정하면 그 밖은 아예 조회할 수 없어요

범위를 지정하면 자유 SQL이 막혀요. 범위 지정 grant로는 임의 쿼리를 못 돌리고(403 scope_requires_target), 범위 밖 리소스에 접근하면 403 scope_out_of_range가 나요. 넓게 열지, 좁게 잠글지를 정하는 스위치예요.

승인이 잘 걸렸는지는 승인받은 사람 계정에서 이렇게 확인해요.

axhub authz grants mine                    # 내 활성 grant 목록
axhub connectors mine                      # 내가 조회할 수 있는 커넥터 (이름 · 엔진)
axhub connectors mine --json               # 같은 목록 — .data[].id 가 커넥터 ID(UUID)
axhub connectors resources <connector_id>  # 그 커넥터의 리소스 트리

<connector_id>에는 이름이 아니라 axhub connectors mine --json의 .data[].id(UUID)를 넣어요. 사람이 읽는 axhub connectors mine 출력에는 ID가 나오지 않아요. 관리자 계정에서 axhub connectors resources <connector_id> --admin으로 grant와 상관없이 볼 때는 axhub connectors list --json의 .data[].id를 넣어요.

grant 없는 커넥터는 목록에조차 나오지 않아요. 개발자가 "커넥터가 안 보인다"고 하면 승인이 아직 안 된 거예요.

행·열까지 잠그기 (접근 정책)

grant가 "어떤 테이블까지"를 정했다면, 접근 정책은 같은 테이블 안에서 "어느 행, 어느 열까지"를 정해요.
예를 들면 "영업팀은 주문 테이블에서 자기 지역 행만 보고, 연락처 열은 가린다"가 정책 하나예요.

만들고 붙이기

정책은 콘솔 커넥터·정책 › 접근 정책 › 데이터 범위 (행·열) 에서 만들어요.
만든 정책은 커넥터의 [권한] 탭에서 grant에 붙여요. 새로 권한을 줄 때는 멤버 추가 화면에서 고르고, 이미 있는 권한은 그 행의 [정책 편집] 버튼으로 바꿔요.

CLI에는 조회 명령만 있어요(axhub authz policies list · show). 만들기와 수정은 콘솔에서 해요.

정책에 담는 두 가지

정책 하나에는 행 필터와 열 정책을 담아요. 둘 중 하나만 있어도 돼요.

행 필터는 열 연산자 값 형태의 조건 하나예요. 연산자는 = != < <= > >= in 일곱 가지만 돼요. 서브쿼리나 함수, 여러 조건 조합은 안 돼요. 조건을 더 걸고 싶으면 정책을 여러 개 붙이면 되고, 붙인 정책은 전부 AND로 결합돼요.

열 정책은 세 모드 중 하나예요.

모드하는 일
allow허용한 열만 보여요. 비워 두면 전체 허용이에요
deny그 열을 응답에서 제거해요
mask값을 ***로 가려요

정책을 만들 때 적용 대상 테이블을 꼭 지정하세요. 대상 없이 만들면 그 grant의 모든 조회에 걸려서, 필터 열이 없는 다른 테이블 조회까지 column "..." does not exist로 실패해요(fail-closed).

알아두면 좋은 동작

행 필터는 조회 쿼리를 감싸서 거는 방식이라, 세 가지 동작을 알아 두면 좋아요.

  • SELECT 목록에 필터 열이 있어야 해요. SELECT *는 항상 안전해요. 정책이 여러 개면 각 정책의 필터 열이 전부 필요하고, 빠지면 column not found로 실패해요.
  • LIMIT · ORDER BY는 필터보다 먼저 실행돼요. LIMIT 10을 요청해도 필터를 통과한 행은 그보다 적을 수 있어요.
  • 마스킹(***)은 화면 표시만 가려요. 가린 열로도 정렬, 비교, 집계는 실제 값 기준으로 동작해요. 값 자체를 막으려면 deny를 쓰세요.

세 축이 함께 좁혀요

preset, grant 범위, 접근 정책이 동시에 걸리면 전부 AND로 좁혀져요. 정책이 grant보다 넓게 열어 주는 일은 없어요.

축정하는 것
preset어떤 액션(SELECT 등)을
grant 범위어떤 테이블까지
접근 정책그 테이블의 어느 행, 어느 열까지

행 필터가 적용되는 조회에서는 UPDATE · DELETE가 거부돼요. 필터 밖 행까지 건드릴 수 있어서예요. 그리고 grant에 붙어 있는 정책은 삭제가 막혀요("활성 권한이 사용 중"). 지우려면 먼저 grant에서 떼세요.

조회는 이렇게 통제돼요

승인한 뒤 실제 조회에는 세 겹의 안전장치가 걸려요.

안전장치내용
허용된 액션만grant의 preset이 허용한 액션만 실행돼요. 기본 읽기 전용 preset은 SELECT · WITH · EXPLAIN 같은 읽기 쿼리만 통과시켜요
안전 쿼리값은 SQL과 분리해 전달되고, 모든 조회는 허용 · 거부 여부와 함께 감사 기록으로 남아요
임시 세션조회는 게이트웨이 세션으로만 되고, 세션은 8시간이 지나면 자동으로 닫혀요

이렇게 보이면 성공

승인한 사람의 계정에서 axhub connectors mine에 커넥터가 보이면 성공이에요. 그다음부터는 각자 앱에서 커넥터로 회사 데이터 연결하기를 보고 조회하면 돼요.