MySQL용 vsql_oauth2 확장 기능

vsql_oauth2는 계정이 비밀번호 대신 JWT로 로그인하게 합니다. 확장 기능은 JWKS 엔드포인트에서 가져온 키 또는 정적 공개 키 하나로 토큰의 서명을 검증하고, 토큰이 만료되지 않았는지 확인하며, 토큰 안의 클레임을 VillageSQL 계정에 매핑합니다. 자격 증명을 발급하는 곳은 여전히 ID 공급자뿐입니다.


관리자	VillageSQL
소스 및 전체 문서	villagesql/vsql-oauth2
라이선스	GPL-2.0
기능 단계	미리 보기

이 확장 기능은 미리 보기 기능을 사용하므로 vsql_allow_preview_extensions가 ON이어야 합니다. 서버를 --vsql_allow_preview_extensions=ON으로 시작하거나 SET PERSIST vsql_allow_preview_extensions = ON을 실행하세요. 그렇지 않으면 INSTALL EXTENSION이 거부됩니다.

설치

설치 스크립트, Docker 이미지 또는 릴리스 tarball로 VillageSQL을 설치했다면 vsql_oauth2.veb는 이미 서버의 lib/veb/ 디렉터리에 있습니다. 문 하나로 서버에 설치하세요:

INSTALL EXTENSION vsql_oauth2;

설치되었는지 확인합니다:

SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_oauth2';

+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_oauth2    |
+----------------+

직접 빌드하려면 저장소의 빌드 지침을 따르세요.

추가되는 기능

SQL 함수가 아니라 인증 플러그인을 추가합니다. 계정을 만들 때 플러그인을 지정하면, 그 계정은 토큰을 제시하여 인증합니다:

CREATE USER 'analyst'@'%' IDENTIFIED WITH vsql_oauth2;

SELECT user, plugin FROM mysql.user WHERE user = 'analyst';

+---------+-------------+
| user    | plugin      |
+---------+-------------+
| analyst | vsql_oauth2 |
+---------+-------------+

세션은 연결한 계정이 아니라 토큰이 지정하는 계정으로 실행됩니다. 그 이름은 username_claim의 클레임(기본값 sub)이 제공합니다. 그 값이 analyst이면 위의 문만으로 충분합니다. 이메일 주소처럼 다른 것을 가리키면, 그 계정도 만들고 연결 계정이 그 계정으로 프록시하게 하세요:

CREATE USER 'oidc_user'@'%' IDENTIFIED WITH vsql_oauth2;
CREATE USER 'alice@example.com' ACCOUNT LOCK;
GRANT SELECT ON app.* TO 'alice@example.com';
GRANT PROXY ON 'alice@example.com' TO 'oidc_user'@'%';

ACCOUNT LOCK은 누구도 alice@example.com으로 직접 로그인하지 못하게 하며, 잠긴 계정에도 프록시 권한은 동작합니다. validate_password를 실행하는 서버는 잠김 여부와 상관없이 비밀번호 없는 계정 생성을 거부하며, ERROR 1819 (HY000): Your password does not satisfy the current policy requirements 오류로 답합니다. 이 경우에는 아무도 모르는 비밀번호를 계정에 부여하세요. 프록시 권한이 없으면 로그인이 ERROR 6126 (HY000): Access denied for user 'oidc_user'@'localhost', missing proxy privilege. 오류로 거부됩니다. 나머지는 모두 구성입니다.

설정	기본값	제어 대상
`vsql_oauth2.jwks_url`	비어 있음	서명 키를 가져오는 위치. 정적 키보다 우선
`vsql_oauth2.public_key`	비어 있음	JWKS 엔드포인트가 없는 공급자용 정적 공개 키
`vsql_oauth2.jwks_refresh_interval`	`3600`	키를 다시 가져오는 주기(초)
`vsql_oauth2.jwks_http_timeout`	`5`	가져오기에 허용되는 시간(초)
`vsql_oauth2.issuer`	비어 있음	설정 시 토큰이 가져야 하는 `iss` 클레임
`vsql_oauth2.audience`	비어 있음	설정 시 토큰이 가져야 하는 `aud` 클레임
`vsql_oauth2.username_claim`	`sub`	계정 이름을 지정하는 클레임
`vsql_oauth2.roles_claim`	비어 있음	역할을 담은 클레임
`vsql_oauth2.roles_filter`	비어 있음	그 역할 중 고려할 역할
`vsql_oauth2.roles_transform_pattern`, `vsql_oauth2.roles_transform_replacement`	비어 있음	공급자의 역할 이름을 데이터베이스 역할 이름으로 바꾸는 방법
`vsql_oauth2.auto_create`	`OFF`	알 수 없는 주체가 첫 로그인 시 계정을 받는지 여부
`vsql_oauth2.auto_grant`	`OFF`	`OFF`/`ON`/`SYNC` — `OFF`는 이미 부여된 역할만 활성화; `ON`은 DB 역할로 존재하는 클레임 역할도 부여; `SYNC`는 그에 더해 토큰이 더 이상 클레임하지 않는 부여된 역할을 기본 역할을 제외하고 회수

RSA 서명은 RS256, RS384, RS512로, ECDSA 서명은 ES256, ES384, ES512로 허용됩니다.

auto_create와 auto_grant는 기본적으로 꺼져 있으며, 그 기본값이 안전한 선택입니다. 이를 켜면 누가 여기에 계정을 갖고 무엇에 접근할 수 있는지를 ID 공급자가 결정하게 되므로, 켜기 전에 roles_filter의 범위를 정하세요. auto_grant = SYNC는 더 나아가, 운영자가 계정의 DEFAULT ROLE로 설정한 역할을 제외하고 토큰이 클레임하지 않는 계정의 모든 역할을 회수합니다.

SET PERSIST로 쓴 설정은 재시작 후에도 유지되지만, UNINSTALL EXTENSION이 이를 삭제합니다. 제거 후 다시 설치하면 모든 설정이 기본값으로 돌아가며, 재시작해도 이전 값은 돌아오지 않습니다.

상태 변수

변수	설명
`vsql_oauth2.jwks_fetch_failures`	JWKS 가져오기가 실패하고 사용할 캐시된 키가 남아 있지 않아 실패한 로그인 수. 캐시된 키로 대체되는 실패한 갱신은 세지 않습니다.

참고 항목

MySQL에서의 JWT 인증 — 실제 로그인 예제, 클레임 매핑, 거부된 토큰이 잘못된 비밀번호처럼 보이는 이유
확장 기능 관리 — 확장 기능 설정을 읽고 쓰는 방법
미리 보기 기능 — 미리 보기 플래그가 켜는 것과 보장하는 것
사용 가능한 확장 기능 — 전체 카탈로그
villagesql/vsql-oauth2 — 소스, 실제 공급자 설정 예제, 알려진 제한 사항

확장 기능 설치 및 실행

확장 기능 카탈로그

확장 기능 빌드

설치

추가되는 기능

상태 변수

참고 항목

​설치

​추가되는 기능

​상태 변수

​참고 항목

설치

추가되는 기능

상태 변수

참고 항목