Missing documentation for HTTPS with 2way TLS (aka mutual TLS, aka client cert auth)

[Ladicek]

Describe the bug
I'm trying to use client certificate authentication with Quarkus, and I didn't find documentation for it. In fact, I didn't find documentation for 2 things:

1. How to enable client cert auth. Clearly the configuration properties are there (trust store, client auth), but that's all. I'd expect this to be described in the HTTP guide.

   Most likely, the request for documentation from the original mutual TLS pull request has never materialized.

2. How to authenticate users based on the client certificate (and assign them roles). I've briefly looked around in Quarkus and it seems this isn't even possible. Is that true? (I certainly hope not!)

   Please let me know if this is really missing, so I can create a feature request.

   In any case, I'd expect documentation for that in the HTTP guide and also the security guide.

[Ladicek]

I don't know who's responsible here, so I'll wildly guess some people that might know who to add :-) CC @sberyozkin @stuartwdouglas

[stuartwdouglas]

@pedroigor can I leave this with you? It is possible to do this with keycloak at the moment but we need to document how.

[pedroigor]

Sure. I'm going to also check how Elytron can help here without forcing users to have an external authentication service.

[pedroigor]

@stuartwdouglas @Ladicek Please, let me know what you think
#8929.

[pedroigor]

@Ladicek Regarding RBAC. You could use a https://github.com/quarkusio/quarkus/blob/master/extensions/elytron-security-jdbc/deployment/src/test/java/io/quarkus/elytron/security/jdbc/CustomRoleDecoder.java.

Another option is to use an IdP (e.g.: Keycloak [1]), manage roles there, and use quarkus-oidc extension in your application.

[1] https://www.keycloak.org/docs/6.0/server_admin/#adding-x-509-client-certificate-authentication-to-a-browser-flow

[pedroigor]

@stuartwdouglas I started to integrate Vert.X mTLS into Quarkus security layer.

In addition to a mechanism to obtain the authenticated peer, I also need an identity provider so that we can actually build the identity from the peer's certificate.

A generic implementation of an identity provider would basically build a security identity using the certificate. I understand that users can always modify security identity by providing their own security identity augmentor. So that would help if users need to map roles or even change the principal.

Do you agree about that? Is that expected as an initial implementation?

In addition to that, I think we can provide more configuration options in order to determine how to extract the subject from certificates. For instance, obtain from Subject DN, SAN (e.g.: email), using regex, etc. Would that be part of this initial scope?

[pedroigor]

@stuartwdouglas https://github.com/pedroigor/quarkus/tree/issue-8508-mtls.

Please, let me know what you think.

There are some points like:

• In quarkus-security we have a TrustedAuthenticationRequest. It expects a String as a principal. Can't we change to use a Principal instead? Or is it fine to just create a specific one that expects a Principal?

• Regarding the IdentityProvider. Shall we have a built-in TrustedPrincipalProvider? So that users don't need to create their own to just create a security identity from an X509 principal?

• Regarding the configuration. Could we just decide whether or not mTLS authentication should happen based on the quarkus.http.ssl.client-auth=REQUIRED|REQUEST? I've created a specific property just like basic and form. But not sure.

• Add the peer certificate as a credential into the security identity.

[stuartwdouglas]

IMHO It makes more sense to have CertificateAuthenticationRequest as a seperate type, as I am not 100% sure if TrustedAuthenticationRequest is a great design anyway. The idea is to allow an already authenticated user to be loaded from a store, but it has some drawbacks.

I think we should maybe provide an @DefaultBean IdentityProvider, so a user can easily override it. IMHO this is likely to be simpler and more flexible than trying to provide lots of config options.

I think this should just be automatic based on the value of quarkus.http.ssl.client-auth

The peer certificate should definitely be a credential in the identity.

[pedroigor]

@stuartwdouglas Except for the @DefaultBean, everything is OK.

Do you mean having this default bean specific for certificates or a more generic identity provider implementation?