Package 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:
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.

  • Constructor Details

    • 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 Details

    • getUsername

      public String getUsername()
      Returns the username to authenticate as.
      Returns:
      the username to authenticate as.
      Since:
      1.4

    • getListener

      @NonNull public TaskListener getListener()

    • setListener

      public void setListener(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.

    • authenticateOrFail

      public final void authenticateOrFail() throws IOException
      Throws:
      IOException - Failure reason
      Since:
      TODO

    • authenticate

      public final boolean authenticate(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