0
# Authentication
1

2
Authentication system supporting multiple authentication schemes including basic, Kerberos, bearer tokens, and custom authentication mechanisms. The authentication system provides flexible credential management with support for both driver-level and session-level authentication.
3

4
## Capabilities
5

6
### Authentication Functions
7

8
Factory functions for creating authentication tokens for different authentication schemes.
9

10
```python { .api }
11
def basic_auth(user: str, password: str, realm: str = None) -> Auth:
12
    """
13
    Create basic authentication token for username/password authentication.
14
    
15
    Parameters:
16
    - user: Username for authentication
17
    - password: Password for authentication  
18
    - realm: Authentication realm (optional)
19
    
20
    Returns:
21
    Auth token configured for basic authentication
22
    """
23

24
def kerberos_auth(base64_encoded_ticket: str) -> Auth:
25
    """
26
    Create Kerberos authentication token.
27
    
28
    Parameters:
29
    - base64_encoded_ticket: Base64 encoded Kerberos ticket
30
    
31
    Returns:
32
    Auth token configured for Kerberos authentication
33
    """
34

35
def bearer_auth(base64_encoded_token: str) -> Auth:
36
    """
37
    Create bearer token authentication for OAuth/JWT scenarios.
38
    
39
    Parameters:
40
    - base64_encoded_token: Base64 encoded bearer token
41
    
42
    Returns:
43
    Auth token configured for bearer token authentication
44
    """
45

46
def custom_auth(
47
    principal: str,
48
    credentials: str, 
49
    realm: str,
50
    scheme: str,
51
    **parameters
52
) -> Auth:
53
    """
54
    Create custom authentication token for non-standard schemes.
55
    
56
    Parameters:
57
    - principal: User being authenticated
58
    - credentials: Authentication credentials
59
    - realm: Authentication realm/provider
60
    - scheme: Authentication scheme name
61
    - **parameters: Additional authentication parameters
62
    
63
    Returns:
64
    Auth token configured with custom authentication details
65
    """
66
```
67

68
Example authentication usage:
69

70
```python
71
from neo4j import GraphDatabase, basic_auth, bearer_auth, custom_auth
72

73
# Basic username/password authentication (most common)
74
driver = GraphDatabase.driver(
75
    "bolt://localhost:7687",
76
    auth=basic_auth("neo4j", "password")
77
)
78

79
# Basic auth with realm
80
driver = GraphDatabase.driver(
81
    "bolt://localhost:7687", 
82
    auth=basic_auth("user", "password", realm="production")
83
)
84

85
# Bearer token authentication (OAuth/JWT)
86
driver = GraphDatabase.driver(
87
    "bolt://localhost:7687",
88
    auth=bearer_auth("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
89
)
90

91
# Custom authentication scheme  
92
driver = GraphDatabase.driver(
93
    "bolt://localhost:7687",
94
    auth=custom_auth(
95
        principal="user@domain.com",
96
        credentials="secret_key", 
97
        realm="ldap_server",
98
        scheme="LDAP",
99
        server="ldap.company.com",
100
        port=389
101
    )
102
)
103
```
104

105
### Auth Class
106

107
Container class holding authentication details and credentials for database connections.
108

