0
# Authentication Utilities
1

2
The authentication utilities provide helper methods for constructing AWS authentication schemes in endpoint rules, supporting SigV4, SigV4a, and related authentication mechanisms.
3

4
## Capabilities
5

6
### EndpointAuthUtils Class
7

8
Utilities for constructing and validating AWS-specific authentication components for rule-sets.
9

10
```java { .api }
11
/**
12
 * Utilities for constructing and validating AWS-specific authentication components for rule-sets.
13
 */
14
public final class EndpointAuthUtils {
15
    /**
16
     * Adds SigV4 authentication to the provided endpoint builder
17
     * @param builder The endpoint builder to augment
18
     * @param signingRegion The signing region to use when signing
19
     * @param signingService The name of the service to sign with
20
     * @return The updated endpoint builder
21
     */
22
    public static Endpoint.Builder sigv4(Endpoint.Builder builder, Literal signingRegion, Literal signingService);
23
    
24
    /**
25
     * Adds SigV4a authentication to the provided endpoint builder
26
     * @param builder The endpoint builder to augment  
27
     * @param signingRegionSet The set of signing regions to use when signing
28
     * @param signingService The name of the service to sign with
29
     * @return The updated endpoint builder
30
     */
31
    public static Endpoint.Builder sigv4a(Endpoint.Builder builder, List<Literal> signingRegionSet, Literal signingService);
32
    
33
    /**
34
     * Returns if a given auth scheme is equivalent to aws.auth#sigv4
35
     * @param authScheme Name of the auth scheme
36
     * @return Whether the auth scheme is equivalent to aws.auth#sigv4
37
     */
38
    public static boolean isSigV4EquivalentAuthScheme(String authScheme);
39
    
40
    /**
41
     * Returns if a given auth scheme is equivalent to aws.auth#sigv4a
42
     * @param authScheme Name of the auth scheme
43
     * @return Whether the auth scheme is equivalent to aws.auth#sigv4a
44
     */
45
    public static boolean isSigV4AEquivalentAuthScheme(String authScheme);
46
}
47
```
48

49
### Authentication Scheme Validators
50

51
The package provides validators for AWS authentication schemes used in endpoint rules.
52

