0
# Interactive Authentication
1

2
Interactive credential acquisition functions designed for development environments like Jupyter notebooks, providing simplified OAuth 2.0 flows with automatic port management and local server handling.
3

4
## Capabilities
5

6
### User Credential Acquisition
7

8
Main function for obtaining Google OAuth 2.0 credentials through an interactive browser-based flow. Automatically handles local server setup, browser launching, and credential retrieval.
9

10
```python { .api }
11
def get_user_credentials(
12
    scopes: Sequence[str],
13
    client_id: str,
14
    client_secret: str,
15
    minimum_port: int = 8080,
16
    maximum_port: Optional[int] = None
17
) -> google.oauth2.credentials.Credentials:
18
    """
19
    Gets credentials associated with your Google user account.
20

21
    This function authenticates using your user credentials by going through
22
    the OAuth 2.0 flow. Opens a browser window to authenticate to your
23
    Google account with permissions corresponding to the provided scopes.
24

25
    Args:
26
        scopes: List of OAuth 2.0 scopes to request during authentication
27
        client_id: OAuth client ID from Google Developer Console
28
        client_secret: OAuth client secret from Google Developer Console  
29
        minimum_port: Beginning of port range for redirect URI HTTP server
30
        maximum_port: End of port range (exclusive). Tries 100 ports if None
31

32
    Returns:
33
        OAuth 2.0 credentials for the authenticated user
34

35
    Raises:
36
        ConnectionError: If no open port can be found for local server
37
        ValueError: If client credentials are invalid
38
    """
39
```
40

41
### Usage Example
42

43
```python
44
import google_auth_oauthlib
45

46
# Configure OAuth client credentials (from Google Developer Console)
47
client_id = "your-app.apps.googleusercontent.com"
48
client_secret = "your-oauth-client-secret"
49

50
# Define required scopes for your application
51
scopes = [
52
    'https://www.googleapis.com/auth/cloud-platform',
53
    'https://www.googleapis.com/auth/userinfo.email'
54
]
55

56
# Obtain credentials interactively
57
credentials = google_auth_oauthlib.get_user_credentials(
58
    scopes, client_id, client_secret
59
)
60

61
# Use with Google API clients
62
from google.cloud import storage
63
storage_client = storage.Client(credentials=credentials)
64
```
65

66
### Port Management Utilities
67

68
Helper functions for managing local server ports during OAuth flows.
69

70
```python { .api }
71
def find_open_port(start: int = 8080, stop: Optional[int] = None) -> Optional[int]:
72
    """
73
    Find an open port between start and stop.
74

75
    Args:
76
        start: Beginning of range of ports to try (default 8080)
77
        stop: End of range (exclusive). Tries 100 ports if None
78

79
    Returns:
80
        Available port number, or None if no open port found
81
    """
82

83
def is_port_open(port: int) -> bool:
84
    """
85
    Check if a port is open on localhost.
86

87
    Args:
88
        port: Port number to check
89

90
    Returns:
91
        True if port can be bound, False otherwise
92
    """
93
```
94

95
### Constants
96

97
```python { .api }
98
LOCALHOST: str = "localhost"
99
DEFAULT_PORTS_TO_TRY: int = 100
100
```
101

102
## Common Patterns
103

104
### Jupyter Notebook Usage
105

106
```python
107
# In Jupyter notebook cell
108
import google_auth_oauthlib
109

110
credentials = google_auth_oauthlib.get_user_credentials(
111
    scopes=['https://www.googleapis.com/auth/bigquery'],
112
    client_id="your-client-id.apps.googleusercontent.com",
113
    client_secret="your-client-secret"
114
)
115

116
# Browser will open automatically for authentication
117
# After authorization, credentials are ready to use
118
```
119

120
### Custom Port Range
121

122
```python
123
# Use specific port range (e.g., for firewall restrictions)
124
credentials = google_auth_oauthlib.get_user_credentials(
125
    scopes=scopes,
126
    client_id=client_id,
127
    client_secret=client_secret,
128
    minimum_port=9000,
129
    maximum_port=9010
130
)
131
```
132

133
### Error Handling
134

135
```python
136
try:
137
    credentials = google_auth_oauthlib.get_user_credentials(
138
        scopes, client_id, client_secret
139
    )
140
except ConnectionError:
141
    print("Could not find available port for OAuth server")
142
except ValueError as e:
143
    print(f"Invalid client configuration: {e}")
144
```