Endpoints with different authentication schemes

[sNiXx]

Is there any way to expose endpoints with different authentication schemes with Quarkus? For instance,

• /endpoint1: HTTP Basic authentication
• /endpoint2: server authentication (TLS)
• /endpoint3: client and server authentication (mTLS)

I would really appreciate any pointers on how this could be possible.

Thanks a lot 😃

[sberyozkin]

@sNiXx As far as endpoint 2 is concerned, there is no client authentication, so I'd touch on endpoint 1 and 3, see https://quarkus.io/guides/security-authentication-mechanisms#use-http-security-policy-to-enable-path-based-authentication.

For the mtls, the the mechanism name is mtls I believe.

If endpoints 2 is public then just make the policy permitted, that should do

[sNiXx]

@sberyozkin Thank you for the pointer, and you are right about endpoint 2 of course.

Another follow-up question: Is there any way to offer multiple authentication schemes for the same endpoint? So that, for instance, endpoint1 would accept HTTP Basic authentication as well as mTLS?

[sberyozkin]

@sNiXx For the MTLS and basic authentication it will just work out of the box because MTLS is done at the transport level, but in general, the inclusive authentication will support any combination where all the registered mechanisms must authenticate the request, see https://quarkus.io/guides/security-authentication-mechanisms#combining-authentication-mechanisms

[sNiXx]

Good to know! I guess I will have to tinker a little bit to find out how I could make use of inclusive authentication.

Thanks a lot, @sberyozkin!

[sberyozkin]

Np, thanks @sNiXx, give it a try please

[sNiXx]

@sberyozkin I have been looking into this a bit more and was wondering if my understanding is correct:

• proactive authentication enables authentication for all endpoints, so that any request providing credentials is authenticated and those requests that do not provide credentials are not authenticated (default: enabled)
• inclusive authentication means that all registered authentication mechanisms are required (e.g. Basic Auth AND mTLS) (default: disabled)
• it is not possible to combine path-based authentication mechanisms (e.g. Basic Auth OR mTLS) with annotations or HTTP Security Policy
• If both proactive and inclusive authentication are disabled, an endpoint only requires authentication if it is specified (e.g. via annotation)

Which leads me to my questions:

1. How would I go about securing the following ExampleResource to ensure that:
   • /endpoint1 requires no authentication
   • /endpoint2 requires either Basic Auth OR mTLS
   • /endpoint3 requires mTLS

@Path("ws")
public class ExampleResource {

    @Inject
    protected SecurityIdentity securityIdentity;

    @GET
    @Path("endpoint1")
    public Response endpoint1() {
        Log.debugv("isAnonymous: {0}", securityIdentity.isAnonymous());
        // handling code
        return Response.ok(responseBody).build();
    }

    @POST
    @Path("endpoint2")
    public Response endpoint2(String body) {
        // handling code
        return Response.ok(responseBody).build();
    }

    @POST
    @Path("endpoint3")
    public Response endpoint3(String body) {
        // handling code
        return Response.ok(responseBody).build();
    }
}