53
```java { .api }
54
/**
55
 * Validator for SigV4 authentication schemes
56
 */
57
public static final class SigV4SchemeValidator implements AuthSchemeValidator {
58
    /**
59
     * Tests if this validator applies to the given authentication scheme name
60
     * @param name The authentication scheme name
61
     * @return True if this validator should be used for the scheme
62
     */
63
    public boolean test(String name);
64
    
65
    /**
66
     * Validates SigV4 authentication configuration
67
     * @param authScheme The authentication scheme parameter set
68
     * @param sourceLocation The location of the authorization scheme
69
     * @param emitter Function to emit validation events for failures
70
     * @return List of validation events (errors/warnings)
71
     */
72
    public List<ValidationEvent> validateScheme(
73
        Map<Identifier, Literal> authScheme,
74
        FromSourceLocation sourceLocation,
75
        BiFunction<FromSourceLocation, String, ValidationEvent> emitter);
76
}
77

78
/**
79
 * Validator for SigV4a authentication schemes  
80
 */
81
public static final class SigV4aSchemeValidator implements AuthSchemeValidator {
82
    /**
83
     * Tests if this validator applies to the given authentication scheme name
84
     * @param name The authentication scheme name
85
     * @return True if this validator should be used for the scheme
86
     */
87
    public boolean test(String name);
88
    
89
    /**
90
     * Validates SigV4a authentication configuration
91
     * @param authScheme The authentication scheme parameter set
92
     * @param sourceLocation The location of the authorization scheme
93
     * @param emitter Function to emit validation events for failures
94
     * @return List of validation events (errors/warnings)
95
     */
96
    public List<ValidationEvent> validateScheme(
97
        Map<Identifier, Literal> authScheme,
98
        FromSourceLocation sourceLocation,
99
        BiFunction<FromSourceLocation, String, ValidationEvent> emitter);
100
}
101

102
/**
103
 * Validator for SigV4 sub-scheme authentication (e.g., sigv4-s3express)
104
 */
105
public static final class SigV4SubSchemeValidator implements AuthSchemeValidator {
106
    /**
107
     * Tests if this validator applies to the given authentication scheme name
108
     * @param name The authentication scheme name
109
     * @return True if this validator should be used for the scheme
110
     */
111
    public boolean test(String name);
112
    
113
    /**
114
     * Validates SigV4 sub-scheme authentication configuration
115
     * @param authScheme The authentication scheme parameter set
116
     * @param sourceLocation The location of the authorization scheme
117
     * @param emitter Function to emit validation events for failures
118
     * @return List of validation events (errors/warnings)
119
     */
120
    public List<ValidationEvent> validateScheme(
121
        Map<Identifier, Literal> authScheme,
122
        FromSourceLocation sourceLocation,
123
        BiFunction<FromSourceLocation, String, ValidationEvent> emitter);
124
}
125

126
/**
127
 * Validator for beta authentication schemes
128
 */
129
public static final class BetaSchemeValidator implements AuthSchemeValidator {
130
    /**
131
     * Tests if this validator applies to the given authentication scheme name
132
     * @param name The authentication scheme name
133
     * @return True if this validator should be used for the scheme
134
     */
135
    public boolean test(String name);
136
    
137
    /**
138
     * Validates beta authentication scheme configuration
139
     * @param authScheme The authentication scheme parameter set
140
     * @param sourceLocation The location of the authorization scheme
141
     * @param emitter Function to emit validation events for failures
142
     * @return List of validation events (errors/warnings)
143
     */
144
    public List<ValidationEvent> validateScheme(
145
        Map<Identifier, Literal> authScheme,
146
        FromSourceLocation sourceLocation,
147
        BiFunction<FromSourceLocation, String, ValidationEvent> emitter);
148
}
149
```
150

151
**Usage Examples:**
152

153
```java
154
import software.amazon.smithy.rulesengine.aws.language.functions.EndpointAuthUtils;
155
import software.amazon.smithy.rulesengine.language.Endpoint;
156
import software.amazon.smithy.rulesengine.language.syntax.expressions.literal.Literal;
157

158
// Build an endpoint with SigV4 authentication
159
Endpoint.Builder endpointBuilder = Endpoint.builder()
160
    .url("https://service.us-east-1.amazonaws.com");
161

162
// Add SigV4 authentication
163
Endpoint endpoint = EndpointAuthUtils.sigv4(
164
    endpointBuilder,
165
    Literal.of("us-east-1"),    // signing region
166
    Literal.of("service-name")   // signing service
167
).build();
168

169
// Build an endpoint with SigV4a authentication (multi-region)
170
List<Literal> regionSet = Arrays.asList(
171
    Literal.of("us-east-1"),
172
    Literal.of("us-west-2")
173
);
174

175
Endpoint sigv4aEndpoint = EndpointAuthUtils.sigv4a(
176
    Endpoint.builder().url("https://global-service.amazonaws.com"),
177
    regionSet,                   // signing region set
178
    Literal.of("global-service") // signing service
179
).build();
180

181
// Check if an auth scheme is SigV4 equivalent
182
boolean isSigV4 = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4");
183
boolean isSigV4Custom = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4-custom");
184
boolean isNotSigV4 = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4a");
185
```
186

187
## Authentication Schemes
188

189
### SigV4 Authentication
190

191
AWS Signature Version 4 (SigV4) is the standard signing process for AWS API requests.
192

193
#### Configuration Properties:
194
- **signingName**: The service name for signing (e.g., "s3", "ec2")
195
- **signingRegion**: The AWS region for signing (e.g., "us-east-1")
196

