hudson.security
Class CliAuthenticator

java.lang.Object
  hudson.security.CliAuthenticator

public abstract class CliAuthenticator
extends Object

Handles authentication for CLI commands.

CliAuthenticator is used to authenticate an invocation of the CLI command, so that the thread carries the correct Authentication that represents the user who's invoking the command.

Lifecycle

Each time a CLI command is invoked, SecurityRealm.createCliAuthenticator(CLICommand) is called to allocate a fresh CliAuthenticator object.

The Option and Argument annotations on the returned CliAuthenticator instance are scanned and added into the CmdLineParser, then that parser is used to parse command line arguments. This means subtypes can define fields/setters with those annotations to define authentication-specific options to CLI commands.

Once the arguments and options are parsed and populated, authenticate() method is called to perform the authentications. If the authentication succeeds, this method returns an Authentication instance that represents the user. If the authentication fails, this method throws AuthenticationException. To authenticate, the method can use parsed argument/option values, as well as interacting with the client via CLICommand by using its stdin/stdout and its channel (for example, if you want to interactively prompt a password, you can do so by using CLICommand.channel.)

If no explicit credential is provided, or if the SecurityRealm depends on a mode of authentication that doesn't involve in explicit password (such as Kerberos), it's also often useful to fall back to CLICommand.getTransportAuthentication(), in case the user is authenticated at the transport level.

Many commands do not require any authentication (for example, the "help" command), and still more commands can be run successfully with the anonymous permission. So the authenticator should normally allow unauthenticated CLI command invocations. For those, return Jenkins.ANONYMOUS from the authenticate() method.

Example

For a complete example, see the implementation of AbstractPasswordBasedSecurityRealm.createCliAuthenticator(CLICommand)

Since:

1.350

Author:

Kohsuke Kawaguchi

Constructor Summary

CliAuthenticator()

Method Summary

abstract org.acegisecurity.Authentication

authenticate() Authenticates the CLI invocation.

Methods inherited from class java.lang.Object

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

Constructor Detail

CliAuthenticator

public CliAuthenticator()

Method Detail

authenticate

public abstract org.acegisecurity.Authentication authenticate()
                                                       throws org.acegisecurity.AuthenticationException,
                                                              IOException,
                                                              InterruptedException

Authenticates the CLI invocation. See class javadoc for the semantics.

Throws:

org.acegisecurity.AuthenticationException - If the authentication failed and hence the processing shouldn't proceed.

IOException - Can be thrown if the CliAuthenticator fails to interact with the client. This exception is treated as a failure of authentication. It's just that allowing this would often simplify the callee.

InterruptedException - Same motivation as IOException. Treated as an authentication failure.