2. What would my configuration have to look like? Does something like this make sense?

    auth:
      permission:
        default:
          paths: /*
          policy: permit
        basic-or-mtls:
          paths: /endpoint2
          policy: authenticated
        mtls:
          paths: /endpoint3
          policy: authenticated
          auth-mechanism: mtls
      basic: false
      proactive: false
      inclusive: false

3. What does it mean to "register" an authentication mechanism? I saw that this was mentioned in the documentation, but not how this should be done.

I tried a few things, but it seems I am stuck or missing something. Thank you in advance for your insights - I saw that you were working on a few issues/merge requests regarding this topic :-)

[sberyozkin]

@sNiXx

proactive authentication enables authentication for all endpoints, so that any request providing credentials is authenticated and those requests that do not provide credentials are not authenticated (default: enabled)

I'd like to characterize it slightly differently: proactive authentication is about determining the moment when the authentication is performed. If it is on (default), the credentials are verified before it is known if the endpoint is public or secured. If it is disabled, it is performed only if a given request path requires an authentication

inclusive authentication means that all registered authentication mechanisms are required (e.g. Basic Auth AND mTLS) (default: disabled)

Yes, all of them are required to produce a verified security identity

it is not possible to combine path-based authentication mechanisms (e.g. Basic Auth OR mTLS) with annotations or HTTP Security Policy

This requires a more specific discussion, what use case do you have in mind ? When you put a mechanism annotation on some JAX-RS method or class, you enable a path based authentication... I believe you can also use policies alongside annotations.

If both proactive and inclusive authentication are disabled, an endpoint only requires authentication if it is specified (e.g. via annotation)

No, the inclusive authentication is just a composite authentication, so it does not disables or enables the authentication, it determines how the authentication must be done. Indeed, if the proactive authentication is disabled, the authentication is performed (and it can be an inclusive one) only if the annotation or policy requires it.

What does it mean to "register" an authentication mechanism?

Register applies to custom mechanisms, which one registers as a CDI ApplicationScoped / Singleton bean, others like Basic or OIDC, are registered by default, some of them may have to be explicitly enabled, mechanism specific docs should give all the info

How would I go about securing the following ExampleResource to ensure that:
/endpoint1 requires no authentication
/endpoint2 requires either Basic Auth OR mTLS
/endpoint3 requires mTLS

As far as endpoint2 requires either Basic Auth OR mTLS case is concerned, I don't think we can do it right now, neither at the HTTP policy nor the annotation level.

Can I ask you, are you just trying to understand how combining mechanisms works in different variations or is there some specific requirement behind such combinations ?

The reason I ask, we can consider supporting multiple mechanisms for a given path only case, for example, so that users can say auth-mechanism: mtls,basic, or use multiple mechanism annotations on a single method, but I'd like to avoid us investing time into it if there is no actual requirement behind such a case

[sberyozkin]

Though, either Basic Auth OR mTLS can easily be done if it is to be applied to all the application space

[sberyozkin]

@michalvavrik Thanks, I opened it to keep the track of it but indeed, the custom mechanism can certainly work

[sNiXx]

Thank you for the hints, I was working on this today and have come up with the following - still work in progress, but my tests with credentials in the application.properties file, seem to indicate it works.

However, whether I annotate my endpoint with @MtlsOrBasicAuthentication or @MTLSAuthentication, does not seem to make a difference. All requests with mTLS authentication seem to be going through my custom mechanism. Am I missing something?

Also, do you have any general remarks? I would like to add a few notes to the documentation to help anyone looking into this in the future.

MtlsOrBasicAuthentication

/**
 * Selects {@link MtlsOrBasicAuthenticationMechanism}.
 *
 * @see HttpAuthenticationMechanism for more information
 */
@HttpAuthenticationMechanism("mtls-basic")
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface MtlsOrBasicAuthentication {

    String AUTH_MECHANISM_SCHEME = "mtls-basic";

}

MtlsOrBasicAuthenticationMechanism

@Alternative
@Priority(1)
@ApplicationScoped
public class MtlsOrBasicAuthenticationMechanism implements HttpAuthenticationMechanism {

    @Inject
    BasicAuthenticationMechanism basic;

    @Inject
    MtlsAuthenticationMechanism mtls;

    @Override
    public Uni<SecurityIdentity> authenticate(RoutingContext context, IdentityProviderManager identityProviderManager) {
        return selectBetweenBasicAndMtls(context).authenticate(context, identityProviderManager);
    }

    @Override
    public Uni<ChallengeData> getChallenge(RoutingContext context) {
        return selectBetweenBasicAndMtls(context).getChallenge(context);
    }

    @Override
    public Set<Class<? extends AuthenticationRequest>> getCredentialTypes() {
        Set<Class<? extends AuthenticationRequest>> credentialTypes = new HashSet<>();
        credentialTypes.addAll(basic.getCredentialTypes());
        credentialTypes.addAll(mtls.getCredentialTypes());
        return credentialTypes;
    }

