0
# Authorization Code Flow
1

2
OAuth 2.0 authorization code flow implementation for installed applications, providing complete integration with browser launching, verification code handling, and credential management.
3

4
## Capabilities
5

6
### AuthorizationCodeInstalledApp
7

8
Main class that orchestrates the OAuth 2.0 authorization flow for installed applications.
9

10
```java { .api }
11
/**
12
 * OAuth 2.0 authorization code flow for an installed Java application that persists end-user credentials.
13
 * Implementation is thread-safe.
14
 */
15
public class AuthorizationCodeInstalledApp {
16
    
17
    /**
18
     * Constructor with default browser support.
19
     * @param flow authorization code flow
20
     * @param receiver verification code receiver
21
     */
22
    public AuthorizationCodeInstalledApp(
23
        AuthorizationCodeFlow flow, 
24
        VerificationCodeReceiver receiver);
25
    
26
    /**
27
     * Constructor with custom browser implementation.
28
     * @param flow authorization code flow
29
     * @param receiver verification code receiver  
30
     * @param browser custom browser implementation
31
     */
32
    public AuthorizationCodeInstalledApp(
33
        AuthorizationCodeFlow flow, 
34
        VerificationCodeReceiver receiver, 
35
        Browser browser);
36
    
37
    /**
38
     * Authorizes the installed application to access user's protected data.
39
     * @param userId user ID or null if not using a persisted credential store
40
     * @return credential with access token and optional refresh token
41
     * @throws IOException if authorization fails
42
     */
43
    public Credential authorize(String userId) throws IOException;
44
    
45
    /** Returns the authorization code flow. */
46
    public final AuthorizationCodeFlow getFlow();
47
    
48
    /** Returns the verification code receiver. */
49
    public final VerificationCodeReceiver getReceiver();
50
    
51
    /**
52
     * Open a browser at the given URL using Desktop if available, 
53
     * or alternatively output the URL to System.out for command-line applications.
54
     * @param url URL to browse
55
     */
56
    public static void browse(String url);
57
}
58
```
59

60
**Usage Example:**
61

62
```java
63
import com.google.api.client.auth.oauth2.AuthorizationCodeFlow;
64
import com.google.api.client.auth.oauth2.BearerToken;
65
import com.google.api.client.auth.oauth2.Credential;
66
import com.google.api.client.extensions.java6.auth.oauth2.AuthorizationCodeInstalledApp;
67
import com.google.api.client.extensions.java6.auth.oauth2.AbstractPromptReceiver;
68
import com.google.api.client.http.javanet.NetHttpTransport;
69
import com.google.api.client.json.gson.GsonFactory;
70

71
// Create a prompt receiver for out-of-band authorization
72
class OobReceiver extends AbstractPromptReceiver {
73
    @Override
74
    public String getRedirectUri() {
75
        return "urn:ietf:wg:oauth:2.0:oob";
76
    }
77
}
78

79
// Set up the authorization flow
80
AuthorizationCodeFlow flow = new AuthorizationCodeFlow.Builder(
81
    BearerToken.authorizationHeaderAccessMethod(),
82
    new NetHttpTransport(),
83
    GsonFactory.getDefaultInstance(),
84
    new GenericUrl("https://oauth2.googleapis.com/token"),
85
    new ClientParametersAuthentication("your-client-id", "your-client-secret"),
86
    "your-client-id",
87
    "https://accounts.google.com/o/oauth2/auth")
88
    .setScopes(Arrays.asList("https://www.googleapis.com/auth/drive"))
89
    .build();
90

91
// Authorize the user
92
OobReceiver receiver = new OobReceiver();
93
AuthorizationCodeInstalledApp app = new AuthorizationCodeInstalledApp(flow, receiver);
94
Credential credential = app.authorize("user-id");
95

96
// Use the credential for API calls
97
if (credential.getAccessToken() != null) {
98
    System.out.println("Authorization successful!");
99
}
100
```
101

102
### Browser Interface
103

104
Interface for custom browser implementations to handle authorization URL opening.
105

106
```java { .api }
107
/**
108
 * Helper interface to allow caller to browse.
109
 */
110
public static interface Browser {
111
    /**
112
     * Browse to the specified URL.
113
     * @param url url to browse
114
     * @throws IOException if browsing fails
115
     */
116
    public void browse(String url) throws IOException;
117
}
118
```
119

120
### DefaultBrowser
121

122
Default browser implementation that delegates to the static browse method.
123

124
```java { .api }
125
/**
126
 * Default browser that just delegates to AuthorizationCodeInstalledApp.browse(String).
127
 */
128
public static class DefaultBrowser implements Browser {
129
    @Override
130
    public void browse(String url) throws IOException;
131
}
132
```
133

134
## Protected Methods
135

136
### onAuthorization
137

138
Hook method for customizing the authorization process, such as adding state parameters.
139

140
```java { .api }
141
/**
142
 * Handles user authorization by redirecting to the OAuth 2.0 authorization server.
143
 * Default implementation calls browse(authorizationUrl.build()).
144
 * @param authorizationUrl authorization URL that can be customized
145
 * @throws IOException I/O exception
146
 */
147
protected void onAuthorization(AuthorizationCodeRequestUrl authorizationUrl) throws IOException;
148
```
149

150
**Customization Example:**
151

152
```java
153
class CustomInstalledApp extends AuthorizationCodeInstalledApp {
154
    public CustomInstalledApp(AuthorizationCodeFlow flow, VerificationCodeReceiver receiver) {
155
        super(flow, receiver);
156
    }
157
    
158
    @Override
159
    protected void onAuthorization(AuthorizationCodeRequestUrl authorizationUrl) throws IOException {
160
        // Add state parameter for security
161
        authorizationUrl.setState("random-state-value");
162
        // Add additional parameters
163
        authorizationUrl.set("prompt", "consent");
164
        super.onAuthorization(authorizationUrl);
165
    }
166
}
167
```
168

169
## Flow Process
170

171
1. **Check Existing Credentials**: Loads existing credential for the user ID if available
172
2. **Validate Existing Token**: Checks if current credential is valid and not expired
173
3. **Browser Launch**: Opens authorization URL in user's default browser
174
4. **Code Collection**: Waits for user to paste verification code via the receiver
175
5. **Token Exchange**: Exchanges authorization code for access token and refresh token
176
6. **Credential Storage**: Stores the new credential using the flow's credential store
177
7. **Cleanup**: Stops the verification code receiver and releases resources