0
# Channel Credentials
1

2
Lower-level credential objects for custom channel security configuration, providing fine-grained control over ALTS authentication settings.
3

4
## Capabilities
5

6
### ALTS Channel Credentials
7

8
Provides secure and authenticated communication between two cloud VMs using ALTS.
9

10
```java { .api }
11
/**
12
 * Provides secure and authenticated communication between two cloud VMs using ALTS.
13
 */
14
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/4151")
15
public final class AltsChannelCredentials {
16
    
17
    /**
18
     * Creates ALTS channel credentials with default settings
19
     * @return ChannelCredentials configured for ALTS
20
     */
21
    public static ChannelCredentials create();
22
    
23
    /**
24
     * Creates a new builder for customizing ALTS channel credentials
25
     * @return Builder instance
26
     */
27
    public static Builder newBuilder();
28
    
29
    /**
30
     * Builder for customizing ALTS channel credentials
31
     */
32
    @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4151")
33
    public static final class Builder {
34
        
35
        /**
36
         * Adds an expected target service account. One of the added service accounts
37
         * should match the peer service account in the handshaker result.
38
         * @param targetServiceAccount the expected target service account
39
         * @return this builder for chaining
40
         */
41
        public Builder addTargetServiceAccount(String targetServiceAccount);
42
        
43
        /**
44
         * Enables untrusted ALTS for testing. Disables Google Cloud Platform checks.
45
         * @return this builder for chaining
46
         */
47
        public Builder enableUntrustedAltsForTesting();
48
        
49
        /**
50
         * Sets a custom handshaker service address for testing
51
         * @param handshakerAddress the handshaker service address
52
         * @return this builder for chaining
53
         */
54
        public Builder setHandshakerAddressForTesting(String handshakerAddress);
55
        
56
        /**
57
         * Builds the channel credentials
58
         * @return the configured ChannelCredentials
59
         */
60
        public ChannelCredentials build();
61
    }
62
}
63
```
64

65
**Usage Examples:**
66

67
```java
68
import io.grpc.alts.AltsChannelCredentials;
69
import io.grpc.ChannelCredentials;
70
import io.grpc.Grpc;
71
import io.grpc.ManagedChannel;
72

73
// Basic ALTS credentials
74
ChannelCredentials creds = AltsChannelCredentials.create();
75
ManagedChannel channel = Grpc.newChannelBuilder("my-service:443", creds)
76
    .build();
77

78
// Customized ALTS credentials with service account verification
79
ChannelCredentials secureCreds = AltsChannelCredentials.newBuilder()
80
    .addTargetServiceAccount("backend@my-project.iam.gserviceaccount.com")
81
    .addTargetServiceAccount("backup@my-project.iam.gserviceaccount.com")
82
    .build();
83

84
ManagedChannel secureChannel = Grpc.newChannelBuilder("backend:8080", secureCreds)
85
    .build();
86

87
// Testing credentials
88
ChannelCredentials testCreds = AltsChannelCredentials.newBuilder()
89
    .enableUntrustedAltsForTesting()
90
    .setHandshakerAddressForTesting("localhost:9999")
91
    .build();
92

93
ManagedChannel testChannel = Grpc.newChannelBuilder("localhost:8080", testCreds)
94
    .build();
95
```
96

97
### Compute Engine Channel Credentials
98

99
Creates credentials that use ALTS on Google Cloud Platform and automatically fall back to TLS elsewhere.
100

101
```java { .api }
102
/**
103
 * Channel credentials that automatically choose ALTS on GCP and TLS elsewhere
104
 */
105
public final class ComputeEngineChannelCredentials {
106
    
107
    /**
108
     * Creates Compute Engine channel credentials with ALTS and TLS fallback
109
     * @return ChannelCredentials configured for Compute Engine environments
110
     */
111
    public static ChannelCredentials create();
112
}
113
```
114

115
**Usage Examples:**
116

