com.cloudbees.jenkins.plugins.sshcredentials

Class SSHAuthenticator<C,U extends com.cloudbees.plugins.credentials.common.StandardUsernameCredentials>

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 com.cloudbees.plugins.credentials.common.StandardUsernameCredentials>
extends Object

Abstraction for something that can authenticate an SSH connection.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SSHAuthenticator.Mode Reflects the different styles of applying authentication.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SSHAuthenticator(C connection, U user) Deprecated. use SSHAuthenticator(Object, com.cloudbees.plugins.credentials.common.StandardUsernameCredentials, String)
protected	SSHAuthenticator(C connection, U user, String username) Constructor.

Method Summary

Modifier and Type	Method and Description
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 List<? extends com.cloudbees.plugins.credentials.common.StandardUsernameCredentials>	filter(Iterable<? extends com.cloudbees.plugins.credentials.Credentials> credentials, Class<?> connectionClass) Deprecated. Use CredentialsMatchers.filter(List, CredentialsMatcher) and matcher(Class)
SSHAuthenticator.Mode	getAuthenticationMode() Returns the mode of authentication that this SSHAuthenticator supports.
protected C	getConnection() Gets the bound connection.
hudson.model.TaskListener	getListener()
static List<String>	getPrivateKeys(SSHUserPrivateKey user) Same as SSHUserPrivateKey.getPrivateKeys() but backward compatible for old implementations.
U	getUser() Gets the supplied credentials.
String	getUsername() Returns the username to authenticate as.
boolean	isAuthenticated() Returns true if the bound connection has been authenticated.
static <C,U extends com.cloudbees.plugins.credentials.common.StandardUsernameCredentials> boolean	isSupported(Class<C> connectionClass, Class<U> userClass) Returns true if and only if the supplied connection class and user class are supported by at least one factory.
static com.cloudbees.plugins.credentials.CredentialsMatcher	matcher() Returns a CredentialsMatcher that matches the generic types of credential that are valid for use over SSH.
static com.cloudbees.plugins.credentials.CredentialsMatcher	matcher(Class<?> connectionClass) Creates a CredentialsMatcher for the specific type of connection.
static <C,U extends com.cloudbees.plugins.credentials.common.StandardUsernameCredentials> SSHAuthenticator<C,U>	newInstance(C connection, U user) Creates an authenticator that may be able to authenticate the supplied connection with the supplied user.
static <C,U extends com.cloudbees.plugins.credentials.common.StandardUsernameCredentials> SSHAuthenticator<C,U>	newInstance(C connection, U user, String username) Creates an authenticator that may be able to authenticate the supplied connection with the supplied user.
static SSHAuthenticator<Object,com.cloudbees.plugins.credentials.common.StandardUsernameCredentials>	newInstance(Object connection, SSHUser user) Deprecated. Use newInstance(Object, StandardUsernameCredentials) instead.
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

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

Deprecated. use SSHAuthenticator(Object, com.cloudbees.plugins.credentials.common.StandardUsernameCredentials, String)

Constructor.

Parameters:

connection - the connection we will be authenticating.

user - the user we will be authenticating as.

SSHAuthenticator

protected SSHAuthenticator(@NonNull
                           C connection,
                           @NonNull
                           U user,
                           @CheckForNull
                           String username)

Constructor.

Parameters:

connection - the connection we will be authenticating.

user - the user we will be authenticating as.

username - the username we will be authenticating as or null to use the users username.

Since:

1.4

Method Detail

getUsername

public String getUsername()

Returns the username to authenticate as.

Returns:

the username to authenticate as.

Since:

1.4

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 com.cloudbees.plugins.credentials.common.StandardUsernameCredentials> SSHAuthenticator<C,U> newInstance(@NonNull
                                                                                                                                            C connection,
                                                                                                                                            @NonNull
                                                                                                                                            U user)
                                                                                                                                     throws InterruptedException,
                                                                                                                                            IOException

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.

Throws:

InterruptedException

IOException

newInstance

@NonNull
public static <C,U extends com.cloudbees.plugins.credentials.common.StandardUsernameCredentials> SSHAuthenticator<C,U> newInstance(@NonNull
                                                                                                                                            C connection,
                                                                                                                                            @NonNull
                                                                                                                                            U user,
                                                                                                                                            @CheckForNull
                                                                                                                                            String username)
                                                                                                                                     throws InterruptedException,
                                                                                                                                            IOException

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.

username - the username or null to fall back to the username in the user parameter.

Returns:

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

Throws:

InterruptedException

IOException

Since:

1.4

newInstance

@Deprecated
public static SSHAuthenticator<Object,com.cloudbees.plugins.credentials.common.StandardUsernameCredentials> newInstance(Object connection,
                                                                                                                                    SSHUser user)
                                                                                                                             throws InterruptedException,
                                                                                                                                    IOException

Deprecated. Use newInstance(Object, StandardUsernameCredentials) instead.

Throws:

InterruptedException

IOException

isSupported

public static <C,U extends com.cloudbees.plugins.credentials.common.StandardUsernameCredentials> boolean isSupported(@NonNull
                                                                                                                     Class<C> connectionClass,
                                                                                                                     @NonNull
                                                                                                                     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 List<? extends com.cloudbees.plugins.credentials.common.StandardUsernameCredentials> filter(Iterable<? extends com.cloudbees.plugins.credentials.Credentials> credentials,
                                                                                                          Class<?> connectionClass)

Deprecated. Use CredentialsMatchers.filter(List, CredentialsMatcher) and matcher(Class)

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.

matcher

public static com.cloudbees.plugins.credentials.CredentialsMatcher matcher()

Returns a CredentialsMatcher that matches the generic types of credential that are valid for use over SSH. When you know the connection type you will be using, it is better to use matcher(Class).

Returns:

a CredentialsMatcher that matches the generic types of credential that are valid for use over SSH.

matcher

public static com.cloudbees.plugins.credentials.CredentialsMatcher matcher(Class<?> connectionClass)

Creates a CredentialsMatcher for the specific type of connection.

Parameters:

connectionClass - the type of connection.

Returns:

a CredentialsMatcher

Since:

0.5

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.

getPrivateKeys

public static List<String> getPrivateKeys(SSHUserPrivateKey user)

Same as SSHUserPrivateKey.getPrivateKeys() but backward compatible for old implementations.

Since:

1.3