0
# Airbyte Source Google Directory
1

2
An Airbyte source connector that extracts data from Google Directory (Google Workspace Admin Directory API). This connector provides access to users, groups, and group memberships within a Google Workspace organization through structured data extraction with OAuth 2.0 and Service Account authentication support.
3

4
## Package Information
5

6
- **Package Name**: source-google-directory
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: This package is part of the Airbyte ecosystem and is typically used within Airbyte platform. For development: `poetry install --with dev`
10
- **Dependencies**: Requires `airbyte-cdk`, `google-auth-oauthlib`, `google-auth-httplib2`, `google-api-python-client`, `backoff`
11

12
## Core Imports
13

14
```python
15
from source_google_directory import SourceGoogleDirectory
16
```
17

18
For running the connector:
19

20
```python
21
from source_google_directory.run import run
22
```
23

24
For accessing individual components:
25

26
```python
27
from source_google_directory.client import Client
28
from source_google_directory.api import API, UsersAPI, GroupsAPI, GroupMembersAPI
29
from source_google_directory.utils import rate_limit_handling
30
```
31

32
## Basic Usage
33

34
```python
35
from source_google_directory import SourceGoogleDirectory
36

37
# Initialize the source connector
38
source = SourceGoogleDirectory()
39

40
# For command-line usage
41
from source_google_directory.run import run
42
run()  # Uses sys.argv for command-line arguments
43

44
# For programmatic access to individual components
45
from source_google_directory.client import Client
46

47
# OAuth credentials configuration
48
oauth_credentials = {
49
    "client_id": "your-client-id",
50
    "client_secret": "your-client-secret", 
51
    "refresh_token": "your-refresh-token"
52
}
53

54
# Service account credentials configuration  
55
service_credentials = {
56
    "credentials_json": '{"type": "service_account", ...}',
57
    "email": "admin@yourdomain.com"
58
}
59

60
# Create client with credentials
61
client = Client(credentials=oauth_credentials)
62

63
# Perform health check
64
is_healthy, error_msg = client.health_check()
65
```
66

67
## Architecture
68

69
The connector follows Airbyte's CDK architecture with these key components:
70

71
- **SourceGoogleDirectory**: Main connector class extending BaseSource from Airbyte CDK
72
- **Client**: Primary client interface extending BaseClient, orchestrates API interactions
73
- **API**: Core Google Directory API wrapper handling authentication and requests
74
- **StreamAPI**: Abstract base class for specific data stream implementations (UsersAPI, GroupsAPI, GroupMembersAPI)
75
- **Utilities**: Helper functions for rate limiting and error handling
76

77
The authentication system supports both OAuth 2.0 (web application flow) and Service Account scenarios, automatically detecting the credential type and establishing appropriate authentication flows.
78

79
## Configuration
80

81
The connector accepts configuration following this schema:
82

83
```python { .api }
84
# OAuth 2.0 Web Server Application Configuration
85
OAuthConfig = {
86
    "credentials": {
87
        "credentials_title": "Web server app",  # Authentication scenario identifier
88
        "client_id": str,                       # OAuth client ID (secret)
89
        "client_secret": str,                   # OAuth client secret (secret)
90
        "refresh_token": str                    # OAuth refresh token (secret)
91
    }
92
}
93

94
# Service Account Configuration  
95
ServiceAccountConfig = {
96
    "credentials": {
97
        "credentials_title": "Service accounts",  # Authentication scenario identifier
98
        "credentials_json": str,                  # JSON service account key (secret)
99
        "email": str                             # Admin email for delegation
100
    }
101
}
102

103
# The connector configuration uses oneOf schema validation
104
CredentialsConfig = Union[OAuthConfig, ServiceAccountConfig]
105
```
106

107
### Configuration Fields
108

109
**OAuth 2.0 Web Server Application:**
110
- `client_id`: The Client ID of the developer application (required, secret)
111
- `client_secret`: The Client Secret of the developer application (required, secret)
112
- `refresh_token`: The Token for obtaining a new access token (required, secret)
113

114
**Service Account:**
115
- `credentials_json`: Contents of the JSON service account key file (required, secret)
116
- `email`: Email of the user with Google Workspace Admin API permissions (required)
117

118
Both authentication methods require appropriate Google Cloud Console setup and Directory API scopes.
119

120
## Capabilities
121

122
### Main Connector Interface
123

124
The primary interface for the Airbyte source connector, providing the main entry point and connector lifecycle management.
125

126
```python { .api }
127
class SourceGoogleDirectory(BaseSource):
128
    client_class = Client
129
```
130

131
```python { .api }
132
def run():
133
    """Main entry point function that launches the connector."""
134
```
135

136
[Main Connector](./main-connector.md)
137

138
### Client Operations
139

140
High-level client interface for managing Google Directory API interactions, including authentication, health checks, and stream enumeration.
141

142
```python { .api }
143
class Client(BaseClient):
144
    def __init__(self, credentials: Mapping[str, Any] = None, credentials_json: str = None, email: str = None): ...
145
    def health_check(self) -> Tuple[bool, str]: ...
146
    def streams(self) -> Generator[AirbyteStream, None, None]: ...
147
```
148

149
[Client Operations](./client-operations.md)
150

151
### Google Directory APIs
152

153
Direct access to Google Directory API resources including users, groups, and group membership data with pagination and error handling.
154

155
```python { .api }
156
class API:
157
    def __init__(self, credentials: Mapping[str, Any]): ...
158
    def get(self, name: str, params: Dict = None) -> Dict: ...
159

160
class UsersAPI(StreamAPI):
161
    def list(self, fields: Sequence[str] = None) -> Iterator[dict]: ...
162

163
class GroupsAPI(StreamAPI):
164
    def list(self, fields: Sequence[str] = None) -> Iterator[dict]: ...
165

166
class GroupMembersAPI(StreamAPI):
167
    def list(self, fields: Sequence[str] = None) -> Iterator[dict]: ...
168
```
169

170
[Google Directory APIs](./google-directory-apis.md)
171

172
## Types
173

174
```python { .api }
175
# Core Python types used in API signatures
176
from typing import Any, Callable, Dict, Generator, Iterator, Mapping, Sequence, Tuple, Union
177
from abc import ABC, abstractmethod
178
from functools import partial
179
import json
180
import sys
181

182
# Google OAuth2 and API types
183
from google.oauth2.credentials import Credentials
184
from google.oauth2 import service_account
185
from google.auth.transport.requests import Request
186
from googleapiclient.discovery import build
187
from googleapiclient.errors import HttpError as GoogleApiHttpError
188

189
# Airbyte CDK types
190
from airbyte_cdk.models import AirbyteStream
191
from airbyte_cdk.sources.deprecated.base_source import BaseSource
192
from airbyte_cdk.sources.deprecated.client import BaseClient
193
from airbyte_cdk.entrypoint import launch
194

195
# Backoff library for retry logic
196
import backoff
197

198
# Configuration types for credentials
199
OAuthCredentials = Dict[str, str]  # Contains client_id, client_secret, refresh_token
200
ServiceAccountCredentials = Dict[str, str]  # Contains credentials_json, email
201
CredentialsConfig = Dict[str, Any]  # Union of above credential types
202
```
203

204
## Constants
205

206
```python { .api }
207
# OAuth scopes required for Google Directory API access
208
SCOPES = [
209
    "https://www.googleapis.com/auth/admin.directory.user.readonly",
210
    "https://www.googleapis.com/auth/admin.directory.group.readonly"
211
]
212
```