Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[JENKINS-27027] documentation for the authentication flow inside the …
…application for default authentication possibilities
  • Loading branch information
Wadeck committed Oct 18, 2017
1 parent 02501d5 commit a5ded7a
Show file tree
Hide file tree
Showing 4 changed files with 2,453 additions and 0 deletions.
59 changes: 59 additions & 0 deletions content/doc/developer/security/index.adoc
Expand Up @@ -7,6 +7,8 @@ references:
title: Script Security Developer's Guide
---

:imagesdir: /doc/developer/security/resources

// this is a straight import of https://wiki.jenkins-ci.org/display/JENKINS/Making+your+plugin+behave+in+secured+Jenkins
// TODO check contents and remove wiki page

Expand Down Expand Up @@ -96,6 +98,63 @@ To do this, write Jelly like this:
NOTE: This is not to be confused with the +checkPermission+ invocation in your operation.
Users can still hit the URL directly, so you still need to protect the operation itself, in addition to disabling the UI rendering

=== Authentication methods

In Jenkins the security engine that is used is AcegiSecurity (ancestor of SpringSecurity).
Without any special plugins to manage authentication, an instance of Jenkins is packaged
with the following authentication methods:

* Web UI
** When you use the form on the login page, using the fields j_username and j_password
* REST API
** Using Basic with login / *password*
** Using Basic with login / *apiToken*
* Jenkins-CLI jar
** (deprecated) using remoting transport with login / logout command
** username / password as parameters on each command
** '-auth' argument with username:*password* or username:*apiToken* that will do something like HTTP calls
** using SSH transport mode with your local keys
* CLI over SSH
** directly using the native SSH command, without Jenkins-CLI

=== Authentication flow

Depending on the authentication method you use, the processing flow will differ drastically.
By flow we mean the involved classes that will check your credentials for validity.

Starting with the easiest part, the authentication using Web UI and REST API.

image:web_rest_flow.png["Web UI and REST API flow", role=center]

Both the Web UI and the REST API using login / password will flow in the same +AbstractPasswordBasedSecurityRealm+
that delegates the real check to the configured +SecurityRealm+.
The credentials are retrieved for the first method by retrieving information in the POST and for the second by using the Basic Authentication (in header).
A point that is important to mention here, the Web UI is the only way (not deprecated) that use the Session to save the credentials.

For the login / apiToken calls, the +BasicHeaderApiTokenAuthenticator+ manages to check if the apiToken corresponds to the user with the given login.

For the CLI part, the things become a bit more complicated, not by the complexity but more by the multiplicity of way to connect.

image:cli_flow.png["CLI flow", role=center]

The first case (remoting) is deprecated but explained as potentially it's still used.
The principle is to create a sort of session between the login command and the logout one.
The authentication is checked using the same classes that we use for the Web UI or the REST Api with password.
Once the authentication is verified, the credentials are stored in a local cache that will enable future calls to be authenticated automatically.

The second way put the username and the password as additional parameters of the command (--username and --password).

For the third and fourth ways, we pass the parameters to connect like in an HTTP call in the header.
The authentication is checked exactly the same way as for the REST API depending on the provided password or token.

Last possibility for the Jenkins-CLI is using the SSH transport mode.
Currently it's the recommended way to connect to the CLI.
It uses normal SSH configuration using your local keys to authenticate.
It shares the same verifier with the Native CLI way.

Alternative to the Jenkins-CLI is to use directly the native SSH command.
Nothing special to mention here compared to the SSH transport mode.

////
https://wiki.jenkins-ci.org/display/JENKINS/Making+your+plugin+behave+in+secured+Jenkins
////
2,394 changes: 2,394 additions & 0 deletions content/doc/developer/security/resources/_auth_flow_schema.svg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit a5ded7a

Please sign in to comment.