> ## 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.

# MySQL용 vsql_oauth2 확장 기능

> vsql_oauth2 확장 기능은 MySQL 계정이 JWT로 로그인하게 하며, JWKS 엔드포인트로 서명을 검증하고 클레임을 계정에 매핑합니다.

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

| | |
| - | - |
| **관리자** | VillageSQL |
| **소스 및 전체 문서** | [villagesql/vsql-oauth2](https://github.com/villagesql/vsql-oauth2) |
| **라이선스** | GPL-2.0 |
| **기능 단계** | 미리 보기 |

> [!WARNING]
>
> 이 확장 기능은 미리 보기 기능을 사용하므로 `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/` 디렉터리에 있습니다. 문 하나로
서버에 설치하세요:

```sql theme={null}
INSTALL EXTENSION vsql_oauth2;
```

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

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_oauth2';
```

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

직접 빌드하려면 [저장소](https://github.com/villagesql/vsql-oauth2)의 빌드
지침을 따르세요.

## 추가되는 기능

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

```sql theme={null}
CREATE USER 'analyst'@'%' IDENTIFIED WITH vsql_oauth2;
```

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

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

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

```sql theme={null}
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로
허용됩니다.

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

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

## 상태 변수

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

## 참고 항목

* [MySQL에서의 JWT 인증](https://villagesql.com/docs/en/guides/jwt-authentication.md) — 실제 로그인 예제, 클레임 매핑, 거부된 토큰이 잘못된 비밀번호처럼 보이는 이유
* [확장 기능 관리](https://villagesql.com/docs/ko/extensions/managing.md) — 확장 기능 설정을 읽고 쓰는 방법
* [미리 보기 기능](https://villagesql.com/docs/ko/extensions/build/preview-capabilities.md) — 미리 보기 플래그가 켜는 것과 보장하는 것
* [사용 가능한 확장 기능](https://villagesql.com/docs/ko/extensions/catalog) — 전체 카탈로그
* [villagesql/vsql-oauth2](https://github.com/villagesql/vsql-oauth2) — 소스, 실제 공급자 설정 예제, 알려진 제한 사항


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