com.cloudbees.jenkins.plugins.sshcredentials
Class SSHAuthenticator<C,U extends SSHUser>

java.lang.Object
  com.cloudbees.jenkins.plugins.sshcredentials.SSHAuthenticator<C,U>

Type Parameters:

C - the type of connection.

U - the user to authenticate.

Direct Known Subclasses:

JSchSSHPasswordAuthenticator, JSchSSHPublicKeyAuthenticator, TrileadSSHPasswordAuthenticator, TrileadSSHPublicKeyAuthenticator

public abstract class SSHAuthenticator<C,U extends SSHUser>
extends java.lang.Object

Abstraction for something that can authenticate an SSH connection.

Nested Class Summary

static class

SSHAuthenticator.Mode Reflects the different styles of applying authentication.

Constructor Summary

protected

SSHAuthenticator(C connection, U user) Constructor.

Method Summary

boolean	authenticate() Deprecated. as of 0.3 Use authenticate(TaskListener) and provide a listener to receive errors.
boolean	authenticate(hudson.model.TaskListener listener) Authenticate the bound connection using the supplied credentials.
boolean	canAuthenticate() Returns true if the bound connection is in a state where authentication can be tried using the supplied credentials.
protected abstract boolean	doAuthenticate() SPI for authenticating the bound connection using the supplied credentials.
static java.util.List<? extends SSHUser>	filter(java.lang.Iterable<? extends com.cloudbees.plugins.credentials.Credentials> credentials, java.lang.Class<?> connectionClass) Filters Credentials returning only those which are supported with the specified type of connection.
SSHAuthenticator.Mode	getAuthenticationMode() Returns the mode of authentication that this SSHAuthenticator supports.
protected C	getConnection() Gets the bound connection.
hudson.model.TaskListener	getListener()
U	getUser() Gets the supplied credentials.
boolean	isAuthenticated() Returns true if the bound connection has been authenticated.
static <C,U extends SSHUser> boolean	isSupported(java.lang.Class<C> connectionClass, java.lang.Class<U> userClass) Returns true if and only if the supplied connection class and user class are supported by at least one factory.
static <C,U extends SSHUser> SSHAuthenticator<C,U>	newInstance(C connection, U user) Creates an authenticator that may be able to authenticate the supplied connection with the supplied user.
void	setListener(hudson.model.TaskListener listener) Sets the TaskListener that receives errors that happen during the authentication.

Methods inherited from class java.lang.Object

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

Constructor Detail

SSHAuthenticator

protected SSHAuthenticator(@NonNull
                           C connection,
                           @NonNull
                           U user)

Constructor.

Parameters:

connection - the connection we will be authenticating.

Method Detail

getListener

@NonNull
public hudson.model.TaskListener getListener()

setListener

public void setListener(hudson.model.TaskListener listener)

Sets the TaskListener that receives errors that happen during the authentication. If you are doing this as a part of a build, pass in your BuildListener. Pass in null to suppress the error reporting. Doing so is useful if the caller intends to try another SSHAuthenticator when this one fails. For assisting troubleshooting with callers that do not provide a valid listener, by default the errors will be sent to stderr of the server.

newInstance

@NonNull
public static <C,U extends SSHUser> SSHAuthenticator<C,U> newInstance(@NonNull
                                                                              C connection,
                                                                              @NonNull
                                                                              U user)

Creates an authenticator that may be able to authenticate the supplied connection with the supplied user.

Type Parameters:

C - the type of connection.

U - the type of user.

Parameters:

connection - the connection to authenticate on.

user - the user to authenticate with.

Returns:

a SSHAuthenticator that may or may not be able to successfully authenticate.

isSupported

public static <C,U extends SSHUser> boolean isSupported(@NonNull
                                                        java.lang.Class<C> connectionClass,
                                                        @NonNull
                                                        java.lang.Class<U> userClass)

Returns true if and only if the supplied connection class and user class are supported by at least one factory.

Type Parameters:

C - the type of connection.

U - the type of user.

Parameters:

connectionClass - the connection class.

userClass - the user class.

Returns:

true if and only if the supplied connection class and user class are supported by at least one factory.

filter

public static java.util.List<? extends SSHUser> filter(java.lang.Iterable<? extends com.cloudbees.plugins.credentials.Credentials> credentials,
                                                       java.lang.Class<?> connectionClass)

Filters Credentials returning only those which are supported with the specified type of connection.

Parameters:

credentials - the credentials to filter.

connectionClass - the type of connection to filter for.

Returns:

a list of SSHUser credentials appropriate for use with the supplied type of connection.

canAuthenticate

public boolean canAuthenticate()

Returns true if the bound connection is in a state where authentication can be tried using the supplied credentials.

Subclasses can override this if they can tell whether it is possible to make an authentication attempt, default implementation is one-shot always.

Returns:

true if the bound connection is in a state where authentication can be tried using the supplied credentials.

isAuthenticated

public final boolean isAuthenticated()

Returns true if the bound connection has been authenticated.

Returns:

true if the bound connection has been authenticated.

getConnection

@NonNull
protected final C getConnection()

Gets the bound connection.

Returns:

the bound connection.

getUser

@NonNull
public U getUser()

Gets the supplied credentials.

Returns:

the supplied credentials.

doAuthenticate

protected abstract boolean doAuthenticate()

SPI for authenticating the bound connection using the supplied credentials. As a guideline, authentication errors should be reported to getListener() before this method returns with false. This helps an user better understand what is tried and failing. Logging can be used in addition to this to capture further details. (in contrast, please avoid reporting a success to the listener to improve S/N ratio)

Returns:

true if and only if authentication was successful.

getAuthenticationMode

@NonNull
public SSHAuthenticator.Mode getAuthenticationMode()

Returns the mode of authentication that this SSHAuthenticator supports.

Returns:

the mode of authentication that this SSHAuthenticator supports.

Since:

0.2

authenticate

public final boolean authenticate()

Deprecated. as of 0.3 Use authenticate(TaskListener) and provide a listener to receive errors.

authenticate

public final boolean authenticate(hudson.model.TaskListener listener)

Authenticate the bound connection using the supplied credentials.

Returns:

For an getAuthenticationMode() of SSHAuthenticator.Mode.BEFORE_CONNECT the return value is always true otherwise the return value is true if and only if authentication was successful.