0
# Verification Code Receivers
1

2
Interface and implementations for receiving OAuth 2.0 verification codes from users during the authorization process. These components handle the user interaction portion of OAuth 2.0 flows.
3

4
## Capabilities
5

6
### VerificationCodeReceiver Interface
7

8
Core interface that defines how verification codes are received from users during OAuth 2.0 authorization flows.
9

10
```java { .api }
11
/**
12
 * OAuth 2.0 verification code receiver.
13
 * Implementation should be thread-safe.
14
 */
15
public interface VerificationCodeReceiver {
16
    
17
    /**
18
     * Returns the redirect URI to be used in the authorization request.
19
     * @return redirect URI string
20
     * @throws IOException if URI generation fails
21
     */
22
    String getRedirectUri() throws IOException;
23
    
24
    /**
25
     * Waits for a verification code from the user.
26
     * This method blocks until a code is received.
27
     * @return verification code string
28
     * @throws IOException if code reception fails
29
     */
30
    String waitForCode() throws IOException;
31
    
32
    /**
33
     * Releases any resources and stops any processes started.
34
     * @throws IOException if resource cleanup fails
35
     */
36
    void stop() throws IOException;
37
}
38
```
39

40
### AbstractPromptReceiver
41

42
Abstract implementation that prompts the user to manually enter the verification code via console input. Suitable for command-line applications and scenarios where automatic code reception is not possible.
43

44
```java { .api }
45
/**
46
 * OAuth 2.0 abstract verification code receiver that prompts user to paste the code 
47
 * copied from the browser. Implementation is thread-safe.
48
 */
49
public abstract class AbstractPromptReceiver implements VerificationCodeReceiver {
50
    
51
    /**
52
     * Prompts the user to enter the verification code via console input.
53
     * Continues prompting until a non-empty code is entered.
54
     * @return verification code entered by user
55
     */
56
    @Override
57
    public String waitForCode();
58
    
59
    /**
60
     * No-op implementation since no resources need to be stopped.
61
     */
62
    @Override  
63
    public void stop();
64
    
65
    // Abstract method - must be implemented by subclasses
66
    /**
67
     * Returns the redirect URI. Typically "urn:ietf:wg:oauth:2.0:oob" for out-of-band flows.
68
     * @return redirect URI for the authorization request
69
     * @throws IOException if URI generation fails  
70
     */
71
    public abstract String getRedirectUri() throws IOException;
72
}
73
```
74

75
**Usage Example:**
76

77
```java
78
import com.google.api.client.extensions.java6.auth.oauth2.AbstractPromptReceiver;
79

80
// Create a simple console-based receiver for out-of-band authorization
81
public class ConsoleReceiver extends AbstractPromptReceiver {
82
    @Override
83
    public String getRedirectUri() throws IOException {
84
        // Out-of-band redirect URI for manual code entry
85
        return "urn:ietf:wg:oauth:2.0:oob";
86
    }
87
}
88

89
// Usage in authorization flow
90
ConsoleReceiver receiver = new ConsoleReceiver();
91
AuthorizationCodeInstalledApp app = new AuthorizationCodeInstalledApp(flow, receiver);
92

93
// When authorize() is called:
94
// 1. Browser opens to authorization URL
95
// 2. User grants permission and copies the code
96
// 3. Console prompts: "Please enter code: "
97
// 4. User pastes the code and presses Enter
98
// 5. Authorization completes
99
Credential credential = app.authorize("user-id");
100
```
101

102
**Custom Receiver Example:**
103

104
```java
105
import com.google.api.client.extensions.java6.auth.oauth2.VerificationCodeReceiver;
106
import java.util.Scanner;
107

108
// Custom receiver that uses a GUI dialog instead of console
109
public class DialogReceiver implements VerificationCodeReceiver {
110
    private JDialog dialog;
111
    private String code;
112
    
113
    @Override
114
    public String getRedirectUri() throws IOException {
115
        return "urn:ietf:wg:oauth:2.0:oob";
116
    }
117
    
118
    @Override
119
    public String waitForCode() throws IOException {
120
        SwingUtilities.invokeLater(() -> {
121
            dialog = new JDialog();
122
            JTextField codeField = new JTextField(30);
123
            JButton okButton = new JButton("OK");
124
            
125
            okButton.addActionListener(e -> {
126
                code = codeField.getText();
127
                dialog.dispose();
128
            });
129
            
130
            dialog.add(new JLabel("Enter verification code:"));
131
            dialog.add(codeField);
132
            dialog.add(okButton);
133
            dialog.setModal(true);
134
            dialog.pack();
135
            dialog.setVisible(true);
136
        });
137
        
138
        // Wait for dialog completion
139
        while (code == null) {
140
            Thread.sleep(100);
141
        }
142
        return code;
143
    }
144
    
145
    @Override
146
    public void stop() throws IOException {
147
        if (dialog != null) {
148
            dialog.dispose();
149
        }
150
    }
151
}
152
```
153

154
## Implementation Guidelines
155

156
### Thread Safety
157
All `VerificationCodeReceiver` implementations should be thread-safe as specified in the interface documentation.
158

159
### Resource Management
160
Always implement the `stop()` method to properly clean up resources:
161
- Close network connections
162
- Dispose of GUI components  
163
- Stop background threads
164
- Release file handles
165

166
### Error Handling
167
Handle common error scenarios:
168
- User cancellation (return null or throw specific exception)
169
- Network timeouts for web-based receivers
170
- Invalid code formats
171
- I/O errors during code reception
172

173
### Redirect URI Patterns
174
Common redirect URI patterns:
175
- `"urn:ietf:wg:oauth:2.0:oob"` - Out-of-band (manual code entry)
176
- `"http://localhost:8080"` - Local HTTP server
177
- `"http://localhost:0"` - Local HTTP server with random port
178
- Custom protocol schemes for desktop applications
179

180
## Out-of-Band Authorization Flow
181

182
The out-of-band (OOB) flow is commonly used with `AbstractPromptReceiver`:
183

184
1. **Authorization URL**: Generated with redirect URI `urn:ietf:wg:oauth:2.0:oob`
185
2. **User Action**: User visits URL in browser and grants permission
186
3. **Code Display**: Authorization server displays verification code to user
187
4. **Manual Entry**: User copies code and pastes it into application prompt
188
5. **Token Exchange**: Application exchanges code for access token
189

190
This flow is ideal for:
191
- Command-line applications
192
- Applications without HTTP server capabilities
193
- Environments where localhost redirection is not available