net.devh.boot.grpc.client.security

Class CallCredentialsHelper

java.lang.Object

net.devh.boot.grpc.client.security.CallCredentialsHelper

public class CallCredentialsHelper
extends Object

Helper class with useful methods to create and configure some commonly used authentication schemes such as Basic-Auth.

Note: If you have exactly one CallCredentials bean in your application context then it will be used for all AbstractStub that are annotation with GrpcClient. If you have none or multiple CallCredentials in the application context or use Channels, then you have to configure the credentials yourself (See GrpcClientSecurityAutoConfiguration).

Currently the following CallCredentials are supported by this class:

• Basic-Auth
• Bearer-Auth
• Other variants using static or dynamic headers
• Require privacy for the connection (Wrapper)
• Include credentials only if connection is private (Wrapper)

Usage:

• If you need only a single CallCredentials for all services, then it suffices to declare it as bean in your application context/configuration.

   @Bean
   CallCredentials myCallCredentials() {
       return CallCredentialsHelper.basicAuth("user", "password");
   }
   

• If you need multiple/different CallCredentials for the services or only need them for a subset, then you should either add none of them or all of them (two ore more) to your application context to prevent the automatic credential selection. You can use a StubTransformer to select a CallCredential based on the client name instead.

   @Bean
   StubTransformer myCallCredentialsTransformer() {
       return CallCredentialsHelper.mappedCredentialsStubTransformer(Map.of(
           "myService1", basicAuth("user1", "password1"),
           "theService2", basicAuth("foo", "bar"),
           "publicApi", null // No credentials needed
       ));
   }
   

• If you need different CallCredentials for each call, then you have to define it in the method yourself.

   stub.withCallCredentials(CallCredentialsHelper.basicAuth("user", "password")).doStuff(request);
   

Method Summary

Modifier and Type	Method and Description
static io.grpc.CallCredentials	authorizationHeader(String authorization) Creates new call credentials with the given static authorization information.
static io.grpc.CallCredentials	authorizationHeader(Supplier<String> authorizationSource) Creates new call credentials with the given authorization information source.
static io.grpc.CallCredentials	authorizationHeaders(io.grpc.Metadata authorizationHeaders) Creates new call credentials with the given static authorization headers.
static io.grpc.CallCredentials	authorizationHeaders(Supplier<io.grpc.Metadata> authorizationHeadersSupplier) Creates new call credentials with the given authorization headers source.
static io.grpc.CallCredentials	basicAuth(String username, String password) Creates new call credentials with the given username and password for basic auth.
static io.grpc.CallCredentials	bearerAuth(String token) Creates new call credentials with the given token for bearer auth.
static io.grpc.CallCredentials	bearerAuth(Supplier<String> tokenSource) Creates new call credentials with the given token source for bearer auth.
static String	encodeBasicAuth(String username, String password) Encodes the given username and password as basic auth.
static StubTransformer	fixedCredentialsStubTransformer(io.grpc.CallCredentials credentials) Creates a new StubTransformer that will assign the given credentials to the given AbstractStub.
static io.grpc.CallCredentials	includeWhenPrivate(io.grpc.CallCredentials callCredentials) Wraps the given call credentials in a new layer, that will only include the credentials if the connection guarantees privacy.
static boolean	isPrivacyGuaranteed(io.grpc.SecurityLevel securityLevel) Checks whether the given security level provides privacy for all data being send on the connection.
static StubTransformer	mappedCredentialsStubTransformer(Map<String,io.grpc.CallCredentials> credentialsByName) Creates a new StubTransformer that will assign credentials to the given AbstractStub based on the name.
static StubTransformer	mappedCredentialsStubTransformer(Map<String,io.grpc.CallCredentials> credentialsByName, io.grpc.CallCredentials fallback) Creates a new StubTransformer that will assign credentials to the given AbstractStub based on the name.
static io.grpc.CallCredentials	requirePrivacy(io.grpc.CallCredentials callCredentials) Wraps the given call credentials in a new layer, which ensures that the credentials are only send, if the connection guarantees privacy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

fixedCredentialsStubTransformer

public static StubTransformer fixedCredentialsStubTransformer(io.grpc.CallCredentials credentials)

Creates a new StubTransformer that will assign the given credentials to the given AbstractStub.

Parameters:

credentials - The call credentials to assign.

Returns:

The transformed stub.

See Also:

AbstractStub.withCallCredentials(CallCredentials)

mappedCredentialsStubTransformer

public static StubTransformer mappedCredentialsStubTransformer(Map<String,io.grpc.CallCredentials> credentialsByName)

Creates a new StubTransformer that will assign credentials to the given AbstractStub based on the name. If the given map does not contain a value for the given name, then the call credentials will be omitted.

Parameters:

credentialsByName - The map that contains the call credentials.

Returns:

The transformed stub.

See Also:

mappedCredentialsStubTransformer(Map, CallCredentials), AbstractStub.withCallCredentials(CallCredentials)

mappedCredentialsStubTransformer

