0
# Google Auth OAuthlib
1

2
Google Authentication Library - oauthlib integration provides seamless OAuth 2.0 flows for Google services authentication. It offers high-level abstractions for common authentication patterns including web application flows, installed application flows, and interactive credential acquisition, with built-in support for token refresh, credential storage, and various Google OAuth 2.0 endpoints.
3

4
## Package Information
5

6
- **Package Name**: google-auth-oauthlib
7
- **Language**: Python
8
- **Installation**: `pip install google-auth-oauthlib`
9
- **CLI Tool**: `pip install google-auth-oauthlib[tool]` (includes CLI functionality)
10

11
## Core Imports
12

13
```python
14
import google_auth_oauthlib
15
from google_auth_oauthlib import get_user_credentials
16
```
17

18
For OAuth flows:
19

20
```python
21
from google_auth_oauthlib.flow import Flow, InstalledAppFlow
22
```
23

24
For session and credential helpers:
25

26
```python
27
from google_auth_oauthlib.helpers import (
28
    session_from_client_config,
29
    credentials_from_session
30
)
31
```
32

33
## Basic Usage
34

35
```python
36
import google_auth_oauthlib
37

38
# Simple interactive credential acquisition
39
scopes = ['https://www.googleapis.com/auth/cloud-platform']
40
client_id = 'your-client-id.apps.googleusercontent.com'
41
client_secret = 'your-client-secret'
42

43
credentials = google_auth_oauthlib.get_user_credentials(
44
    scopes, client_id, client_secret
45
)
46

47
# Use credentials with Google API clients
48
from google.cloud import bigquery
49
bigquery_client = bigquery.Client(credentials=credentials)
50
```
51

52
For installed applications:
53

54
```python
55
from google_auth_oauthlib.flow import InstalledAppFlow
56

57
flow = InstalledAppFlow.from_client_secrets_file(
58
    'client_secrets.json',
59
    scopes=['https://www.googleapis.com/auth/cloud-platform']
60
)
61

62
credentials = flow.run_local_server()
63
```
64

65
## Architecture
66

67
The library provides multiple abstraction levels for OAuth 2.0 flows:
68

69
- **High-level functions**: Simple credential acquisition (`get_user_credentials`)
70
- **Flow classes**: Complete OAuth 2.0 flow management (`Flow`, `InstalledAppFlow`)
71
- **Helper utilities**: Low-level session and credential conversion
72
- **CLI tool**: Command-line interface for development and testing
73

74
This design enables both quick integration for simple use cases and fine-grained control for complex authentication scenarios across web applications, desktop applications, CLI tools, and interactive environments.
75

76
## Capabilities
77

78
### Interactive Credential Acquisition
79

80
High-level functions for obtaining user credentials in interactive development environments like Jupyter notebooks. Provides automatic port detection and simplified OAuth flow management.
81

82
```python { .api }
83
def get_user_credentials(
84
    scopes, client_id, client_secret, 
85
    minimum_port=8080, maximum_port=None
86
): ...
87
```
88

89
[Interactive Authentication](./interactive.md)
90

91
### OAuth Flow Management
92

93
Complete OAuth 2.0 authorization flow implementation with support for both web and installed application patterns. Handles authorization URL generation, token exchange, and credential management.
94

95
```python { .api }
96
class Flow:
97
    def __init__(self, oauth2session, client_type, client_config, ...): ...
98
    @classmethod
99
    def from_client_config(cls, client_config, scopes, **kwargs): ...
100
    def authorization_url(self, **kwargs): ...
101
    def fetch_token(self, **kwargs): ...
102

103
class InstalledAppFlow(Flow):
104
    def run_local_server(self, host="localhost", port=8080, ...): ...
105
```
106

107
[OAuth Flows](./oauth-flows.md)
108

109
### Helper Utilities
110

111
Low-level utilities for session management and credential conversion between requests-oauthlib sessions and google-auth credentials objects.
112

113
```python { .api }
114
def session_from_client_config(client_config, scopes, **kwargs): ...
115
def credentials_from_session(session, client_config=None): ...
116
```
117

118
[Helper Utilities](./helpers.md)
119

120
### Command Line Tool
121

122
CLI tool for obtaining OAuth credentials during development and testing. Provides interactive authentication flow with credential storage options.
123

124
```bash
125
google-oauthlib-tool --client-secrets client.json --scope https://www.googleapis.com/auth/cloud-platform
126
```
127

128
[CLI Tool](./cli-tool.md)
129

130
## Error Handling
131

132
The library raises standard Python exceptions for common error conditions:
133

134
- **ValueError**: Invalid client configuration, missing tokens, or malformed parameters
135
- **ConnectionError**: Network connectivity issues or inability to bind to local ports
136
- **requests_oauthlib exceptions**: OAuth-specific errors from underlying library
137

138
## Types
139

140
```python { .api }
141
# Common type hints used throughout the API
142
from typing import Sequence, Mapping, Any, Optional, Tuple
143
from google.oauth2.credentials import Credentials
144
from google.auth.transport.requests import AuthorizedSession
145
import requests_oauthlib
146
```