ompass-sdk 1.0.0

OMPASS FIDO2 MFA Web API SDK for Python

OMPASS Python SDK

OMPASS FIDO2 MFA 솔루션의 Web API를 Python에서 쉽게 사용할 수 있는 SDK입니다.

요구 사항

• Python 3.9 이상

설치

pip install ompass-sdk

빠른 시작

1. 클라이언트 초기화

from ompass import OmpassClient, OmpassConfig

config = OmpassConfig(
    client_id="your-client-id",
    secret_key="your-secret-key",
    base_url="https://your-tenant.ompasscloud.com",  # 테넌트별 API URL (필수)
    connect_timeout=30,  # 초 (기본값: 30)
    read_timeout=30,     # 초 (기본값: 30)
)

client = OmpassClient(config)

2. 인증 시작

사용자의 OMPASS 인증을 시작합니다.

from ompass import AuthStartRequest, Language, LoginClientType

request = AuthStartRequest(
    username="user123",
    lang_init=Language.KR,
    login_client_type=LoginClientType.BROWSER,
    session_timeout_seconds=300,
)

response = client.start_auth(request)

# 클라이언트에 전달하여 팝업 또는 리다이렉트
ompass_url = response.ompass_url

3. 토큰 검증

인증 완료 후 리다이렉트로 받은 토큰을 검증합니다.

from ompass import TokenVerifyRequest

request = TokenVerifyRequest(
    username="user123",
    token="received-token-from-redirect",
)

response = client.verify_token(request)

if response.is_verified:
    # 인증 성공
    print(f"인증 완료: {response.username}")

4. 인증기 목록 조회

사용자의 등록된 인증기 목록을 조회합니다.

response = client.get_authenticators("user123")

for auth in response.authenticators:
    print(f"{auth.type} - {auth.status}")
    if auth.mobile_device:
        print(f"  기기: {auth.mobile_device.device_name}")

5. 인증 장치 삭제

사용자의 인증 장치를 삭제합니다.

client.delete_authenticator("authenticator-id")

6. 리소스 정리

# 직접 호출
client.close()

# 또는 Context Manager 사용
with OmpassClient(config) as client:
    response = client.start_auth(request)

예외 처리

SDK는 두 가지 예외 타입을 제공합니다.

OmpassException

일반적인 SDK 오류 (네트워크 오류, JSON 파싱 오류 등)

from ompass import OmpassException

try:
    client.start_auth(request)
except OmpassException as e:
    print(f"Error: {e}")

OmpassApiException

API 응답 오류 (4xx, 5xx 상태 코드)

from ompass import OmpassApiException

try:
    client.start_auth(request)
except OmpassApiException as e:
    print(f"HTTP Status: {e.http_status_code}")
    print(f"Error Code: {e.error_code}")
    print(f"Error Message: {e.error_message}")

API 참조

OmpassConfig

파라미터	타입	설명	필수	기본값
client_id	str	OMPASS 클라이언트 ID	O	-
secret_key	str	OMPASS 시크릿 키	O	-
base_url	str	테넌트별 API URL	O	-
connect_timeout	int	연결 타임아웃 (초)	X	30
read_timeout	int	읽기 타임아웃 (초)	X	30

AuthStartRequest

필드	타입	설명	필수
username	str	사용자 ID	O
lang_init	Language	초기 언어 (KR, EN, JP)	X
login_client_type	LoginClientType	클라이언트 타입	X
session_timeout_seconds	int	세션 타임아웃 (초)	X

AuthStartResponse

필드	타입	설명
username	str	사용자 ID
ompass_url	str	OMPASS 인증 URL
registered_ompass	bool	OMPASS 등록 여부

TokenVerifyRequest

필드	타입	설명	필수
username	str	사용자 ID	O
token	str	인증 토큰	O

TokenVerifyResponse

필드	타입	설명
client_id	str	클라이언트 ID
application_name	str	애플리케이션 이름
username	str	사용자 ID
is_verified	bool	검증 성공 여부 (property)

지원 언어

• Language.KR - 한국어
• Language.EN - 영어
• Language.JP - 일본어

클라이언트 타입

• LoginClientType.BROWSER - 웹 브라우저
• LoginClientType.MOBILE_APP - 모바일 앱
• LoginClientType.DESKTOP_APP - 데스크톱 앱

빌드

# 의존성 설치
pip install -e ".[dev]"

# 테스트
pytest

# 패키지 빌드
python -m build

라이선스

이 프로젝트는 독점 라이선스 하에 있습니다.