> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증 방식

> vsql::preview::auth 기능을 사용하면 확장 프로그램이 서버 인증 방식을 제공할 수 있습니다. 기능 선언, 핸들러 구현, 활성 역할 준비, 계정 자동 생성을 다룹니다.

이 페이지의 기능은 미리보기 단계입니다. API는 안정적이지 않으며, 이 기능을 선언하는 확장 프로그램은 설치 시 `vsql_allow_preview_extensions = ON`이 필요합니다. 미리보기 계층을 활성화하고 기능을 등록하는 방법은 [미리보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities)을 참조하세요.

auth 기능(`vsql::preview::auth`)은 확장 프로그램이 서버 인증 방식을 제공할 수 있게 해줍니다. 계정은 `CREATE USER ... IDENTIFIED WITH <method-name>`으로 이를 선택합니다. 연결 시점에 그 이름이 로드된 MySQL 인증 플러그인이 아니면, 서버는 VEF 인증 레지스트리를 조회하고 핸드셰이크 전반에 걸쳐 확장 프로그램의 핸들러를 호출합니다. MySQL 인증 플러그인을 작성하지 않고도 서버가 알지 못하는 자격 증명 소스 — 베어러 토큰, 외부 신원 공급자, 또는 사용자 정의 챌린지 — 를 기준으로 계정을 인증하는 데 사용하세요.

기능 이름 `VEF_PREVIEW_AUTH_NAME`은 `"vsql::preview::auth"`입니다.

핸들러는 `AuthContext`를 받는 타입이 지정된 함수입니다: 서버가 소유한 이 컨텍스트를 통해 핸드셰이크 패킷을 읽고 쓰면서 클라이언트와 통신하며, MySQL의 내부 인증 구조체는 전혀 보지 않습니다.

> [!WARNING]
>
> 인증 결과는 실패 시 차단(fail-closed)됩니다. 서버는 `AuthResult::kOk`이 아닌 모든 것을 거부된 연결로 처리합니다 — "아마도"나 실패 시 허용(fail-open) 결과는 의도적으로 존재하지 않습니다. `AuthResult::kReject`를 반환하거나, `AuthResult::kError`를 반환하거나, 유효 계정을 설정하지 않는 핸들러는 로그인을 거부합니다.

## 기능 선언

헤더를 포함하고, 타입이 지정된 핸들러를 작성하고, 플루언트 `make_auth<>` 빌더로 디스크립터를 구축한 후, 그 디스크립터를 `.with()`에 전달할 `AuthCapability` 토큰에 넘깁니다. 미리보기 기능 헤더는 `<villagesql/vsql.h>` 우산 헤더에 포함되지 않으므로, `<villagesql/preview/auth.h>`를 명시적으로 포함하세요:

```cpp theme={null}
#include <villagesql/preview/auth.h>
#include <villagesql/vsql.h>

using namespace vsql;
using vsql::preview_auth::AuthContext;
using vsql::preview_auth::AuthResult;

AuthResult authenticate(AuthContext &c) {
  // ... validate the client and set the effective account ...
  return AuthResult::kOk;
}

constexpr auto MY_AUTH =
    vsql::preview_auth::make_auth<&authenticate>("my_auth")
        .client_plugin("mysql_clear_password")
        .build();

static vsql::preview_auth::AuthCapability g_auth{MY_AUTH};

VEF_GENERATE_ENTRY_POINTS(
    make_extension()
        .with(g_auth))
```

빌더는 여섯 부분으로 구성됩니다:

