Skip to content

Commit 779b49b

Browse files
sungwysungwy
committed
combine auth docs
1 parent c951f83 commit 779b49b

1 file changed

Lines changed: 74 additions & 73 deletions

File tree

‎mkdocs/docs/configuration.md‎

Lines changed: 74 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -359,7 +359,9 @@ catalog:
359359

360360
#### Authentication Options
361361

362-
##### OAuth2
362+
##### Legacy OAuth2
363+
364+
Legacy OAuth2 Properties will be removed in PyIceberg 1.0 in place of pluggable AuthManager properties below
363365

364366
| Key | Example | Description |
365367
| ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
@@ -378,6 +380,77 @@ catalog:
378380
| rest.signing-region | us-east-1 | The region to use when SigV4 signing a request |
379381
| rest.signing-name | execute-api | The service signing name to use when SigV4 signing a request |
380382

383+
##### Pluggable Authentication via AuthManager
384+
385+
The RESTCatalog supports pluggable authentication via the `auth` configuration block. This allows you to specify which how the access token will be fetched and managed for use with the HTTP requests to the RESTCatalog server. The authentication method is selected by setting the `auth.type` property, and additional configuration can be provided as needed for each method.
386+
387+
###### Supported Authentication Types
388+
389+
- `noop`: No authentication (no Authorization header sent).
390+
- `basic`: HTTP Basic authentication.
391+
- `custom`: Custom authentication manager (requires `auth.impl`).
392+
393+
###### Configuration Properties
394+
395+
The `auth` block is structured as follows:
396+
397+
```yaml
398+
catalog:
399+
default:
400+
type: rest
401+
uri: http://rest-catalog/ws/
402+
auth:
403+
type: <auth_type>
404+
<auth_type>:
405+
# Type-specific configuration
406+
impl: <custom_class_path> # Only for custom auth
407+
```
408+
409+
###### Property Reference
410+
411+
| Property | Required | Description |
412+
|------------------|----------|-------------------------------------------------------------------------------------------------|
413+
| `auth.type` | Yes | The authentication type to use (`noop`, `basic`, or `custom`). |
414+
| `auth.impl` | Conditionally | The fully qualified class path for a custom AuthManager. Required if `auth.type` is `custom`. |
415+
| `auth.basic` | If type is `basic` | Block containing `username` and `password` for HTTP Basic authentication. |
416+
| `auth.custom` | If type is `custom` | Block containing configuration for the custom AuthManager. |
417+
418+
###### Examples
419+
420+
No Authentication:
421+
422+
```yaml
423+
auth:
424+
type: noop
425+
```
426+
427+
Basic Authentication:
428+
429+
```yaml
430+
auth:
431+
type: basic
432+
basic:
433+
username: myuser
434+
password: mypass
435+
```
436+
437+
Custom Authentication:
438+
439+
```yaml
440+
auth:
441+
type: custom
442+
impl: mypackage.module.MyAuthManager
443+
custom:
444+
property1: value1
445+
property2: value2
446+
```
447+
448+
###### Notes
449+
450+
- If `auth.type` is `custom`, you **must** specify `auth.impl` with the full class path to your custom AuthManager.
451+
- If `auth.type` is not `custom`, specifying `auth.impl` is not allowed.
452+
- The configuration block under each type (e.g., `basic`, `custom`) is passed as keyword arguments to the corresponding AuthManager.
453+
381454
<!-- markdown-link-check-enable-->
382455

383456
#### Common Integrations & Examples
@@ -445,78 +518,6 @@ catalog:
445518
py-io-impl: pyiceberg.io.fsspec.FsspecFileIO
446519
```
447520

448-
#### Authentication in RESTCatalog
449-
450-
The RESTCatalog supports pluggable authentication via the `auth` configuration block. This allows you to specify which how the access token will be fetched and managed for use with the HTTP requests to the RESTCatalog server. The authentication method is selected by setting the `auth.type` property, and additional configuration can be provided as needed for each method.
451-
452-
##### Supported Authentication Types
453-
454-
- `noop`: No authentication (no Authorization header sent).
455-
- `basic`: HTTP Basic authentication.
456-
- `legacyoauth2`: Legacy OAuth2 client credentials flow (Deprecated and will be removed in PyIceberg 1.0.0)
457-
- `custom`: Custom authentication manager (requires `auth.impl`).
458-
459-
##### Configuration Properties
460-
461-
The `auth` block is structured as follows:
462-
463-
```yaml
464-
catalog:
465-
default:
466-
type: rest
467-
uri: http://rest-catalog/ws/
468-
auth:
469-
type: <auth_type>
470-
<auth_type>:
471-
# Type-specific configuration
472-
impl: <custom_class_path> # Only for custom auth
473-
```
474-
475-
**Property Reference:**
476-
477-
| Property | Required | Description |
478-
|------------------|----------|-------------------------------------------------------------------------------------------------|
479-
| `auth.type` | Yes | The authentication type to use (`noop`, `basic`, or `custom`). |
480-
| `auth.impl` | Conditionally | The fully qualified class path for a custom AuthManager. Required if `auth.type` is `custom`. |
481-
| `auth.basic` | If type is `basic` | Block containing `username` and `password` for HTTP Basic authentication. |
482-
| `auth.custom` | If type is `custom` | Block containing configuration for the custom AuthManager. |
483-
484-
##### Examples
485-
486-
**No Authentication:**
487-
488-
```yaml
489-
auth:
490-
type: noop
491-
```
492-
493-
**Basic Authentication:**
494-
495-
```yaml
496-
auth:
497-
type: basic
498-
basic:
499-
username: myuser
500-
password: mypass
501-
```
502-
503-
**Custom Authentication:**
504-
505-
```yaml
506-
auth:
507-
type: custom
508-
impl: mypackage.module.MyAuthManager
509-
custom:
510-
property1: value1
511-
property2: value2
512-
```
513-
514-
##### Notes
515-
516-
- If `auth.type` is `custom`, you **must** specify `auth.impl` with the full class path to your custom AuthManager.
517-
- If `auth.type` is not `custom`, specifying `auth.impl` is not allowed.
518-
- The configuration block under each type (e.g., `basic`, `custom`) is passed as keyword arguments to the corresponding AuthManager.
519-
520521
### SQL Catalog
521522

522523
The SQL catalog requires a database for its backend. PyIceberg supports PostgreSQL and SQLite through psycopg2. The database connection has to be configured using the `uri` property. The init_catalog_tables is optional and defaults to True. If it is set to False, the catalog tables will not be created when the SQLCatalog is initialized. See SQLAlchemy's [documentation for URL format](https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls):

0 commit comments

Comments
 (0)