Add Athenz integration module by ikhoon · Pull Request #6321 · line/armeria

ikhoon · 2025-07-23T09:09:01Z

Motivation:

This PR aims to provide an integration layer for Athenz so that users can easily obtain Athenz tokens and validate them
by decorating clients or services and annotating required Athenz roles declaratively.

Modifications:

Client side
- ZtsBaseClient provides common functionality such as TlsKeyPair management and Athenz client configurations.
  - Users should create ZtsBaseClient first to create AthenzClient and AthenzService.
  - ZtsBaseClient is designed as a resource, and it needs to be closed since Armeria decorators are not closable.
  - The lifecycle of Athenz ClientFactory is delegated to ZtsBaseClient
- AccessTokenClient acquires OAuth 2.0 token from the/oauth2/token endpoint.
  - The cached tokens are automatically refreshed before expiration.
  - Athenz uses mTLS as the authorization layer, and the client credentials of OAuth 2.0 are unnecessary.
    - This method does not conform to the official OAuth 2.0 specification.
- RoleTokenClient obtains Athenz role tokens from the /domain/{domainName}/token?role=<roleName> endpoint.
  - It has a similar refreshing logic to AccessTokenClient.
- AthenzClient is a public decorator that delegates to AccessTokenClient or RoleTokenClient depending on the configuration.
Server side
- AthenzPolicyLoader loads Athenz domain policies from ZTS servers, just like the zpu CLI does.
  - The external zpu cronjob to fetch policies is no longer necessary.
  - Both JWS policy data and signed policy data are supported.
- AthenzPolicyHandler parses the policy data and verifies it with public keys.
- MinifiedAuthZpeClient is forked from AuthZpeClient and modified to seamlessly integrate with Armeria.
  - MinifiedAuthZpeClient is responsible for token validation.
  - Reviewers may skip a detailed review of this class.
- AthenzService is a public decorator to check access permission for projected resources.
- RequiresAthenzRole allows users to specify an Athenz role using annotations.
  - AthenzServiceDecoratorFactory should be injected via DependencyInjector to use RequiresAthenzRole

Result:

You can now use the Athenz module to easily obtain Athenz tokens and validate them.
Closes Add Athenz module #6050
Server example:

class MyService {
  // 1. Decorate the method with `RequiresAthenzRole` to check Athenz role.
  @RequiresAthenzRole(resource = "user", action = "get")
  @ProducesJson
  @Get("/user")
  public CompletableFuture<User> getUser() {
     ...
  }
}

// 2. Create a `ZtsBaseClient` and `AthenzServiceDecoratorFactory` to use Athenz.
ZtsBaseClient ztsBaseClient =
  ZtsBaseClient
    .builder("https://athenz.example.com:4443/zts/v1")
    .keyPair("/var/lib/athenz/service.key.pem", "/var/lib/athenz/service.cert.pem")
    .build();
final AthenzServiceDecoratorFactory athenzDecoratorFactory =
  AthenzServiceDecoratorFactory
    .builder(ztsBaseClient)
    .policyConfig(new AthenzPolicyConfig("my-domain"))
    .build();

// 3. Create a `DependencyInjector` with the `AthenzServiceDecoratorFactory`
//    and set it to the server. `AthenzServiceDecoratorFactory` is required to
//    create the `RequiresAthenzRole` decorator.
final DependencyInjector di =
  DependencyInjector.ofSingletons(athenzDecoratorFactory)
                    .orElse(DependencyInjector.ofReflective());
serverBuilder.dependencyInjector(di, true);

Client example:

ZtsBaseClient ztsBaseClient =
  ZtsBaseClient
    .builder("https://athenz.example.com:4443/zts/v1")
    .keyPair("/var/lib/athenz/service.key.pem", "/var/lib/athenz/service.cert.pem")
    .build();