197
```java
198
// SigV4 endpoint configuration
199
Map<String, Object> sigv4Config = Map.of(
200
    "signingName", "s3",
201
    "signingRegion", "us-east-1"
202
);
203
```
204

205
### SigV4a Authentication  
206

207
AWS Signature Version 4a (SigV4a) supports multi-region signing for global services.
208

209
#### Configuration Properties:
210
- **signingName**: The service name for signing
211
- **signingRegionSet**: Set of regions where the signature is valid
212

213
```java
214
// SigV4a endpoint configuration
215
Map<String, Object> sigv4aConfig = Map.of(
216
    "signingName", "global-service",
217
    "signingRegionSet", Arrays.asList("us-east-1", "us-west-2", "eu-west-1")
218
);
219
```
220

221
### SigV4 Sub-schemes
222

223
Special variants of SigV4 for specific services or use cases:
224

225
- **sigv4-s3express**: Optimized signing for S3 Express One Zone
226
- **sigv4-custom**: Custom signing variants
227

228
```java
229
// Check for SigV4 sub-schemes
230
boolean isS3Express = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4-s3express");
231
boolean isCustomSigV4 = EndpointAuthUtils.isSigV4EquivalentAuthScheme("sigv4-custom");
232
```
233

234
## Authentication Validation
235

236
### Validation Rules
237

238
The validators enforce proper authentication configuration:
239

240
1. **Required Properties**: Signing name and region/region set must be specified
241
2. **Type Validation**: Properties must be correct types (string, array)
242
3. **Value Validation**: Regions must be valid AWS regions
243
4. **Scheme Compatibility**: Auth scheme must match endpoint configuration
244

245
### Common Validation Errors
246

247
```java
248
// Missing signing region
249
ValidationEvent error1 = ValidationEvent.builder()
250
    .severity(Severity.ERROR)
251
    .message("SigV4 authentication requires signingRegion property")
252
    .build();
253

254
// Invalid region format
255
ValidationEvent error2 = ValidationEvent.builder()
256
    .severity(Severity.ERROR) 
257
    .message("Invalid AWS region format: 'invalid-region'")
258
    .build();
259

260
// Empty signing region set for SigV4a
261
ValidationEvent error3 = ValidationEvent.builder()
262
    .severity(Severity.ERROR)
263
    .message("SigV4a authentication requires non-empty signingRegionSet")
264
    .build();
265
```
266

267
## Integration with Built-ins
268

269
Authentication utilities work with AWS built-in parameters:
270

271
```java
272
// Authentication-related built-ins
273
AwsBuiltIns.CREDENTIAL_SCOPE        // Credential scoping
274
AwsBuiltIns.ACCOUNT_ID              // Account-based signing
275
AwsBuiltIns.ACCOUNT_ID_ENDPOINT_MODE // Account endpoint mode
276
```
277

278
## Best Practices
279

280
### SigV4 Usage
281
```java
282
// Standard SigV4 for regional services
283
EndpointAuthUtils.sigv4(
284
    builder,
285
    Literal.of("${Region}"),      // Use region parameter
286
    Literal.of("service-name")    // Service-specific signing name
287
);
288
```
289

290
### SigV4a Usage
291
```java
292
// SigV4a for global/multi-region services
293
EndpointAuthUtils.sigv4a(
294
    builder, 
295
    Arrays.asList(
296
        Literal.of("*")           // All regions
297
    ),
298
    Literal.of("global-service")
299
);
300
```
301

302
### Scheme Detection
303
```java
304
// Robust scheme detection
305
if (EndpointAuthUtils.isSigV4EquivalentAuthScheme(schemeName)) {
306
    // Handle as SigV4 (including sub-schemes)
307
} else if (EndpointAuthUtils.isSigV4AEquivalentAuthScheme(schemeName)) {
308
    // Handle as SigV4a
309
} else {
310
    // Handle other authentication schemes
311
}
312
```