public static StubTransformer mappedCredentialsStubTransformer(Map<String,io.grpc.CallCredentials> credentialsByName,
                                                               @Nullable
                                                               io.grpc.CallCredentials fallback)

Creates a new StubTransformer that will assign credentials to the given AbstractStub based on the name. If the given map does not contain a value for the given name, then the optional fallback will be used otherwise the call credentials will be omitted.

Parameters:

credentialsByName - The map that contains the call credentials.

fallback - The optional fallback to use.

Returns:

The transformed stub.

See Also:

AbstractStub.withCallCredentials(CallCredentials)

bearerAuth

public static io.grpc.CallCredentials bearerAuth(String token)

Creates new call credentials with the given token for bearer auth. Use this method if you have a permanent token or only use the call credentials for a single call/while the token is valid.

Note: This method uses experimental grpc-java-API features.

Parameters:

token - the bearer token to use

Returns:

The newly created bearer auth credentials.

See Also:

SecurityConstants.BEARER_AUTH_PREFIX, authorizationHeader(String)

bearerAuth

public static io.grpc.CallCredentials bearerAuth(Supplier<String> tokenSource)

Creates new call credentials with the given token source for bearer auth. Use this method if you derive the token from the active context (e.g. currently logged in user) or dynamically obtain it from the authentication server.

Note: This method uses experimental grpc-java-API features.

Parameters:

tokenSource - the bearer token source to use

Returns:

The newly created bearer auth credentials.

See Also:

SecurityConstants.BEARER_AUTH_PREFIX, authorizationHeader(Supplier)

basicAuth

public static io.grpc.CallCredentials basicAuth(String username,
                                                String password)

Creates new call credentials with the given username and password for basic auth.

Note: This method uses experimental grpc-java-API features.

Parameters:

username - The username to use.

password - The password to use.

Returns:

The newly created basic auth credentials.

See Also:

SecurityConstants.BASIC_AUTH_PREFIX, encodeBasicAuth(String, String), authorizationHeader(String)

encodeBasicAuth

public static String encodeBasicAuth(String username,
                                     String password)

Encodes the given username and password as basic auth. The header value will be encoded with UTF_8.

Parameters:

username - The username to use.

password - The password to use.

Returns:

The encoded basic auth header value.

See Also:

SecurityConstants.BASIC_AUTH_PREFIX

authorizationHeader

public static io.grpc.CallCredentials authorizationHeader(String authorization)

Creates new call credentials with the given static authorization information.

Note: This method uses experimental grpc-java-API features.

Parameters:

authorization - The authorization to use. The authorization usually starts with the scheme such as as "Basic " or "Bearer " followed by the actual authentication information.

Returns:

The newly created call credentials.

See Also:

SecurityConstants.AUTHORIZATION_HEADER, authorizationHeaders(Metadata)

authorizationHeader

public static io.grpc.CallCredentials authorizationHeader(Supplier<String> authorizationSource)

Creates new call credentials with the given authorization information source.

Note: This method uses experimental grpc-java-API features.

Parameters:

authorizationSource - The authorization source to use. The authorization usually starts with the scheme such as as "Basic " or "Bearer " followed by the actual authentication information.

Returns:

The newly created call credentials.

See Also:

SecurityConstants.AUTHORIZATION_HEADER, authorizationHeaders(Supplier)

authorizationHeaders

public static io.grpc.CallCredentials authorizationHeaders(io.grpc.Metadata authorizationHeaders)

Creates new call credentials with the given static authorization headers.

Parameters:

authorizationHeaders - The authorization headers to use.

Returns:

The newly created call credentials.

authorizationHeaders

public static io.grpc.CallCredentials authorizationHeaders(Supplier<io.grpc.Metadata> authorizationHeadersSupplier)

Creates new call credentials with the given authorization headers source.

Parameters:

authorizationHeadersSupplier - The authorization headers source to use.

Returns:

The newly created call credentials.

isPrivacyGuaranteed

public static boolean isPrivacyGuaranteed(io.grpc.SecurityLevel securityLevel)

Checks whether the given security level provides privacy for all data being send on the connection.

Note: This method uses experimental grpc-java-API features.

Parameters:

securityLevel - The security level to check.

Returns:

True, if and only if the given security level ensures privacy. False otherwise.

requirePrivacy

public static io.grpc.CallCredentials requirePrivacy(io.grpc.CallCredentials callCredentials)

Wraps the given call credentials in a new layer, which ensures that the credentials are only send, if the connection guarantees privacy. If the connection doesn't do that, the call will be aborted before sending any data.

Note: This method uses experimental grpc-java-API features.

Parameters:

callCredentials - The call credentials to wrap.

Returns:

The newly created call credentials.

includeWhenPrivate

public static io.grpc.CallCredentials includeWhenPrivate(io.grpc.CallCredentials callCredentials)

Wraps the given call credentials in a new layer, that will only include the credentials if the connection guarantees privacy. If the connection doesn't do that, the call will continue without the credentials.

Note: This method uses experimental grpc-java-API features.

Parameters:

callCredentials - The call credentials to wrap.

Returns:

The newly created call credentials.