Support External IDs as subject names in ZTS user certificate requests

[ctyano]

Problem

PostUserCertificateRequest currently assumes that the requested user certificate subject is an Athenz user principal under the configured user domain, for example user.joe. This prevents ZTS from issuing a user certificate when the subject CN is an External ID such as email:ext.joe@athenz.io.

This is useful for deployments where the user identity is established by an external IdP and represented in Athenz policy data using the existing External ID syntax.

Proposal

Allow PostUserCertificateRequest to accept External IDs in the request name and CSR subject CN, for example:

• email:ext.joe@athenz.io

For normal Athenz user principals, the existing behavior remains unchanged:

• user.joe is still validated as an Athenz user principal.
• The user. prefix is still stripped before calling the configured user certificate provider.

For External IDs:

• ZTS validates that the subject uses the External ID separator format.
• The full External ID is preserved when validating the CSR and when passing the request to the configured user certificate provider.
• The user certificate provider accepts the External ID when the IdP token subject or configured username claim matches it.

Justification

This change does not make Athenz responsible for user authentication. The actual user authentication remains delegated to the configured external IdP and the user certificate provider.
ZTS only validates that the requested certificate subject matches the CSR and that the provider confirms the attested identity.

This also does not redefine External IDs as ordinary Athenz Principals. External IDs remain conceptually separate from Athenz user/service principals. The change only allows an External ID, already supported as an identity reference in Athenz policy concepts, to be used as the subject identifier for the user certificate issuance flow.

Without this support, deployments that intentionally spec user authentication outside of Athenz cannot issue user certificates for externally authenticated identities unless they map those identities into synthetic user.* principals. Preserving the External ID avoids that lossy mapping and keeps the certificate subject aligned with the identity asserted by the external IdP.

Scope

This issue is limited to user certificate issuance through PostUserCertificateRequest.

It does not change:

• normal user.* certificate issuance behavior
• role or service certificate issuance
• how Athenz authenticates users
• the general conceptual distinction between Athenz Principals and External IDs

Acceptance Criteria

• PostUserCertificateRequest can issue a certificate when request name and CSR CN are email:ext.joe@athenz.io.
• Existing user.joe behavior remains unchanged.
• Invalid External ID-like values are rejected.
• Provider token subject / username claim validation supports the full External ID.
• Unit tests cover both ZTS request validation and user certificate provider subject matching.

[havetisyan]

@ctyano not sure if I agree with this proposal. The user cert endpoint is specific to user principals recognized by ZTS. They're defined and understood as human users and registered in the user domain. Removing that check just opens up the api to now sure what. There is no guarantee that email:ext.joe@athenz.io is a user, service, or some other identity and handling that request through user cert request endpoint is not correct

What is your use case - looks to me you're extending the ZTS to issue certificates to any identity even if it's not a principal defined within Athenz. if that's your goal, if these are external users, why are we getting certificates issued by Athenz? Shouldn't they have their own identities and you'll just have an Authority defined in ZTS to authenticate them instead of issuing certificates?

[ctyano]

@havetisyan Thank you for your feedback.

As you pointed out, this is not a feature that must exclusively be implemented by Athenz, and alternative approaches are certainly possible.

The rationale behind this feature is that many existing IdPs do not support issuing user-identifiable X.509 certificates. I felt that being able to distribute X.509-based identities through Athenz would bring new value to the ecosystem.

Since Athenz already issues X.509 certificates for service accounts, adding full compatibility for user accounts would be a highly practical and useful capability. While I agree it is not a strictly exclusive requirement for Athenz, I hope you will consider accepting this feature for its overall utility.

While I still believe this is a necessary feature for our organization, I respect your final decision. If you feel it does not align with the project's direction, please let me know, and I will proceed to close this issue and PR.

[havetisyan]

@ctyano if you want to add a feature to allow external members to get identity certificates, then you should define a separate endpoint and not overload the user certificate endpoint since as I mentioned in my original comment there is no way to guarantee that email:ext.{email-address} is an actual user or not. The user cert endpoint specifically tied to the user authority defined in athenz and there are already a well understanding that these are human users in your corporate identity system.

So if you want, define a new endpoint something like postExtMemberCertificateRequest and implement the logic within that endpoint where it can enforce that which external members can have certs (e.g. if we have email:ext.{email-address} and hosts:ext.{hostname} then we can somehow configure that email domain is the only one authorized for certs, etc) and additional logic reserved for external members only.

[ctyano]

@havetisyan Thanks for the clarification. I agree that overloading /usercert changes the semantics of an endpoint that is tied to the configured user authority.

I updated the PR to keep /usercert restricted to active user principals and added a separate /extmembercert endpoint for external members. The new endpoint validates the ExternalMemberName format and only allows external member domains explicitly configured via athenz.zts.external_member_cert_allowed_domains, so external member certificate issuance is opt-in and no longer broadens the existing user certificate endpoint.

I also updated the RDL/generated server and Java client stubs, tests, and the config/design documentation.