0
# Server Credentials
1
2
Lower-level credential objects for custom server security configuration, providing fine-grained control over ALTS authentication settings for gRPC servers.
3
4
## Capabilities
5
6
### ALTS Server Credentials
7
8
Provides secure ALTS authentication for gRPC servers running on Google Cloud Platform.
9
10
```java { .api }
11
/**
12
* Server credentials for ALTS authentication on Google Cloud Platform
13
*/
14
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/4151")
15
public final class AltsServerCredentials {
16
17
/**
18
* Creates ALTS server credentials with default settings
19
* @return ServerCredentials configured for ALTS
20
*/
21
public static ServerCredentials create();
22
23
/**
24
* Creates a new builder for customizing ALTS server credentials
25
* @return Builder instance
26
*/
27
public static Builder newBuilder();
28
29
/**
30
* Builder for customizing ALTS server credentials
31
*/
32
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/4151")
33
public static final class Builder {
34
35
/**
36
* Enables untrusted ALTS for testing. Disables Google Cloud Platform checks.
37
* @return this builder for chaining
38
*/
39
public Builder enableUntrustedAltsForTesting();
40
41
/**
42
* Sets a custom handshaker service address for testing
43
* @param handshakerAddress the handshaker service address
44
* @return this builder for chaining
45
*/
46
public Builder setHandshakerAddressForTesting(String handshakerAddress);
47
48
/**
49
* Builds the server credentials
50
* @return the configured ServerCredentials
51
*/
52
public ServerCredentials build();
53
}
54
}
55
```
56
57
**Usage Examples:**
58
59
```java
60
import io.grpc.alts.AltsServerCredentials;
61
import io.grpc.ServerCredentials;
62
import io.grpc.Grpc;
63
import io.grpc.Server;
64
65
// Basic ALTS server credentials
66
ServerCredentials creds = AltsServerCredentials.create();
67
Server server = Grpc.newServerBuilderForPort(8080, creds)
68
.addService(new MyServiceImpl())
69
.build();
70
71
server.start();
72
73
// Customized server credentials for testing
74
ServerCredentials testCreds = AltsServerCredentials.newBuilder()
75
.enableUntrustedAltsForTesting()
76
.setHandshakerAddressForTesting("localhost:9999")
77
.build();
78
79
Server testServer = Grpc.newServerBuilderForPort(8080, testCreds)
80
.addService(new TestServiceImpl())
81
.build();
82
83
testServer.start();
84
```
85
86
## Integration with gRPC Core
87
88
Server credentials integrate with the core gRPC `Grpc.newServerBuilderForPort()` API:
89
90
```java
91
import io.grpc.Grpc;
92
import io.grpc.Server;
93
import io.grpc.ServerCredentials;
94
import io.grpc.BindableService;
95
96
// Use credentials with Grpc.newServerBuilderForPort()
97
ServerCredentials credentials = AltsServerCredentials.create();
98
Server server = Grpc.newServerBuilderForPort(8080, credentials)
99
.addService(new MyServiceImpl())
100
.handshakeTimeout(30, TimeUnit.SECONDS)
101
.executor(Executors.newFixedThreadPool(10))
102
.build();
103
104
server.start();
105
```
106
107
## Server Lifecycle with Credentials
108
109
```java
110
import io.grpc.alts.AltsServerCredentials;
111
import io.grpc.ServerCredentials;
112
import io.grpc.Grpc;
113
import io.grpc.Server;
114
import java.util.concurrent.TimeUnit;
115
116
public class AltsServerExample {
117
public static void main(String[] args) throws Exception {
118
// Create server credentials
119
ServerCredentials creds = AltsServerCredentials.create();
120
121
// Build and start server
122
Server server = Grpc.newServerBuilderForPort(8080, creds)
123
.addService(new MyGrpcServiceImpl())
124
.build()
125
.start();
126
127
System.out.println("ALTS server started on port 8080");
128
129
// Add shutdown hook
130
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
131
System.out.println("Shutting down ALTS server...");
132
server.shutdown();
133
try {
134
if (!server.awaitTermination(5, TimeUnit.SECONDS)) {
135
server.shutdownNow();
136
}
137
} catch (InterruptedException e) {
138
server.shutdownNow();
139
}
140
}));
141
142
// Wait for termination
143
server.awaitTermination();
144
}
145
}
146
```
147
148
## Testing Configuration
149
150
For development and testing environments, server credentials support special testing modes:
151
152
```java
153
import io.grpc.alts.AltsServerCredentials;
154
import io.grpc.ServerCredentials;
155
156
// Testing credentials that bypass GCP environment checks
157
ServerCredentials testCreds = AltsServerCredentials.newBuilder()
158
.enableUntrustedAltsForTesting()
159
.setHandshakerAddressForTesting("localhost:9999")
160
.build();
161
162
// Use with local handshaker service for integration testing
163
Server testServer = Grpc.newServerBuilderForPort(8080, testCreds)
164
.addService(new TestServiceImpl())
165
.build();
166
```
167
168
## Security Considerations
169
170
- **Production Usage**: Always use `AltsServerCredentials.create()` in production
171
- **Testing Methods**: Never use `enableUntrustedAltsForTesting()` in production environments
172
- **Google Cloud Platform**: ALTS server credentials only work on authenticated Google Cloud VMs
173
- **Mutual Authentication**: Both client and server identities are verified during the ALTS handshake
174
- **Handshaker Service**: The server communicates with Google's ALTS handshaker service for authentication
175
176
## Comparison with Server Builders
177
178
Server credentials provide lower-level control compared to `AltsServerBuilder`:
179
180
| Feature | AltsServerCredentials | AltsServerBuilder |
181
|---------|----------------------|-------------------|
182
| **Abstraction Level** | Low-level credential object | High-level builder |
183
| **Integration** | Works with `Grpc.newServerBuilderForPort()` | Self-contained builder |
184
| **Configuration** | Limited to credential settings | Full server configuration |
185
| **Use Case** | Custom server setups | Standard ALTS servers |
186
187
Choose `AltsServerCredentials` when you need to integrate ALTS with custom server configurations or existing gRPC server code.