0
# gRPC ALTS Java Library
1

2
The gRPC ALTS (Application Layer Transport Security) Java library provides secure, authenticated communication capabilities for gRPC applications running on Google Cloud Platform. ALTS enables mutual authentication and encryption between services without explicit credential management, leveraging Google's infrastructure for automatic service identity verification.
3

4
## Package Information
5

6
- **Package Name**: grpc-alts
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Maven coordinates `io.grpc:grpc-alts:1.73.0`
10

11
## Core Imports
12

13
```java
14
import io.grpc.alts.AltsChannelBuilder;
15
import io.grpc.alts.AltsServerBuilder;
16
import io.grpc.alts.AltsChannelCredentials;
17
import io.grpc.alts.AltsServerCredentials;
18
import io.grpc.alts.AltsContext;
19
import io.grpc.alts.AltsContextUtil;
20
import io.grpc.alts.ComputeEngineChannelBuilder;
21
import io.grpc.alts.GoogleDefaultChannelBuilder;
22
```
23

24
## Basic Usage
25

26
### Client Channel with ALTS
27

28
```java
29
import io.grpc.alts.AltsChannelBuilder;
30
import io.grpc.ManagedChannel;
31

32
// Create a secure ALTS channel to a target service
33
ManagedChannel channel = AltsChannelBuilder.forTarget("example-service:443")
34
    .addTargetServiceAccount("expected-service@gcp-project.iam.gserviceaccount.com")
35
    .build();
36

37
// Use the channel for gRPC calls
38
YourServiceGrpc.YourServiceBlockingStub stub = 
39
    YourServiceGrpc.newBlockingStub(channel);
40
```
41

42
### Server with ALTS
43

44
```java
45
import io.grpc.alts.AltsServerBuilder;
46
import io.grpc.Server;
47

48
// Create a secure ALTS server
49
Server server = AltsServerBuilder.forPort(8080)
50
    .addService(new YourServiceImpl())
51
    .build();
52

53
server.start();
54
```
55

56
### Compute Engine Channel (ALTS with TLS Fallback)
57

58
```java
59
import io.grpc.alts.ComputeEngineChannelBuilder;
60
import io.grpc.ManagedChannel;
61

62
// Automatically uses ALTS on GCP, TLS elsewhere
63
ManagedChannel channel = ComputeEngineChannelBuilder
64
    .forTarget("example-service:443")
65
    .build();
66
```
67

68
## Architecture
69

70
The gRPC ALTS library is organized around several key components:
71

72
- **Channel and Server Builders**: High-level builders (`AltsChannelBuilder`, `AltsServerBuilder`) that configure ALTS security automatically
73
- **Credential Classes**: Lower-level credential objects (`AltsChannelCredentials`, `AltsServerCredentials`) for custom integration
74
- **Context and Authorization**: Runtime context access (`AltsContext`, `AltsContextUtil`) for service identity verification
75
- **Fallback Mechanisms**: Compute Engine and Google Default builders that provide automatic fallback to TLS
76
- **Testing Support**: Special configurations for development and testing environments
77

78
## Capabilities
79

80
### Channel Builders
81

82
High-level builders for creating secure gRPC channels with ALTS authentication. These builders automatically configure the underlying security infrastructure.
83

84
```java { .api }
85
// Pure ALTS channel builder
86
public final class AltsChannelBuilder {
87
    public static AltsChannelBuilder forTarget(String target);
88
    public static AltsChannelBuilder forAddress(String name, int port);
89
    public AltsChannelBuilder addTargetServiceAccount(String targetServiceAccount);
90
    public ManagedChannel build();
91
}
92

93
// Compute Engine channel builder (ALTS with TLS fallback)
94
public final class ComputeEngineChannelBuilder {
95
    public static ComputeEngineChannelBuilder forTarget(String target);
96
    public static ComputeEngineChannelBuilder forAddress(String name, int port);
97
}
98

99
// Google Default channel builder (full Google Cloud auth stack)
100
public final class GoogleDefaultChannelBuilder {
101
    public static GoogleDefaultChannelBuilder forTarget(String target);
102
    public static GoogleDefaultChannelBuilder forAddress(String name, int port);
103
}
104
```
105

106
[Channel Builders](./channel-builders.md)
107

108
### Server Builders
109

110
High-level builders for creating secure gRPC servers with ALTS authentication.
111

112
```java { .api }
113
public final class AltsServerBuilder {
114
    public static AltsServerBuilder forPort(int port);
115
    public AltsServerBuilder enableUntrustedAltsForTesting();
116
    public AltsServerBuilder setHandshakerAddressForTesting(String handshakerAddress);
117
    public Server build();
118
}
119
```
120

121
[Server Builders](./server-builders.md)
122

123
### Channel Credentials
124

125
Lower-level credential objects for custom channel security configuration.
126

127
```java { .api }
128
public final class AltsChannelCredentials {
129
    public static ChannelCredentials create();
130
    public static Builder newBuilder();
131
}
132

133
public final class ComputeEngineChannelCredentials {
134
    public static ChannelCredentials create();
135
}
136

137
public final class GoogleDefaultChannelCredentials {
138
    public static ChannelCredentials create();
139
    public static Builder newBuilder(); // Since 1.43.0
140
}
141
```
142

143
[Channel Credentials](./channel-credentials.md)
144

145
### Server Credentials
146

147
Lower-level credential objects for custom server security configuration.
148

149
```java { .api }
150
public final class AltsServerCredentials {
151
    public static ServerCredentials create();
152
    public static Builder newBuilder();
153
}
154
```
155

156
[Server Credentials](./server-credentials.md)
157

158
### Context and Authorization
159

160
Runtime context access for service identity verification and authorization checks.
161

162
```java { .api }
163
public final class AltsContext {
164
    public SecurityLevel getSecurityLevel();
165
    public String getPeerServiceAccount();
166
    public String getLocalServiceAccount();
167
    
168
    public enum SecurityLevel {
169
        UNKNOWN, SECURITY_NONE, INTEGRITY_ONLY, INTEGRITY_AND_PRIVACY
170
    }
171
}
172

173
public final class AltsContextUtil {
174
    public static AltsContext createFrom(ServerCall<?, ?> call);
175
    public static AltsContext createFrom(ClientCall<?, ?> call);
176
    public static boolean check(ServerCall<?, ?> call);
177
    public static boolean check(ClientCall<?, ?> call);
178
}
179

180
public final class AuthorizationUtil {
181
    public static Status clientAuthorizationCheck(
182
        ServerCall<?, ?> call, 
183
        Collection<String> expectedServiceAccounts
184
    );
185
}
186
```
187

188
[Context and Authorization](./context-authorization.md)
189

190
## Types
191

192
```java { .api }
193
// Core gRPC interfaces used by ALTS
194
import io.grpc.ManagedChannel;
195
import io.grpc.Server;
196
import io.grpc.ChannelCredentials;
197
import io.grpc.ServerCredentials;
198
import io.grpc.ServerCall;
199
import io.grpc.ClientCall;
200
import io.grpc.Status;
201

202
// Java standard types
203
import java.util.Collection;
204
import java.util.concurrent.TimeUnit;
205
```
206

207
## API Maturity
208

209
Most ALTS APIs are marked as `@ExperimentalApi` and subject to change:
210
- Main builder and credential APIs are experimental (Issue #4151)
211
- Context and utility APIs are experimental (Issue #7864)
212

213
Production usage should account for potential API changes in future versions.