    @Override
    public Uni<HttpCredentialTransport> getCredentialTransport(RoutingContext context) {
        return selectBetweenBasicAndMtls(context).getCredentialTransport(context);
    }

    private HttpAuthenticationMechanism selectBetweenBasicAndMtls(RoutingContext context) {
        List<String> authHeaders = context.request().headers().getAll(HttpHeaderNames.AUTHORIZATION);
        if (!authHeaders.isEmpty()) {
            Log.debug("Attempting HTTP Basic authentication");
            return basic;
        } else {
            Log.debug("Attempting mTLS authentication");
            return mtls;
        }
    }
}

[michalvavrik]

Also, do you have any general remarks? I would like to add a few notes to the documentation to help anyone looking into this in the future.

The MtlsOrBasicAuthentication annotation can't work because only meta-annotations we supports is for @PermissionsAllowed It goes down to the indexing Quarkus performs during the build. It is not the same that you annotate @HttpAuthenticationMechanism("mtls-basic"). Now validation that would fail the build is not straighforward, because we do annotate things like @MTLSAuthentication simply to understand they are one-to-one, but it is definitely possible. I'd like the build fail in your case, I'll add it to my list.

All requests with mTLS authentication seem to be going through my custom mechanism. Am I missing something?

Your authentication mechanism has following annotation instances

@Alternative
@Priority(1)
@ApplicationScoped

so you got rid of every other authentication mechanism. it is only mechanism available.

However, whether I annotate my endpoint with @MtlsOrBasicAuthentication or @MTLSAuthentication, does not seem to make a difference.

if you have @MTLSAuthentication annotation applied and your mechanism returns basic and it is still applied, I'd like to see a reproduce. You didn't mention it explicitly, just saying everything else is expected juding by what you have described.

[sNiXx]

There is a lot of information in your response that I do not understand - I seem to have quite a few gaps in understanding about what is going on. I followed the Security Customization guide, as suggested by @sberyozkin and do not understand how what I am doing differs in any way?

While doing some more research, I saw that you recently updated the Authentication Mechanisms guide, referencing the Security Customization guide and mentioning that inclusive authentication now also supports a "lax" mode. So either should work when I would like to allow multiple authentication mechanisms?

In my tests, I observed the following: When annotating my endpoints with @MTLSAuthentication or @MtlsOrBasicAuthentication, the latter was always chosen. More interestingly, however, the authorization with Basic Authentication fails if the endpoint is only annotated with @MTLSAuthentication. Or put differently:

    @POST
    @Path("simpleenroll")
    @Consumes("application/pkcs10")
    @Produces("application/pkcs7-mime")
    @MtlsOrBasicAuthentication
    @Authenticated
    public Response simpleEnroll() {
	// handling code
    }

--> authentication is handled by my custom mechanism MtlsOrBasicAuthentication
--> request with mTLS Authentication succeeds
--> request with Basic Authentication succeeds

    @POST
    @Path("simpleenroll")
    @Consumes("application/pkcs10")
    @Produces("application/pkcs7-mime")
    @MTLSAuthentication
    @Authenticated
    public Response simpleEnroll() {
	// handling code
    }

--> authentication is handled by my custom mechanism MtlsOrBasicAuthentication
--> request with mTLS Authentication succeeds
--> request with Basic Authentication fails

[michalvavrik]

There is a lot of information in your response that I do not understand - I seem to have quite a few gaps in understanding about what is going on. I followed the Security Customization guide, as suggested by @sberyozkin and do not understand how what I am doing differs in any way?

Jakarta CDI specs is clear there, we cannot see mTLS authentication mechanism if only CDI bean of type the bean you define, that is MtlsOrBasicAuthenticationMechanism. Quarkus docs next to the example says:

Declaring the mechanism an alternative bean ensures this mechanism is used rather than OidcAuthenticationMechanism and JWTAuthMechanism.

Therefore it is always your mechanism that will be used.

placeholder for the rest of your responses

You basically say:

• mTLS authentication pass for the endpoint annotated with @MTLSAuthentication and `basic fails -> expected
• @MtlsOrBasicAuthentication is ignored and my MtlsOrBasicAuthenticationMechanism is used, also expected.

Here is documentation for the @HttpAuthenticationMechanism https://quarkus.io/guides/security-authentication-mechanisms#use-annotations-to-enable-path-based-authentication-for-jakarta-rest-endpoints and there is a list of supported annotations, the MtlsOrBasicAuthenticationMechanism or any mention of meta annotations is not there. I have already said we need to improve build-time validation and I'll probably do it this week.

Sorry, don't have more time, I am very busy ATM, but I have already documented your use case here https://quarkus.io/version/main/guides/security-authentication-mechanisms#use-inclusive-authentication-to-enable-path-based-authentication, please give it a try as we have tests that ensures it works. For example here #46183 I created tests with @MtlsBasic, so that we know it works. It is present in 3.19.x, but if you use 3.18.x, there are no modes so it will work as well.s

[michalvavrik]

For the mtls, the the mechanism name is mtls I believe.

It is X509 @sberyozkin , see

quarkus/extensions/vertx-http/runtime/src/main/java/io/quarkus/vertx/http/runtime/security/MtlsAuthenticationMechanism.java

Line 93 in 4fe180b

return Uni.createFrom().item(new HttpCredentialTransport(HttpCredentialTransport.Type.X509, "X509"));

I suppose we should really document this as many users won't know where to look.

[michalvavrik]

I want to politely say that I have a different opinion. If it was intended that inclusive=true enforces that all mechanisms provide identity, it means that it enforces authorization, because there will never be any anonymous identity. That means that if someone set quarkus.http.auth.inclusive=true with default setup (that is by default, proactive=true) every single incoming HTTP request would have to be authenticated. No anonymous identity could ever exist. The application will have no public endpoint.

[sberyozkin]

@michalvavrik Michal, there is only one thing I meant when I opened an initial PR that you reworked: all registered mechanisms must provide an identity.
I'd like to avoid now us trying to re-qualify what it really means...

if someone set quarkus.http.auth.inclusive=true with default setup (that is by default, proactive=true) every single incoming HTTP request would have to be authenticated. No anonymous identity could ever exist. The application will have no public endpoint.

I'm sorry, it is totally out of context, the inclusive authentication is about the registered mechanisms producing the identity, let's not bring the anonymous case into it

[sberyozkin]

@michalvavrik I'm not sure what this statement above is based upon. If the endpoint requires the authentication and the authentication is inclusive, then all registered mechanisms must verify it. What do you mean, no anonymous identity could ever exist, inclusive is about how the authentication has to be completed, the process stops when either the first mechanism that can produce the SecurityIdentity (default) does it, or when all of them produce it (inclusive).

OIDC and MTLS test confirms it I believe

[sberyozkin]

@michalvavrik Michal, Let's discuss it later, good night :-)

[michalvavrik]

I don't mind discussing it elsewhere, but I read your comments and I don't agree with them. Good night as well.

[michalvavrik]

it is not possible to combine path-based authentication mechanisms (e.g. Basic Auth OR mTLS) with annotations or HTTP Security Policy

No. If by annotations you mean standard security annotations like @RolesAllowed. Path-based authentication can be combined with anything if your endpoints are Jakarta REST endpoints and HTTP permission that selects mechanism (in case you are selecting it with configuration) you use JAXRS https://quarkus.io/guides/all-config#quarkus-vertx-http_quarkus-http-auth-permission-permissions-applies-to.

[michalvavrik]

If both proactive and inclusive authentication are disabled, an endpoint only requires authentication if it is specified (e.g. via annotation)

proactive and inclusive authentications are not about authorization, so authentication is required when you require it with annotations or HTTP permissions.

[michalvavrik]

No, the inclusive authentication is just a composite authentication, so it does not disables or enables the authentication, it determines how the authentication must be done. Indeed, if the proactive authentication is disabled, the authentication is performed (and it can be an inclusive one) only if the annotation or policy requires it.

that's better, I can sign under that one.