doc: Custom binding of authenticated user

[sdelamo]

Close: #1430

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication

[jeremyg484]

While I think showing this particular example is useful in its own right, I don't really think it addresses the specific use case from #1430 wherein they are fully replacing the default Authentication object such that a call to request.getUserPrincipal(AuthenticationWithEmail.class) would be expected to work.

To address that case, I think we'd want to also show that it's possible to just extend AbstractPrincipalArgumentBinder as they did, but explain how that approach only works with something like a custom AuthenticationProvider.

Also as an aside that should probably be addressed separately, I notice that providing a custom implementation of TokenValidator as you have in the tests here seems like a nice simple way to enhance the Authentication attributes, but I don't see it mentioned anywhere in the documentation.

[sdelamo]

While I think showing this particular example is useful in its own right,

While I think showing this particular example is useful in its own right, I don't really think it addresses the specific use case from #1430 wherein they are fully replacing the default Authentication object such that a call to request.getPrincipal(AuthenticationWithEmail.class) would be expected to work.

They are not fully replacing authentication. They are creating:

class TokenAuthentication implements Authentication {
String token
}

I think this PR adds the docs they would need for they usecase (bind such a class in a controller method parameter).

Happy to do further improvements but I think we should get this merged in.

[jeremyg484]

They are not fully replacing authentication. They are creating:

class TokenAuthentication implements Authentication {
String token
}

I think this PR adds the docs they would need for they usecase (bind such a class in a controller method parameter).

In #1430 (comment) they said that simply extending AbstractPrincipalArgumentBinder solved their problem.

i.e., in Java their example would be:

@Singleton
public class TokenAuthenticationArgumentBinder extends AbstractPrincipalArgumentBinder<TokenAuthentication> {

    public TokenAuthenticationArgumentBinder() {
        super(TokenAuthentication.class);
    }
}

The bind method in their implementation is thus going to call httpRequest.getUserPrincipal(TokenAuthentication.class). For that to be working successfully, they have to have somehow replaced the Authentication that is stored in the request, whether with a custom AuthenticationProvider, a custom OpenIdAuthenticationMapper, etc. Thus the example binder shown in this PR is more than what they need for that specific case.

[jeremyg484]

See my prior comment above. I think this is good in its own right to be merged, but I don't think it addresses the specific case in #1430, so I don't think it should close that issue.

We should address that separately, either with my suggested enhancement in #1522, or by providing a separate documentation example of extending AbstractPrincipalArgumentBinder, or both.