109
```python { .api }
110
class Auth:
111
    def __init__(
112
        self,
113
        scheme: str,
114
        principal: str, 
115
        credentials: str,
116
        realm: str = None,
117
        **parameters
118
    ):
119
        """
120
        Create authentication token.
121
        
122
        Parameters:
123
        - scheme: Authentication scheme identifier
124
        - principal: User being authenticated
125
        - credentials: Authentication credentials (password, token, etc.)
126
        - realm: Authentication provider/realm
127
        - **parameters: Additional scheme-specific parameters
128
        """
129
    
130
    @property
131
    def scheme(self) -> str | None:
132
        """
133
        Authentication scheme identifier.
134
        
135
        Returns:
136
        String identifying the authentication method (basic, kerberos, etc.)
137
        """
138
    
139
    @property
140
    def principal(self) -> str | None:
141
        """
142
        User being authenticated.
143
        
144
        Returns:
145
        Username or principal identifier
146
        """
147
    
148
    @property
149
    def credentials(self) -> str | None:
150
        """
151
        Authentication credentials.
152
        
153
        Returns:
154
        Password, token, or other credential data
155
        """
156
    
157
    @property
158
    def realm(self) -> str | None:
159
        """
160
        Authentication provider or realm.
161
        
162
        Returns:
163
        Realm identifier for the authentication provider
164
        """
165
    
166
    @property
167
    def parameters(self) -> dict:
168
        """
169
        Additional authentication parameters.
170
        
171
        Returns:
172
        Dictionary of scheme-specific parameters
173
        """
174
```
175

176
AuthToken is an alias for the Auth class:
177

178
```python { .api }
179
# AuthToken is identical to Auth
180
AuthToken = Auth
181
```
182

183
## Authentication Examples
184

185
### Basic Authentication
186

187
The most common authentication method using username and password:
188

189
```python
190
from neo4j import GraphDatabase, basic_auth
191

192
# Simple basic authentication
193
auth = basic_auth("neo4j", "password")
194
driver = GraphDatabase.driver("bolt://localhost:7687", auth=auth)
195

196
# With explicit realm
197
auth = basic_auth("username", "password", realm="my_realm")
198
driver = GraphDatabase.driver("bolt://localhost:7687", auth=auth)
199

200
# Manual Auth construction (equivalent to basic_auth)
201
from neo4j import Auth
202
auth = Auth("basic", "neo4j", "password")
203
driver = GraphDatabase.driver("bolt://localhost:7687", auth=auth)
204
```
205

206
### Session-Level Authentication
207

208
Authentication can be overridden at the session level for per-session credentials:
209

210
```python
211
# Driver with default authentication
212
driver = GraphDatabase.driver(
213
    "bolt://localhost:7687",
214
    auth=basic_auth("default_user", "default_password")
215
)
216

217
# Session with different authentication
218
with driver.session(auth=basic_auth("admin_user", "admin_password")) as session:
219
    # This session uses admin credentials
220
    result = session.run("SHOW USERS")
221
    
222
# Back to default credentials for subsequent sessions
223
with driver.session() as session:
224
    # Uses default_user credentials
225
    result = session.run("MATCH (n) RETURN count(n)")
226
```
227

228
### Bearer Token Authentication
229

230
For OAuth, JWT, or other token-based authentication:
231

232
```python
233
from neo4j import GraphDatabase, bearer_auth
234

235
# Using bearer token (JWT example)
236
jwt_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
237

238
auth = bearer_auth(jwt_token)
239
driver = GraphDatabase.driver("bolt://localhost:7687", auth=auth)
240

241
# Token refresh example
242
class TokenRefreshAuth:
243
    def __init__(self, initial_token):
244
        self._token = initial_token
245
    
246
    def get_current_auth(self):
247
        # Refresh token logic here
248
        return bearer_auth(self._token)
249

250
token_auth = TokenRefreshAuth("initial_token")
251
driver = GraphDatabase.driver("bolt://localhost:7687", auth=token_auth.get_current_auth())
252
```
253

254
### Kerberos Authentication
255

256
For environments using Kerberos authentication:
257

258
```python
259
from neo4j import GraphDatabase, kerberos_auth
260
import base64
261

262
# Obtain Kerberos ticket (implementation specific)
263
kerberos_ticket = obtain_kerberos_ticket()  # Your Kerberos implementation
264
encoded_ticket = base64.b64encode(kerberos_ticket).decode('utf-8')
265

266
auth = kerberos_auth(encoded_ticket)
267
driver = GraphDatabase.driver("bolt://localhost:7687", auth=auth)
268
```
269

270
### Custom Authentication Schemes
271

