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

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

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