vsql_allow_preview_extensions = ON이 필요합니다. 미리보기 계층을 활성화하고 기능을 등록하는 방법은 미리보기 기능을 참조하세요.
auth 기능(vsql::preview::auth)은 확장 프로그램이 서버 인증 방식을 제공할 수 있게 해줍니다. 계정은 CREATE USER ... IDENTIFIED WITH <method-name>으로 이를 선택합니다. 연결 시점에 그 이름이 로드된 MySQL 인증 플러그인이 아니면, 서버는 VEF 인증 레지스트리를 조회하고 핸드셰이크 전반에 걸쳐 확장 프로그램의 핸들러를 호출합니다. MySQL 인증 플러그인을 작성하지 않고도 서버가 알지 못하는 자격 증명 소스 — 베어러 토큰, 외부 신원 공급자, 또는 사용자 정의 챌린지 — 를 기준으로 계정을 인증하는 데 사용하세요.
기능 이름 VEF_PREVIEW_AUTH_NAME은 "vsql::preview::auth"입니다.
핸들러는 AuthContext를 받는 타입이 지정된 함수입니다: 서버가 소유한 이 컨텍스트를 통해 핸드셰이크 패킷을 읽고 쓰면서 클라이언트와 통신하며, MySQL의 내부 인증 구조체는 전혀 보지 않습니다.
기능 선언
헤더를 포함하고, 타입이 지정된 핸들러를 작성하고, 플루언트make_auth<> 빌더로 디스크립터를 구축한 후, 그 디스크립터를 .with()에 전달할 AuthCapability 토큰에 넘깁니다. 미리보기 기능 헤더는 <villagesql/vsql.h> 우산 헤더에 포함되지 않으므로, <villagesql/preview/auth.h>를 명시적으로 포함하세요:
AuthCapability g_auth{descriptor}는 .with()가 사용하는 자체 등록 토큰입니다. 등록보다 오래 유지되도록 static으로 선언하세요.
client_plugin은 선택적입니다. make_auth는 광고되는 플러그인을 "mysql_clear_password" — 모든 MySQL 클라이언트가 제공하는 최소 공통 분모 — 로 기본 설정하므로, .client_plugin()을 전혀 호출하지 않는 방식도 설치되고 단순한 클라이언트도 연결됩니다. 다른 플러그인을 요청하려면 .client_plugin(name)을 호출하세요. mysql_clear_password는 베어러 토큰을 비밀번호 슬롯에 그대로 받습니다.
방식이 요청한 것과 다른 플러그인을 제안하는 클라이언트는 요청된 플러그인으로 전환되어 자격 증명을 그대로 다시 보내며, 이는 왕복 한 번의 비용이 들고 그 전환을 받아들이는 클라이언트가 필요합니다. .accepts_client_plugin(&callback)은 방식이 제안된 플러그인을 그대로 유지할 수 있게 합니다: 서버는 제안된 각 이름을 콜백에 전달하며, 요청된 플러그인도 포함되지만 이는 콜백의 반환 값과 무관하게 허용됩니다. 콜백을 설정하지 않은 방식은 다른 어떤 제안도 허용하지 않으므로, 다른 모든 제안은 요청된 플러그인으로 전환됩니다. 허용은 최종적입니다 — 서버는 그 후에 요청된 플러그인으로 되돌리지 않습니다 — 따라서 핸들러가 실제로 그 프레이밍을 해석하는 플러그인만 허용하세요. 서버는 핸들러의 첫 읽기 이전인 핸드셰이크 협상 중에 콜백을 조회하므로, 콜백은 순수 술어여야 합니다: 패킷 I/O 없음, 블로킹 없음, 부작용 없음.
핸들러 계약
핸들러는AuthHandler 유형과 일치합니다 — AuthContext &를 받고 AuthResult를 반환합니다:
AuthContext는 서버가 소유한 시도별 컨텍스트를 감쌉니다. 호출 기간 동안만 보유하고 보관하지 마세요. 함수 테이블을 통해 컨텍스트 포인터를 전달하는 대신 그 메서드를 호출하세요. 토큰 기반 핸들러가 사용하는 메서드:
핸들러는 세 가지 결과 중 하나를 반환합니다:
AuthResult::kReject와 AuthResult::kError 둘 다 연결을 거부합니다. AuthResult::kOk만 성공합니다.
핸들러가 연결하는 계정을 다른 유효 계정으로 매핑할 때 — 아래 예제가 연결하는 계정을 vsql_auth_test_user로 매핑하는 것처럼 — 그것은 프록시이며, MySQL 플러그인 인증 경로에서와 똑같이 GRANT PROXY가 필요합니다.
활성 역할 스테이징
c.set_active_roles(roles, n_roles)는 세션에서 활성화되어야 하는 역할을 스테이징하며, 이 로그인에 대해 계정의 기본 역할 활성화를 대체합니다. roles는 NUL로 끝나는 이름 n_roles개의 배열입니다. 문자열은 복사되므로 호출자가 유지할 필요가 없습니다. 서버는 계정 확인 후에 SET ROLE과 동일한 부여 검사 활성화를 사용하여 이를 적용합니다: 인증된 계정에 실제로 부여된 역할만 활성화되고, 부여되지 않은 이름은 조용히 건너뜁니다 — 따라서 방식이 .roles_mode()를 설정하지 않는 한, 토큰은 DBA가 프로비저닝한 범위를 넘어 권한을 부여하거나 상승시킬 수 없습니다. n_roles == 0을 전달하면 어떤 역할도 활성화되지 않습니다(SET ROLE NONE과 동등).
완전한 예제
어떤 릴리스에도 포함되지 않는, 서버 소스 트리의villagesql/test-extensions/vsql-auth-test/에 있는 vsql_auth_test 확장 프로그램에서 축약한 최소 인증기입니다. 고정된 토큰 하나를 허용하고, 연결을 vsql_auth_test_user로 매핑하며, 토큰이 비밀번호 슬롯에 그대로 도착하도록 mysql_clear_password를 요청합니다. (인트리 확장 프로그램은 테스트 스위트를 구동하기 위해 추가 토큰 경로, .accepts_client_plugin() 콜백, 그리고 아래에 설명된 두 옵트인을 모두 추가합니다.)
계정 바인딩 및 연결
미리보기 계층이 활성화된 상태에서(참조: 미리보기 계층 활성화), 확장 프로그램을 빌드하고, 그.veb 파일을 veb_dir에 복사하고, 설치한 다음, 계정을 방식에 바인딩합니다. 핸들러가 두 번째 계정으로 매핑하므로, 그 계정도 생성하고 연결하는 계정이 그 신원을 취할 수 있도록 PROXY 권한을 부여합니다:
vsql_auth_test가 등록된 VEF 인증 방식이기 때문에 CREATE USER ... IDENTIFIED WITH vsql_auth_test가 허용됩니다 — 설치된 플러그인 이름이 허용되는 것과 동일한 방식입니다.
IDENTIFIED WITH <method> 형식만 허용되며, 선택적으로 AS '...'를 붙일 수 있습니다. BY '...'를 추가하는 것은 방식에게 비밀번호를 저장된 자격 증명으로 변환하라고 요청하는 것인데 — MySQL 플러그인이 generate_authentication_string()을 통해 수행하는 작업입니다 — 오늘날 어떤 VEF 인증 방식도 그 훅을 선언하지 않으므로 서버가 이를 거부합니다:
plugin 컬럼에 기록되며, 이것이 그 계정의 다음 로그인이 읽는 값입니다:
mysql_clear_password를 요청하므로, 클라이언트는 토큰을 평문으로 보내기 위해 --enable-cleartext-plugin을 전달해야 합니다. 올바른 토큰이면 세션은 매핑된 계정으로 실행되고 @@external_user를 통해 연결하는 계정을 노출합니다:
계정 자동 생성
방식은 아직 존재하지 않는 계정의 로그인도 처리하고, 로그인이 성공하는 과정의 일부로 서버가 계정을 생성하도록 할 수 있습니다. 이것이 없으면 알 수 없는 계정은 어떤 방식이 실행되기도 전에 거부됩니다..auto_create(&callback)으로 옵트인합니다. 콜백은 인수를 받지 않고 bool을 반환합니다. 서버는 등록 시점에 한 번 읽는 것이 아니라 알 수 없는 계정의 로그인마다 이를 호출하므로, 방식은 확장 프로그램이 로드될 때 선택을 고정하는 대신 자체 런타임 설정을 따를 수 있습니다:
.auto_create()를 생략하거나 콜백에서 false를 반환하면 표준 동작이 유지됩니다: 알 수 없는 계정은 거부됩니다. 한 번에 설치된 방식 중 하나만 옵트인할 수 있습니다 — 둘이 true를 반환하면 서버는 추측하기를 거부하고, 오류 로그에 경고를 기록하며, 아무도 옵트인하지 않은 것처럼 알 수 없는 계정을 거부합니다.
핸들러에서는 c.account_unknown()이 두 경우를 구분합니다. 먼저 자격 증명을 검증한 다음, 무엇을 생성할지 기술하고 그 계정으로 인증합니다:
request_provision(account, roles, n_roles)는 의도를 기록하고 아무것도 반환하지 않습니다. 서버는 핸들러가 AuthResult::kOk을 반환한 후에 DDL을 직접 실행하며, 알 수 없는 계정으로 라우팅된 로그인에 대해서만 실행합니다 — 따라서 핸들러가 이어서 거부하는 로그인은 아무것도 생성하지 않고, 이미 존재하는 계정을 지정한 요청의 경우 그 계정은 바인딩을 유지하면서 지정된 역할을 그대로 받습니다. 서버가 실행하는 것은 CREATE USER IF NOT EXISTS <account>@'%' IDENTIFIED WITH <method>이며, 그 뒤에 지정된 역할마다 하나씩 GRANT가 이어집니다: 계정은 항상 호스트 %에 대해 생성되고 자신을 인증한 방식에 바인딩되며, account가 연결하는 사용자 이름일 필요는 없습니다. 생성을 수행할 수 없으면 — 예를 들어 super_read_only 서버에서 — 계정 없이 진행하는 대신 로그인이 실패합니다.
서버는 자동 CREATE USER와 그 GRANT, 그리고 역할 조정을 위한 GRANT와 REVOKE를 바이너리 로그에 기록하지 않습니다. 복제 토폴로지의 각 서버는 계정을 스스로 생성하고 조정합니다.
역할은 활성 역할 스테이징에서와 동일하게 동작합니다: DBA가 이를 소유합니다. 각 이름은 부여 가능한 역할로 이미 존재해야 하며, 부여할 수 없는 이름은 로그인을 실패시키지 않고 로깅된 후 건너뜁니다. 따라서 토큰은 역할을 지정할 수는 있어도 결코 생성하거나 상승시킬 수 없습니다. 계정 이름은 클라이언트에서 오므로 서버는 이를 식별자로 인용합니다 — 조작된 이름은 이상한 이름의 계정 하나가 될 뿐, 결코 두 번째 문이 되지 않습니다.
vsql_auth_test 확장 프로그램은 연결하는 사용자에게 vsql_role_granted 역할을 프로비저닝하며, 옵트인을 OFF로 시작하는 vsql_auth_test.auto_create 뒤에 둡니다. 이를 켜고 역할을 먼저 생성한 다음, 존재하지 않는 계정으로 연결하세요:
역할 자동 부여
기본적으로 토큰이 지정한 역할은 계정이 이미 그것을 보유한 경우에만 적용됩니다. 보유하지 않은 역할은 건너뛰며, 서버는 그 이유를 로깅합니다(VEF auth: role '<role>'@'<host>' requested for account '<user>'@'<host>' is not granted; skipping). .roles_mode(&callback)은 이를 바꿉니다: 콜백은 vef_auth_roles_mode_t — VEF_AUTH_ROLES_ACTIVATE(기본값), VEF_AUTH_ROLES_GRANT, 또는 VEF_AUTH_ROLES_SYNC — 를 반환하고, 서버는 로그인마다 그에 따라 스테이징된 역할을 계정의 부여된 역할과 조정합니다.
콜백은 .auto_create()와 형태가 같습니다 — 인수가 없습니다 — 하지만 bool 대신 모드 열거형을 반환하며, 서버가 로그인마다 호출하여 그 뒤에 있는 값을 실시간으로 읽습니다:
.auto_create()는 아직 존재하지 않는 계정의 로그인이 계정을 프로비저닝할 수 있는지를 결정하고, .roles_mode()는 그 후에 로그인이 확인한 계정 — 방금 프로비저닝된 계정이든 이미 존재하던 계정이든 — 에 대해 실행되므로, 어느 경우든 동일한 조정이 적용됩니다. VEF_AUTH_ROLES_ACTIVATE 또는 콜백 없음은 활성화 전용 기본 동작을 유지합니다.
VEF_AUTH_ROLES_GRANT는 추가적입니다: 계정에 없는 스테이징된 역할을 부여하고, 취소 단계는 전혀 실행하지 않습니다. VEF_AUTH_ROLES_SYNC는 그 단계를 실행합니다: 토큰이 요구하지 않은 부여된 역할을 모두 취소하므로, 토큰에서 빠진 역할은 다음 로그인 시 계정에서도 빠집니다 — 단, 운영자의 ALTER USER로 계정의 DEFAULT ROLE로 설정된 역할은 예외이며, SYNC는 이를 결코 취소하지 않습니다. 어느 모드에서든, DB 역할로 존재하지 않는 스테이징된 역할은 GRANT에 실패하며 로그인을 실패시키지 않고 로깅된 후 건너뜁니다.
vsql_auth_test는 이를 vsql_auth_test.auto_grant로 노출하며, 이는 OFF/ON/SYNC 열거형(이 또한 OFF로 시작)으로 그 인덱스 순서는 위의 모드 순서와 일치합니다. 그 -token-roles 토큰은 vsql_role_granted와 vsql_role_denied를 스테이징하며, 아래 계정은 둘 다 보유하지 않습니다. 설정이 꺼져 있으면 로그인은 계정의 역할을 그대로 둡니다:
vsql-auth-test-token-roles를 사용해 auth_user로 연결하고, SELECT CURRENT_ROLE()로 무엇이 활성 상태인지 물으세요:
SHOW GRANTS는 서버가 추가한 부여를 보여줍니다: