메인 콘텐츠로 건너뛰기
이 페이지의 기능은 미리보기 단계입니다. API는 안정적이지 않으며, 이 기능을 선언하는 확장 프로그램은 설치 시 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의 내부 인증 구조체는 전혀 보지 않습니다.
인증 결과는 실패 시 차단(fail-closed)됩니다. 서버는 AuthResult::kOk이 아닌 모든 것을 거부된 연결로 처리합니다 — “아마도”나 실패 시 허용(fail-open) 결과는 의도적으로 존재하지 않습니다. AuthResult::kReject를 반환하거나, AuthResult::kError를 반환하거나, 유효 계정을 설정하지 않는 핸들러는 로그인을 거부합니다.

기능 선언

헤더를 포함하고, 타입이 지정된 핸들러를 작성하고, 플루언트 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 뒤에 둡니다. 이를 켜고 역할을 먼저 생성한 다음, 존재하지 않는 계정으로 연결하세요:
이제 계정이 존재하며, 방식에 바인딩되어 있고, 부여된 역할을 보유합니다:
잘못된 토큰은 여전히 실패 시 차단되며, 아무것도 프로비저닝하지 않습니다:
옵트인하면 알 수 없는 계정과 기존 계정의 차이가 관찰 가능해지는데, 이는 표준 알 수 없는 계정 거부가 의도적으로 숨기는 것입니다: 알 수 없는 계정에 대한 거부된 로그인은 (using password: NO)를 보고하는 반면, 일반 비밀번호를 가진 계정에 대한 거부된 로그인은 (using password: YES)를 보고하며, 유효한 자격 증명은 계정을 생성합니다. 이것이 이 기능이 감수하는 대가입니다. 자격 증명이 널리 보유된 방식에서 옵트인을 활성화하기 전에 이를 저울질하세요.

역할 자동 부여

기본적으로 토큰이 지정한 역할은 계정이 이미 그것을 보유한 경우에만 적용됩니다. 보유하지 않은 역할은 건너뛰며, 서버는 그 이유를 로깅합니다(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는 서버가 추가한 부여를 보여줍니다:
vsql_auth_test.auto_grant가 ON 또는 SYNC로 설정되어 있으면 유효한 토큰만으로 그것이 지정하는 어떤 역할이든 얻을 수 있습니다. DB 역할로 아직 존재하지 않는 역할은 GRANT에 실패하고 건너뛰므로 토큰이 생성된 적 없는 역할을 만들어낼 수는 여전히 없지만, 존재하는 역할 중 어느 것에 계정이 도달할 수 있는지를 더 이상 DBA가 결정하지 않고 인증 방식이 결정합니다. SYNC는 더 나아갑니다: DBA가 별도로 부여했지만 토큰이 요구하지 않는 역할도 계정이 다음에 로그인할 때 취소합니다 — 운영자는 역할을 계정의 DEFAULT ROLE로 설정하여 여전히 하나의 역할을 고정할 수 있으며, SYNC는 이를 그대로 둡니다. vsql_auth_test_user에서 취소된 역할은 이미 그것을 활성화한 세션에서 사라지지 않습니다: 취소 후 동일한 세션에서 CURRENT_ROLE()을 다시 조회하면 여전히 그 역할이 나열됩니다.