117
```java
118
import io.grpc.alts.ComputeEngineChannelCredentials;
119
import io.grpc.ChannelCredentials;
120
import io.grpc.Grpc;
121
import io.grpc.ManagedChannel;
122

123
// Automatic ALTS/TLS selection
124
ChannelCredentials creds = ComputeEngineChannelCredentials.create();
125
ManagedChannel channel = Grpc.newChannelBuilder("my-service:443", creds)
126
    .build();
127

128
// Works seamlessly across environments
129
ManagedChannel flexibleChannel = Grpc.newChannelBuilder("api.googleapis.com:443", creds)
130
    .build();
131
```
132

133
### Google Default Channel Credentials
134

135
Creates credentials using the full Google Cloud authentication stack with support for both ALTS and OAuth credentials.
136

137
```java { .api }
138
/**
139
 * Channel credentials for Google Cloud services with full authentication support
140
 */
141
public final class GoogleDefaultChannelCredentials {
142
    
143
    /**
144
     * Creates Google Default channel credentials with default settings
145
     * @return ChannelCredentials configured for Google Cloud services
146
     */
147
    public static ChannelCredentials create();
148
    
149
    /**
150
     * Creates a new builder for customizing Google Default channel credentials
151
     * @return Builder instance
152
     * @since 1.43.0
153
     */
154
    public static Builder newBuilder();
155
    
156
    /**
157
     * Builder for customizing Google Default channel credentials
158
     */
159
    public static final class Builder {
160
        
161
        /**
162
         * Sets call credentials for TLS connections
163
         * @param callCreds the call credentials for TLS
164
         * @return this builder for chaining
165
         */
166
        public Builder callCredentials(CallCredentials callCreds);
167
        
168
        /**
169
         * Sets ALTS-specific call credentials
170
         * @param callCreds the ALTS-specific call credentials
171
         * @return this builder for chaining
172
         */
173
        public Builder altsCallCredentials(CallCredentials callCreds);
174
        
175
        /**
176
         * Builds the channel credentials
177
         * @return the configured ChannelCredentials
178
         */
179
        public ChannelCredentials build();
180
    }
181
}
182
```
183

184
**Usage Examples:**
185

186
```java
187
import io.grpc.alts.GoogleDefaultChannelCredentials;
188
import io.grpc.ChannelCredentials;
189
import io.grpc.Grpc;
190
import io.grpc.ManagedChannel;
191
import io.grpc.CallCredentials;
192

193
// Basic Google Default credentials
194
ChannelCredentials creds = GoogleDefaultChannelCredentials.create();
195
ManagedChannel channel = Grpc.newChannelBuilder("pubsub.googleapis.com:443", creds)
196
    .build();
197

198
// Customized with call credentials
199
CallCredentials authCreds = // ... OAuth credentials
200
ChannelCredentials customCreds = GoogleDefaultChannelCredentials.newBuilder()
201
    .callCredentials(authCreds)
202
    .build();
203

204
ManagedChannel authChannel = Grpc.newChannelBuilder("storage.googleapis.com:443", customCreds)
205
    .build();
206
```
207

208
## Integration with gRPC Core
209

210
Channel credentials integrate with the core gRPC `Grpc.newChannelBuilder()` API:
211

212
```java
213
import io.grpc.Grpc;
214
import io.grpc.ManagedChannel;
215
import io.grpc.ChannelCredentials;
216

217
// Use credentials with Grpc.newChannelBuilder()
218
ChannelCredentials credentials = // ... any ALTS credentials
219
ManagedChannel channel = Grpc.newChannelBuilder("target:443", credentials)
220
    .keepAliveTime(30, TimeUnit.SECONDS)
221
    .build();
222
```
223

224
## Credential Selection Guide
225

226
Choose the appropriate credential type based on your environment and requirements:
227

228
- **AltsChannelCredentials**: Pure ALTS authentication, requires Google Cloud Platform
229
- **ComputeEngineChannelCredentials**: ALTS on GCP with TLS fallback for other environments
230
- **GoogleDefaultChannelCredentials**: Full Google Cloud authentication stack with OAuth support
231

232
## Security Considerations
233

234
- **Service Account Verification**: Use `addTargetServiceAccount()` for additional security validation
235
- **Testing Methods**: Never use testing methods in production environments
236
- **Credential Composition**: Google Default credentials support layering OAuth and ALTS credentials
237
- **Environment Detection**: Compute Engine credentials automatically detect the runtime environment