0
# Configuration and Settings
1

2
Django settings integration, constants, and system validation for reCAPTCHA configuration. Provides development support with test keys, comprehensive Django settings integration, and system checks for production readiness.
3

4
## Capabilities
5

6
### Django Settings Integration
7

8
The package integrates with Django's settings system for global configuration. All settings are optional and have sensible defaults for development.
9

10
```python { .api }
11
# Django settings.py configuration
12
RECAPTCHA_PUBLIC_KEY = "your_site_key_here"
13
RECAPTCHA_PRIVATE_KEY = "your_secret_key_here"
14
RECAPTCHA_DOMAIN = "www.google.com"  # or "www.recaptcha.net" for global access
15
RECAPTCHA_PROXY = {
16
    'http': 'http://proxy.example.com:8080',
17
    'https': 'https://proxy.example.com:8080'
18
}
19
RECAPTCHA_VERIFY_REQUEST_TIMEOUT = 10  # seconds
20
RECAPTCHA_REQUIRED_SCORE = 0.5  # Default V3 score threshold
21
```
22

23
### Test Keys and Development Support
24

25
Constants providing Google's official test keys for development and testing environments.
26

27
```python { .api }
28
TEST_PUBLIC_KEY = "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
29
"""
30
Google's official test public key.
31
Always passes reCAPTCHA validation without showing challenges.
32
"""
33

34
TEST_PRIVATE_KEY = "6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe"
35
"""
36
Google's official test private key.
37
Paired with test public key for development environments.
38
"""
39

40
DEFAULT_RECAPTCHA_DOMAIN = "www.google.com"
41
"""
42
Default API domain for reCAPTCHA requests.
43
Can be changed to www.recaptcha.net for global accessibility.
44
"""
45
```
46

47
### Django App Configuration
48

49
App configuration class providing Django integration and system check registration.
50

51
```python { .api }
52
class DjangoRecaptchaConfig(AppConfig):
53
    """
54
    Django app configuration for django-recaptcha.
55
    
56
    Registers system checks for production readiness validation.
57
    """
58
    name = "django_recaptcha"
59
    verbose_name = "Django reCAPTCHA"
60
    
61
    def ready(self):
62
        """
63
        Called when Django app is ready.
64
        
65
        Registers security system checks for reCAPTCHA configuration.
66
        """
67
```
68

69
### System Checks
70

71
Function that validates reCAPTCHA configuration and warns about test key usage in production.
72

73
```python { .api }
74
def recaptcha_key_check(app_configs, **kwargs):
75
    """
76
    Django system check for reCAPTCHA key configuration.
77
    
78
    Validates that production keys are used instead of Google's test keys.
79
    
80
    Parameters:
81
    - app_configs: Django app configurations
82
    - **kwargs: Additional system check parameters
83
    
84
    Returns:
85
    list[checks.Error]: List of configuration errors found
86
    
87
    Generates:
88
    - django_recaptcha.recaptcha_test_key_error: When test keys detected
89
    """
90
```
91

92
## Settings Reference
93

94
### Required Settings
95

96
For production use, configure your reCAPTCHA keys:
97

98
```python
99
# Required for production
100
RECAPTCHA_PUBLIC_KEY = "6Lc..."  # Your site key from Google
101
RECAPTCHA_PRIVATE_KEY = "6Lc..."  # Your secret key from Google
102
```
103

104
### Optional Settings
105

106
Additional configuration options for customization:
107

108
```python
109
# API Configuration
110
RECAPTCHA_DOMAIN = "www.recaptcha.net"  # Alternative domain for global access
111
RECAPTCHA_VERIFY_REQUEST_TIMEOUT = 15   # API request timeout in seconds
112

113
# Proxy Configuration
114
RECAPTCHA_PROXY = {
115
    'http': 'http://proxy.company.com:8080',
116
    'https': 'https://proxy.company.com:8080'
117
}
118

119
# V3 Configuration
120
RECAPTCHA_REQUIRED_SCORE = 0.7  # Default minimum score for V3 validation
121
```
122

123
### Settings Validation
124

125
The package validates settings types at import time:
126

127
- `RECAPTCHA_DOMAIN`: Must be string
128
- `RECAPTCHA_PRIVATE_KEY`: Must be string
129
- `RECAPTCHA_PROXY`: Must be dictionary
130
- `RECAPTCHA_PUBLIC_KEY`: Must be string
131
- `RECAPTCHA_VERIFY_REQUEST_TIMEOUT`: Must be integer
132