WebClient
  .builder()
  .decorator(AthenzClient.newDecorator(ztsBaseClient, "my-domain",
                                       TokenType.ROLE_TOKEN)
  ...
  .build();

TBU

github-actions · 2025-07-23T09:26:44Z

🔍 Build Scan® (commit: `909b373`)

Job name	Status	Build Scan®
build-ubicloud-standard-16-jdk-8	✅	https://ge.armeria.dev/s/4mgp5pi253z5a
build-ubicloud-standard-16-jdk-21-snapshot-blockhound	✅	https://ge.armeria.dev/s/ehxiaxd2nws32
build-ubicloud-standard-16-jdk-17-min-java-17-coverage	✅	https://ge.armeria.dev/s/5bbd7kokhsdgy
build-ubicloud-standard-16-jdk-17-min-java-11	✅	https://ge.armeria.dev/s/mczlofejtupz6
build-ubicloud-standard-16-jdk-17-leak	✅	https://ge.armeria.dev/s/7a2hujyomehvc
build-ubicloud-standard-16-jdk-11	✅	https://ge.armeria.dev/s/h76tvsgt5rhyu
build-macos-latest-jdk-21	❌ (failure)	https://ge.armeria.dev/s/e7la5ssfg22hu

…sion when shading

codecov · 2025-07-26T05:12:30Z

Codecov Report

❌ Patch coverage is 60.97308% with 377 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.43%. Comparing base (8150425) to head (909b373).
⚠️ Report is 143 commits behind head on main.

Files with missing lines	Patch %	Lines
...p/armeria/server/athenz/MinifiedAuthZpeClient.java	44.60%	113 Missing and 41 partials ⚠️
...orp/armeria/server/athenz/AthenzPolicyHandler.java	59.45%	31 Missing and 14 partials ⚠️
...rp/armeria/client/athenz/ZtsBaseClientBuilder.java	29.62%	36 Missing and 2 partials ⚠️
...armeria/server/athenz/AthenzPublicKeyProvider.java	72.36%	20 Missing and 1 partial ⚠️
.../linecorp/armeria/client/athenz/ZtsBaseClient.java	67.21%	16 Missing and 4 partials ⚠️
...corp/armeria/server/athenz/AthenzPolicyConfig.java	50.00%	14 Missing and 2 partials ⚠️
...necorp/armeria/server/athenz/AthenzAssertions.java	39.13%	14 Missing ⚠️
...rp/armeria/server/athenz/AthenzServiceBuilder.java	57.69%	7 Missing and 4 partials ⚠️
...inecorp/armeria/client/athenz/RoleTokenClient.java	78.94%	3 Missing and 5 partials ⚠️
...ecorp/armeria/client/athenz/AccessTokenClient.java	80.55%	3 Missing and 4 partials ⚠️
... and 11 more

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #6321      +/-   ##
============================================
- Coverage     74.46%   74.43%   -0.03%     
- Complexity    22234    22967     +733     
============================================
  Files          1963     2061      +98     
  Lines         82437    85695    +3258     
  Branches      10764    11179     +415     
============================================
+ Hits          61385    63791    +2406     
- Misses        15918    16531     +613     
- Partials       5134     5373     +239

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

minwoox

Left some nits. 😉

minwoox

👍 👍 👍

jrhee17

I understood functionally this module is equivalent to ZPE lib and the ZTS lib but with an Armeria flavor.

jrhee17 · 2025-08-04T00:59:30Z

+     * @param tokenType the type of Athenz token to obtain
+     */
+    public static Function<HttpClient, AthenzClient> newDecorator(ZtsBaseClient ztsBaseClient,
+                                                                  String domainName, TokenType tokenType) {


Question) I'm not sure of the environment, but is TokenType.ROLE_TOKEN often used? I'm wondering if TokenType.ACCESS_TOKEN should be the default

Some LY internal servers only support ROLE_TOKEN type. So I wasn't sure if ACCESS_TOKEN could be a sensible default.

jrhee17 · 2025-08-04T01:20:05Z

+ * <pre>{@code
+ * class MyService {
+ *   // 1. Decorate the method with `RequiresAthenzRole` to check Athenz role.
+ *   @RequiresAthenzRole(resource = "user", action = "get")


Note) I understood this is an AND condition. i.e.) If users want to allow either both ACCESS_TOKEN and ROLE_TOKEN, they can't do it using the annotations.

If tokenType is unset, ACCESS_TOKEN and ROLE_TOKEN are allowed.

armeria/athenz/src/main/java/com/linecorp/armeria/server/athenz/RequiresAthenzRole.java

Line 84 in cdfbe39

TokenType[] tokenType() default { TokenType.ROLE_TOKEN, TokenType.ACCESS_TOKEN };

jrhee17 · 2025-08-04T02:15:04Z

+    private AthenzPolicyConfig policyConfig;
+    private int maxTokenCacheSize = MAX_TOKEN_CACHE_SIZE;
+
+    AbstractAthenzServiceBuilder(ZtsBaseClient ztsBaseClient) {


The external zpu cronjob to fetch policies is no longer necessary.

I actually understood the zpu cronjob is still necessary since AthenzService still needs to use the credentials created/rotated by the zpu when connecting to zts. Let me know if I misunderstood.

ZPU fetches and refreshes Athenz policy files. IIUC, it is not related to credentials. Generally, creating Service credentials is delegated to Athenz SIA, which is still necessary.
https://github.com/AthenZ/athenz/blob/master/docs/system_view.md#sia-service-identity-agent-provider:~:text=for%20issuing%20tokens.-,SIA%20(Service%20Identity%20Agent,can%20validate%20the%20signature.,-ZPE%20(AuthZ%20Policy

I see. I understood that service providers will need to install either an SIA and use this module, or use ZPU with ZPE

This Athenz module does not support creating Service credentials, so an external system such as SIA is still used for mTLS.

I see. Then I understood that the ZPU internally uses SIA to acquire initial credentials for communication with the ZMS/ZTS then.

Motivation: Athenz SIA refreshes the certs every 24 hours by default. https://github.com/AthenZ/k8s-athenz-identity#configuration In order to comply with the specification, `TlsProvider` should detect the updated certs and automatically refresh them. Additionally, there were similar requests from Armeria users. #6054 Modifications: - Add `RefreshingTlsProvider` that periodically refreshes the given `TlsKeyPair` provider. - Currently, only one `TlsKeyPair` is supported for `RefreshingTlsProvider` - TODO) Integrate `MappedTlsProvider` with `RefreshingTlsProvider` to build a more flexible `TlsProvider` using `TlsProviderBuilder` - Expose `ReflectiveDependencyInjector` via public API via `DependencyInjector.ofReflective()` - This is unrelated to this PR, but added to minimize conflicts when merging the main branch into #6321 Result: You can now periodically refresh `TlsKeyPair` when using `TlsProvider.ofSheduled()` ```java File keyFile = ...; Fie certFile = ...; TlsProvider.ofScheduled(() -> { return TlsKeyPair.of(keyFile, certFile); }, Duration.ofHours(1)); ```

Add Athenz integration module

cdfbe39

TBU

ikhoon added this to the 1.33.0 milestone Jul 23, 2025

ikhoon added the new feature label Jul 23, 2025

ikhoon force-pushed the athenz branch from 58d5cbd to 9c0898b Compare July 24, 2025 16:14

Exclude MRJARs files that are not compatible with the target Java ver…

58f37b0

…sion when shading

ikhoon force-pushed the athenz branch from 9c0898b to 58f37b0 Compare July 24, 2025 16:16

ikhoon added 2 commits July 25, 2025 01:36

fix javadoc compile errors

144fdfb

use java11

9d4ec15

ikhoon force-pushed the athenz branch 2 times, most recently from 5af1ac7 to 322bb7a Compare July 25, 2025 10:43

ikhoon added 2 commits July 25, 2025 20:11

set docker network

14c9c69

no mount log directories

da2cbf6

ikhoon force-pushed the athenz branch from a881822 to da2cbf6 Compare July 25, 2025 11:11

ikhoon added 4 commits July 25, 2025 20:15

use local compose

a3e013c

change zt_store location

aab4934

detect docker correctly

92fced3

lint

743ffcc

ikhoon added 6 commits July 26, 2025 15:57

launch docker compose per test suite

46f936f

add name for asyncloader and add test case for force reload

ec87d91

add name to test

aeecb50

avoid possible context leak

8ad7318

fix

4d519f7

Merge branch 'main' into athenz

75e8156

ikhoon mentioned this pull request Jul 28, 2025

Implement TlsProvider for periodic key pair refreshing #6331

Merged

Merge branch 'main' into athenz

357ad7b

ikhoon marked this pull request as ready for review July 29, 2025 14:49

ikhoon requested review from jrhee17 and minwoox as code owners July 29, 2025 14:49

ikhoon requested a review from trustin as a code owner July 29, 2025 14:49

update javadoc

2bb7e27

minwoox reviewed Jul 31, 2025

View reviewed changes

ikhoon added 2 commits July 31, 2025 19:37

Address comments by @minwoox

98ff748

revert javadoc

fb2fa8a

minwoox approved these changes Aug 1, 2025

View reviewed changes

jrhee17 approved these changes Aug 4, 2025

View reviewed changes

ikhoon and others added 2 commits August 4, 2025 13:16

address comments by @jrhee17

875b3d9

Merge branch 'main' into athenz

d597b5b

ikhoon and others added 3 commits August 4, 2025 14:57

Merge branch 'main' into athenz

23a9f80

Merge branch 'athenz' of github.com:ikhoon/armeria into athenz

c9bbe59

Merge branch 'main' into athenz

909b373

ikhoon merged commit 62a2da2 into line:main Aug 5, 2025
14 of 16 checks passed

ikhoon deleted the athenz branch August 5, 2025 01:19

Uh oh!

Conversation

ikhoon commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Build Scan® (commit: 909b373)

Uh oh!

codecov Bot commented Jul 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

minwoox left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

minwoox left a comment

Choose a reason for hiding this comment

Uh oh!

jrhee17 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrhee17 Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

ikhoon Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrhee17 Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ikhoon Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

jrhee17 Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

ikhoon Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

jrhee17 Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ikhoon Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

jrhee17 Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ikhoon commented Jul 23, 2025 •

edited

Loading

github-actions Bot commented Jul 23, 2025 •

edited

Loading

🔍 Build Scan® (commit: `909b373`)

codecov Bot commented Jul 26, 2025 •

edited

Loading

ikhoon Aug 4, 2025 •

edited

Loading

jrhee17 Aug 4, 2025 •

edited

Loading

jrhee17 Aug 4, 2025 •

edited

Loading