272
For proprietary or specialized authentication systems:
273

274
```python
275
from neo4j import GraphDatabase, custom_auth
276

277
# LDAP authentication example
278
auth = custom_auth(
279
    principal="user@company.com",
280
    credentials="ldap_password",
281
    realm="ldap.company.com", 
282
    scheme="LDAP",
283
    # Additional LDAP-specific parameters
284
    server="ldap.company.com",
285
    port=389,
286
    base_dn="ou=users,dc=company,dc=com"
287
)
288

289
driver = GraphDatabase.driver("bolt://localhost:7687", auth=auth)
290

291
# API key authentication example
292
auth = custom_auth(
293
    principal="api_user",
294
    credentials="api_key_12345",
295
    realm="api_service",
296
    scheme="APIKEY",
297
    # Additional parameters
298
    service_name="neo4j_service",
299
    key_version="v2"
300
)
301

302
driver = GraphDatabase.driver("bolt://localhost:7687", auth=auth)
303
```
304

305
### No Authentication
306

307
For development or unsecured environments:
308

309
```python
310
from neo4j import GraphDatabase
311

312
# No authentication (auth=None is default)
313
driver = GraphDatabase.driver("bolt://localhost:7687")
314

315
# Explicit no auth
316
driver = GraphDatabase.driver("bolt://localhost:7687", auth=None)
317
```
318

319
## Authentication Verification
320

321
Drivers can verify authentication credentials before executing queries:
322

323
```python
324
from neo4j import GraphDatabase, basic_auth
325

326
driver = GraphDatabase.driver("bolt://localhost:7687", auth=basic_auth("neo4j", "password"))
327

328
try:
329
    # Verify authentication works
330
    is_valid = driver.verify_authentication()
331
    print(f"Authentication valid: {is_valid}")
332
    
333
    # Verify different credentials
334
    alt_auth = basic_auth("different_user", "different_password")
335
    is_valid = driver.verify_authentication(auth=alt_auth)
336
    print(f"Alternative auth valid: {is_valid}")
337
    
338
except Exception as e:
339
    print(f"Authentication verification failed: {e}")
340
```
341

342
## Security Considerations
343

344
### Credential Storage
345

346
```python
347
import os
348
from neo4j import GraphDatabase, basic_auth
349

350
# Use environment variables for credentials
351
username = os.getenv("NEO4J_USERNAME", "neo4j")
352
password = os.getenv("NEO4J_PASSWORD")
353

354
if not password:
355
    raise ValueError("NEO4J_PASSWORD environment variable must be set")
356

357
driver = GraphDatabase.driver(
358
    "bolt://localhost:7687",
359
    auth=basic_auth(username, password)
360
)
361
```
362

363
### Connection Encryption
364

365
Authentication should be used with encrypted connections:
366

367
```python
368
from neo4j import GraphDatabase, basic_auth
369

370
# Secure connection with authentication
371
driver = GraphDatabase.driver(
372
    "bolt+s://production.neo4j.com:7687",  # Encrypted connection
373
    auth=basic_auth("username", "password"),
374
    encrypted=True,
375
    trust=neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
376
)
377
```
378

379
### Authentication Rotation
380

381
```python
382
class RotatingAuth:
383
    def __init__(self):
384
        self._current_auth = None
385
        self._refresh_time = 0
386
    
387
    def get_auth(self):
388
        import time
389
        now = time.time()
390
        
391
        # Refresh every hour
392
        if now - self._refresh_time > 3600:
393
            self._current_auth = self._refresh_credentials()
394
            self._refresh_time = now
395
        
396
        return self._current_auth
397
    
398
    def _refresh_credentials(self):
399
        # Implement credential refresh logic
400
        new_token = fetch_new_token()
401
        return bearer_auth(new_token)
402

403
auth_manager = RotatingAuth()
404
driver = GraphDatabase.driver("bolt://localhost:7687", auth=auth_manager.get_auth())
405
```