133
## System Checks
134

135
### Production Readiness Check
136

137
The package includes a Django system check that warns when test keys are used:
138

139
```python
140
# Check ID: django_recaptcha.recaptcha_test_key_error
141
# Level: ERROR
142
# Message: RECAPTCHA_PRIVATE_KEY or RECAPTCHA_PUBLIC_KEY is making use
143
#          of the Google test keys and will not behave as expected in a
144
#          production environment
145
```
146

147
### Silencing Checks
148

149
To silence the system check (not recommended), add to settings:
150

151
```python
152
SILENCED_SYSTEM_CHECKS = ['django_recaptcha.recaptcha_test_key_error']
153
```
154

155
## Usage Examples
156

157
### Basic Configuration
158

159
```python
160
# settings.py
161
INSTALLED_APPS = [
162
    'django.contrib.admin',
163
    'django.contrib.auth',
164
    'django.contrib.contenttypes',
165
    'django.contrib.sessions',
166
    'django.contrib.messages',
167
    'django.contrib.staticfiles',
168
    'django_recaptcha',  # Add to INSTALLED_APPS
169
]
170

171
# reCAPTCHA configuration
172
RECAPTCHA_PUBLIC_KEY = '6Lc_your_site_key_here'
173
RECAPTCHA_PRIVATE_KEY = '6Lc_your_secret_key_here'
174
```
175

176
### Development Configuration
177

178
```python
179
# settings.py - Development
180
DEBUG = True
181

182
# No need to set reCAPTCHA keys - will use test keys automatically
183
# Test keys always pass validation without user interaction
184
```
185

186
### Production Configuration
187

188
```python
189
# settings.py - Production
190
DEBUG = False
191

192
# Production reCAPTCHA keys (required)
193
RECAPTCHA_PUBLIC_KEY = os.environ.get('RECAPTCHA_PUBLIC_KEY')
194
RECAPTCHA_PRIVATE_KEY = os.environ.get('RECAPTCHA_PRIVATE_KEY')
195

196
# Optional: Custom domain for global access
197
RECAPTCHA_DOMAIN = 'www.recaptcha.net'
198

199
# Optional: Proxy configuration
200
RECAPTCHA_PROXY = {
201
    'http': os.environ.get('HTTP_PROXY'),
202
    'https': os.environ.get('HTTPS_PROXY')
203
}
204
```
205

206
### Enterprise Configuration
207

208
```python
209
# settings.py - Enterprise environment
210
RECAPTCHA_PUBLIC_KEY = '6Lc_enterprise_site_key'
211
RECAPTCHA_PRIVATE_KEY = '6Lc_enterprise_secret_key'
212

213
# Proxy configuration for corporate network
214
RECAPTCHA_PROXY = {
215
    'http': 'http://corporate-proxy.company.com:8080',
216
    'https': 'https://corporate-proxy.company.com:8080'
217
}
218

219
# Increased timeout for slower networks
220
RECAPTCHA_VERIFY_REQUEST_TIMEOUT = 30
221

222
# Stricter V3 scoring
223
RECAPTCHA_REQUIRED_SCORE = 0.8
224
```
225

226
### Multi-environment Configuration
227

228
```python
229
# settings/base.py
230
INSTALLED_APPS = [
231
    # ... other apps
232
    'django_recaptcha',
233
]
234

235
# settings/development.py
236
from .base import *
237
# Uses test keys automatically
238

239
# settings/staging.py  
240
from .base import *
241
RECAPTCHA_PUBLIC_KEY = '6Lc_staging_site_key'
242
RECAPTCHA_PRIVATE_KEY = '6Lc_staging_secret_key'
243

244
# settings/production.py
245
from .base import *
246
RECAPTCHA_PUBLIC_KEY = os.environ['RECAPTCHA_PUBLIC_KEY']
247
RECAPTCHA_PRIVATE_KEY = os.environ['RECAPTCHA_PRIVATE_KEY']
248
RECAPTCHA_DOMAIN = 'www.recaptcha.net'
249
```
250

251
### Runtime Key Configuration
252

253
```python
254
# Override keys per field instance
255
from django_recaptcha.fields import ReCaptchaField
256

257
class SpecialForm(forms.Form):
258
    # Use different keys for specific forms
259
    captcha = ReCaptchaField(
260
        public_key='6Lc_special_public_key',
261
        private_key='6Lc_special_private_key'
262
    )
263
```