| 요소 | 의미 |
| - | - |
| `make_auth<&handler>("name")` | 빌더를 시작합니다. 핸들러는 컴파일 타임 템플릿 인수이므로, null이거나 서명이 잘못된 핸들러는 런타임 실패가 아니라 컴파일 오류가 됩니다. `"name"`은 계정이 바인딩하는 인증 방식 이름(`IDENTIFIED WITH <name>`)이며 최대 `VEF_AUTH_MAX_NAME_LEN`(64)바이트여야 합니다. |
| `.client_plugin(name)` | 선택적. 서버가 핸드셰이크 중에 광고하는 클라이언트 측 인증 플러그인을 오버라이드합니다. |
| `.accepts_client_plugin(callback)` | 선택적. `bool (*)(const char *offered)`을 받습니다. `true`를 반환하면 클라이언트가 제안한 플러그인을 유지하고, `false`를 반환하면 클라이언트를 `.client_plugin()`으로 전환합니다. |
| `.auto_create(callback)` | 선택적. 존재하지 않는 계정의 로그인에 대해 이 방식을 옵트인시킵니다([계정 자동 생성](#auto-creating-accounts) 참조). |
| `.roles_mode(callback)` | 선택적. 핸들러가 스테이징한 역할을 서버가 계정의 부여된 역할과 어떻게 조정할지 선택합니다 — 활성화만, 부여도 함께, 또는 완전 동기화([역할 자동 부여](#auto-granting-roles) 참조). |
| `.build()` | `AuthCapability`에 넘길 디스크립터를 생성합니다. |

`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`를 반환합니다:

```cpp theme={null}
AuthResult authenticate(AuthContext &c);
```

핸들러는 핸드셰이크 중에 연결하는 스레드에서 동기적으로 호출됩니다. `AuthContext`는 서버가 소유한 시도별 컨텍스트를 감쌉니다. 호출 기간 동안만 보유하고 보관하지 마세요. 함수 테이블을 통해 컨텍스트 포인터를 전달하는 대신 그 메서드를 호출하세요. 토큰 기반 핸들러가 사용하는 메서드:

| 메서드 | 용도 |
| - | - |
| `c.read_packet()` | 클라이언트가 보낸 다음 패킷을 읽습니다. 다음 읽기 전까지 유효한 `Span<const unsigned char>`로 바이트를 반환합니다(프로토콜 또는 연결 오류 시 비어 있음). `mysql_clear_password`와 함께 사용하면 한 번의 읽기로 베어러 토큰을 얻습니다. |
| `c.write_packet(data)` | 클라이언트에 패킷을 보냅니다(예: 챌린지). `Span<const unsigned char>`를 받고 실패 시 `true`를 반환합니다. |
| `c.user_name()` | 클라이언트가 연결에 사용한 계정 이름. |
| `c.auth_string()` | `IDENTIFIED WITH <m> AS '...'`의 `AS '...'` 절, 또는 빈 값. |
| `c.host_or_ip()` | 클라이언트 호스트 또는 IP. |
| `c.client_auth_plugin()` | 클라이언트가 핸드셰이크 응답에서 광고한 클라이언트 측 인증 플러그인(예: `"mysql_clear_password"`). 방식이 그 제안을 허용한 경우, 이는 핸들러가 읽는 자격 증명을 프레이밍한 플러그인이기도 하므로, 핸들러는 바이트를 살펴보는 대신 이름으로 해석할 수 있습니다. `.client_plugin()`으로의 강제 전환은 이 값을 갱신하지 않으므로, 그 경로에서는 여전히 클라이언트가 처음 제안한 것을 보고합니다. 알 수 없으면 비어 있습니다. |
| `c.authenticate_as(account)` | 세션이 실행되는 유효 계정을 설정합니다(`CURRENT_USER()`가 표시하는 값). `AuthResult::kOk`을 반환하기 전에 필수입니다. |
| `c.set_external_user(identity)` | 감사 추적을 위한 원래 외부 신원(`@@external_user`)을 설정합니다. |
| `c.set_active_roles(roles, n_roles)` | 세션의 활성 역할을 스테이징합니다([활성 역할 스테이징](#staging-active-roles) 참조). |
| `c.account_unknown()` | 인증 중인 계정이 존재하지 않고 이 로그인이 방식의 `.auto_create()` 옵트인에 의해 이 방식으로 라우팅된 경우 `true`. 기존 계정에 대한 로그인의 경우 `false`. |
| `c.request_provision(account, roles, n_roles)` | 서버에 `account`를 생성하고 `roles`를 부여하도록 요청합니다([계정 자동 생성](#auto-creating-accounts) 참조). |

핸들러는 세 가지 결과 중 하나를 반환합니다:

| 결과 | 의미 |
| - | - |
| `AuthResult::kOk` | 인증에 성공했습니다. 핸들러는 반드시 `authenticate_as()`를 호출했어야 하며, 세션은 그 계정으로 실행됩니다. |
| `AuthResult::kReject` | 인증에 실패했습니다 — 잘못된 자격 증명 또는 정책에 의한 거부. |
| `AuthResult::kError` | 내부 오류로 인해 결정을 내릴 수 없었습니다(예: 키 소스를 사용할 수 없음). 서버는 이를 거부와 동일하게 처리합니다. |

`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()` 콜백, 그리고 아래에 설명된 두 옵트인을 모두 추가합니다.)

```cpp theme={null}
#include <cstring>

#include <villagesql/preview/auth.h>
#include <villagesql/vsql.h>

using namespace vsql;
using vsql::preview_auth::AuthContext;
using vsql::preview_auth::AuthResult;

namespace {

constexpr char kToken[] = "vsql-auth-test-token";
constexpr char kMappedAccount[] = "vsql_auth_test_user";

AuthResult authenticate(AuthContext &c) {
  auto pkt = c.read_packet();
  if (pkt.empty()) return AuthResult::kError;

  // mysql_clear_password sends a NUL-terminated string; drop the trailing NUL.
  size_t len = pkt.size();
  if (len && pkt[len - 1] == '\0') --len;

  if (len != std::strlen(kToken) ||
      std::memcmp(pkt.data(), kToken, len) != 0) {
    return AuthResult::kReject;
  }

  c.authenticate_as(kMappedAccount);
  // @@external_user records the connecting identity, not the mapped account.
  c.set_external_user(c.user_name());
  return AuthResult::kOk;
}

constexpr auto AUTH_METHOD =
    vsql::preview_auth::make_auth<&authenticate>("vsql_auth_test")
        .client_plugin("mysql_clear_password")
        .build();
vsql::preview_auth::AuthCapability g_auth{AUTH_METHOD};

}  // namespace

VEF_GENERATE_ENTRY_POINTS(make_extension().with(g_auth))
```

## 계정 바인딩 및 연결

미리보기 계층이 활성화된 상태에서(참조: [미리보기 계층 활성화](https://villagesql.com/docs/ko/extensions/build/preview-capabilities#enabling-the-preview-tier)), 확장 프로그램을 빌드하고, 그 `.veb` 파일을 `veb_dir`에 복사하고, 설치한 다음, 계정을 방식에 바인딩합니다. 핸들러가 두 번째 계정으로 매핑하므로, 그 계정도 생성하고 연결하는 계정이 그 신원을 취할 수 있도록 `PROXY` 권한을 부여합니다:

```sql theme={null}
INSTALL EXTENSION vsql_auth_test;
CREATE USER auth_user IDENTIFIED WITH vsql_auth_test;
CREATE USER vsql_auth_test_user;
GRANT SELECT ON *.* TO vsql_auth_test_user;
GRANT PROXY ON vsql_auth_test_user TO auth_user;
```

`vsql_auth_test`가 등록된 VEF 인증 방식이기 때문에 `CREATE USER ... IDENTIFIED WITH vsql_auth_test`가 허용됩니다 — 설치된 플러그인 이름이 허용되는 것과 동일한 방식입니다.

`IDENTIFIED WITH <method>` 형식만 허용되며, 선택적으로 `AS '...'`를 붙일 수 있습니다. `BY '...'`를 추가하는 것은 방식에게 비밀번호를 저장된 자격 증명으로 변환하라고 요청하는 것인데 — MySQL 플러그인이 `generate_authentication_string()`을 통해 수행하는 작업입니다 — 오늘날 어떤 VEF 인증 방식도 그 훅을 선언하지 않으므로 서버가 이를 거부합니다:

```sql theme={null}
CREATE USER auth_user IDENTIFIED WITH vsql_auth_test BY 'secret';
```

```text theme={null}
ERROR 1827 (HY000): The password hash doesn't have the expected format.
```

바인딩된 방식 이름은 테이블 기본값이 아니라 계정의 `plugin` 컬럼에 기록되며, 이것이 그 계정의 다음 로그인이 읽는 값입니다:

```sql theme={null}
SELECT plugin FROM mysql.user WHERE user = 'auth_user';
```

```text theme={null}
+----------------+
| plugin         |
+----------------+
| vsql_auth_test |
+----------------+
```

방식이 `mysql_clear_password`를 요청하므로, 클라이언트는 토큰을 평문으로 보내기 위해 `--enable-cleartext-plugin`을 전달해야 합니다. 올바른 토큰이면 세션은 매핑된 계정으로 실행되고 `@@external_user`를 통해 연결하는 계정을 노출합니다:

```bash theme={null}
mysql --enable-cleartext-plugin --user=auth_user \
      --password=vsql-auth-test-token \
      -e "SELECT CURRENT_USER(), @@external_user"
```

```text theme={null}
+-----------------------+-----------------+
| CURRENT_USER()        | @@external_user |
+-----------------------+-----------------+
| vsql_auth_test_user@% | auth_user       |
+-----------------------+-----------------+
```

확장 프로그램을 제거하면 방식이 사라지며, 여기에 바인딩된 계정은 더 이상 인증할 수 없습니다:

```sql theme={null}
UNINSTALL EXTENSION vsql_auth_test;
```

## 계정 자동 생성

방식은 아직 존재하지 않는 계정의 로그인도 처리하고, 로그인이 성공하는 과정의 일부로 서버가 계정을 생성하도록 할 수 있습니다. 이것이 없으면 알 수 없는 계정은 어떤 방식이 실행되기도 전에 거부됩니다.

`.auto_create(&callback)`으로 옵트인합니다. 콜백은 인수를 받지 않고 `bool`을 반환합니다. 서버는 등록 시점에 한 번 읽는 것이 아니라 알 수 없는 계정의 로그인마다 이를 호출하므로, 방식은 확장 프로그램이 로드될 때 선택을 고정하는 대신 자체 런타임 설정을 따를 수 있습니다:

```cpp theme={null}
bool auto_create_enabled() { return true; }

constexpr auto AUTH_METHOD =
    vsql::preview_auth::make_auth<&authenticate>("vsql_auth_test")
        .client_plugin("mysql_clear_password")
        .auto_create(&auto_create_enabled)
        .build();
```

`.auto_create()`를 생략하거나 콜백에서 `false`를 반환하면 표준 동작이 유지됩니다: 알 수 없는 계정은 거부됩니다. 한 번에 설치된 방식 중 하나만 옵트인할 수 있습니다 — 둘이 `true`를 반환하면 서버는 추측하기를 거부하고, 오류 로그에 경고를 기록하며, 아무도 옵트인하지 않은 것처럼 알 수 없는 계정을 거부합니다.

핸들러에서는 `c.account_unknown()`이 두 경우를 구분합니다. 먼저 자격 증명을 검증한 다음, 무엇을 생성할지 기술하고 그 계정으로 인증합니다:

```cpp theme={null}
if (c.account_unknown()) {
  const char *roles[] = {"vsql_role_granted"};
  c.request_provision(c.user_name(), roles, 1);
  c.authenticate_as(c.user_name());
  c.set_external_user(c.user_name());
  return AuthResult::kOk;
}
```

`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`를 바이너리 로그에 기록하지 않습니다. 복제 토폴로지의 각 서버는 계정을 스스로 생성하고 조정합니다.

역할은 [활성 역할 스테이징](#staging-active-roles)에서와 동일하게 동작합니다: DBA가 이를 소유합니다. 각 이름은 부여 가능한 역할로 이미 존재해야 하며, 부여할 수 없는 이름은 로그인을 실패시키지 않고 로깅된 후 건너뜁니다. 따라서 토큰은 역할을 지정할 수는 있어도 결코 생성하거나 상승시킬 수 없습니다. 계정 이름은 클라이언트에서 오므로 서버는 이를 식별자로 인용합니다 — 조작된 이름은 이상한 이름의 계정 하나가 될 뿐, 결코 두 번째 문이 되지 않습니다.

`vsql_auth_test` 확장 프로그램은 연결하는 사용자에게 `vsql_role_granted` 역할을 프로비저닝하며, 옵트인을 `OFF`로 시작하는 `vsql_auth_test.auto_create` 뒤에 둡니다. 이를 켜고 역할을 먼저 생성한 다음, 존재하지 않는 계정으로 연결하세요:

```sql theme={null}
INSTALL EXTENSION vsql_auth_test;
SET GLOBAL vsql_auth_test.auto_create = ON;
CREATE ROLE vsql_role_granted;
GRANT SELECT ON *.* TO vsql_role_granted;
```

```bash theme={null}
mysql --enable-cleartext-plugin --user=auto_created_user \
      --password=vsql-auth-test-token \
      -e "SELECT CURRENT_USER() AS who, @@external_user AS ext"
```

```text theme={null}
+---------------------+-------------------+
| who                 | ext               |
+---------------------+-------------------+
| auto_created_user@% | auto_created_user |
+---------------------+-------------------+
```

이제 계정이 존재하며, 방식에 바인딩되어 있고, 부여된 역할을 보유합니다:

```sql theme={null}
SELECT user, host, plugin FROM mysql.user WHERE user = 'auto_created_user';
```

```text theme={null}
+-------------------+------+----------------+
| user              | host | plugin         |
+-------------------+------+----------------+
| auto_created_user | %    | vsql_auth_test |
+-------------------+------+----------------+
```

```sql theme={null}
SHOW GRANTS FOR 'auto_created_user'@'%';
```

```text theme={null}
+----------------------------------------------------------+
| Grants for auto_created_user@%                           |
+----------------------------------------------------------+
| GRANT USAGE ON *.* TO `auto_created_user`@`%`            |
| GRANT `vsql_role_granted`@`%` TO `auto_created_user`@`%` |
+----------------------------------------------------------+
```

잘못된 토큰은 여전히 실패 시 차단되며, 아무것도 프로비저닝하지 않습니다:

```bash theme={null}
mysql --enable-cleartext-plugin --user=never_created --password=wrong-token \
      -e "SELECT 1"
```

```text theme={null}
ERROR 1045 (28000): Access denied for user 'never_created'@'localhost' (using password: NO)
```

> [!WARNING]
>
> 옵트인하면 알 수 없는 계정과 기존 계정의 차이가 관찰 가능해지는데, 이는 표준 알 수 없는 계정 거부가 의도적으로 숨기는 것입니다: 알 수 없는 계정에 대한 거부된 로그인은 `(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` 대신 모드 열거형을 반환하며, 서버가 로그인마다 호출하여 그 뒤에 있는 값을 실시간으로 읽습니다:

```cpp theme={null}
unsigned long g_auto_grant = 0;  // 0=ACTIVATE, 1=GRANT, 2=SYNC
vef_auth_roles_mode_t roles_mode_cb() {
  return static_cast<vef_auth_roles_mode_t>(g_auto_grant);
}

constexpr auto AUTH_METHOD =
    vsql::preview_auth::make_auth<&authenticate>("vsql_auth_test")
        .client_plugin("mysql_clear_password")
        .roles_mode(&roles_mode_cb)
        .build();
```

두 옵트인은 로그인의 서로 다른 시점에 실행됩니다. `.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`를 스테이징하며, 아래 계정은 둘 다 보유하지 않습니다. 설정이 꺼져 있으면 로그인은 계정의 역할을 그대로 둡니다:

```sql theme={null}
CREATE USER IF NOT EXISTS auth_user IDENTIFIED WITH vsql_auth_test;
CREATE USER IF NOT EXISTS vsql_auth_test_user;
GRANT SELECT ON *.* TO vsql_auth_test_user;
GRANT PROXY ON vsql_auth_test_user TO auth_user;
CREATE ROLE IF NOT EXISTS vsql_role_granted, vsql_role_denied;
```

위와 동일한 방식으로 비밀번호 `vsql-auth-test-token-roles`를 사용해 `auth_user`로 연결하고, `SELECT CURRENT_ROLE()`로 무엇이 활성 상태인지 물으세요:

```text theme={null}
+----------------+
| CURRENT_ROLE() |
+----------------+
| NONE           |
+----------------+
```

설정을 켜고 동일한 로그인을 반복합니다:

```sql theme={null}
SET GLOBAL vsql_auth_test.auto_grant = ON;
```

```text theme={null}
+------------------------------------------------+
| CURRENT_ROLE()                                 |
+------------------------------------------------+
| `vsql_role_denied`@`%`,`vsql_role_granted`@`%` |
+------------------------------------------------+
```

이제 두 역할이 모두 활성 상태이며, `SHOW GRANTS`는 서버가 추가한 부여를 보여줍니다:

```sql theme={null}
SHOW GRANTS FOR vsql_auth_test_user;
```

```text theme={null}
+-----------------------------------------------------------------------------------+
| Grants for vsql_auth_test_user@%                                                  |
+-----------------------------------------------------------------------------------+
| GRANT SELECT ON *.* TO `vsql_auth_test_user`@`%`                                  |
| GRANT `vsql_role_denied`@`%`,`vsql_role_granted`@`%` TO `vsql_auth_test_user`@`%` |
+-----------------------------------------------------------------------------------+
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.