Skip to end of banner Go to start of banner

Build Token Root Plugin

Skip to end of metadata

Created by Jesse Glick, last modified by Martin d'Anjou on Oct 21, 2016

Lets build and related REST build triggers be accessed even when anonymous users cannot see Jenkins.

Plugin Information
View Build Authorization Token Root on the plugin site for more information.

Usage

The use case is that Jenkins is secured so that anonymous users lack overall read permissions. Say you want to triggers builds of certain jobs from a script. You can pick a sufficiently authenticated user and use that person’s API token to POST to job/NAME/build. But this grants that person’s full permissions to anyone who can see the script, which is hazardous.

The usual workaround for this issue is to define a build authorization token in job configuration, and have the script ping job/NAME/build?token=SECRET. Unfortunately Jenkins checks URIs hierarchically and just getting as far as job/NAME/ requires authentication.

This plugin offers an alternate URI pattern which is not subject to the usual overall or job read permissions. Just issue an Http GET or POST to buildByToken/build?job=NAME&token=SECRET. This URI is accessible to anonymous users regardless of security setup, so you only need the right token.

Folder are supported. If a job named myJob is inside a folder named myFolder, then the NAME is myFolder/myJob (without the interleaving "job/" string).

(The variant sub-URIs buildWithParameters and polling are also supported, as is the usual delay query parameter.)

To create a token for your job, go to the job configuration, select "Trigger Builds Remotely" in the build triggers section. The token you set here is what you will pass via the url.

Examples

Trigger the RevolutionTest job with the token TacoTuesday

buildByToken/build?job=RevolutionTest&token=TacoTuesday

Trigger the RevolutionTest job with the token TacoTuesday and parameter Type supplied with the value Mexican

buildByToken/buildWithParameters?job=RevolutionTest&token=TacoTuesday&Type=Mexican

Changelog

Version 1.4 (2016 May 03)

JENKINS-25637 Do not require a CSRF crumb to trigger a build.

Version 1.3 (2015 Aug 11)

JENKINS-22849 Include queue item location in HTTP response, just like the core endpoint does.

Version 1.2 (2015 Mar 08)

JENKINS-26693 Ability to trigger Workflow builds.

Version 1.1 (2014 Feb 10)

Added logging to make it easier to diagnose why a given request was rejected. As a Jenkins admin, create a logger covering org.jenkinsci.plugins.build_token_root at FINE or below.

Version 1.0 (2013 May 14)

Initial release.

plugin-trigger

32 Comments

Henry Z
Hi,

This seems to be exactly what I need, I'm writing a script to kick off a job from command line.

I did

curl http://server_name:server_port/buildByToken/build?job=jobName&token=tokenName

but got the following

Authentication required


if I do

wget http://server_name:server_port/buildByToken/build?job=jobName&token=tokenName

I get

HTTP request sent, awaiting response... 403 Forbidden

any advice would be appreciated!
- Permalink
- Aug 26, 2014
1. Jesse Glick
  This error would be sent if you had forgotten to configure the job to use a build token at all.
  Permalink
  
  Aug 26, 2014
  1. Gaurav Chhabra
    @Jesse: I am getting the following error when i try triggering a build using the following command:
    curl 'http://jenkins_server:port/jenkins/job/job_name/build?token=harry'
    Output:
    -----------------------------------------------------
    <html><head><meta http-equiv='refresh' content='1;url=/jenkins/securityRealm/commenceLogin?from=%2Fjenkins%2Fjob%2Fjob_name%2Fbuild%3Ftoken%3Dharry'/><script>window.location.replace('/jenkins/securityRealm/commenceLogin?from=%2Fjenkins%2Fjob%2Fjob_name%2Fbuild%3Ftoken%3Dharry');</script></head><body style='background-color:white; color:white;'>
    Authentication required
    
    </body></html>
    -----------------------------------------------------
    I have admin rights and have also enabled 'Authentication Token'. I also have Build, Discover and Read rights on Job. I am using Jenkins 1.614. Please suggest.
    
    Permalink
    
    Jul 13, 2015
  2. Gaurav Chhabra
    @Jesse: I am getting the following error when i try triggering a build using the following command:
    
    curl 'http://jenkins_server:port/jenkins/job/job_name/build?token=harry'
    
    Output:
    -----------------------------------------------------
    <html><head><meta http-equiv='refresh' content='1;url=/jenkins/securityRealm/commenceLogin?from=%2Fjenkins%2Fjob%2Fjob_name%2Fbuild%3Ftoken%3Dharry'/><script>window.location.replace('/jenkins/securityRealm/commenceLogin?from=%2Fjenkins%2Fjob%2Fjob_name%2Fbuild%3Ftoken%3Dharry');</script></head><body style='background-color:white; color:white;'>
    Authentication required
    
    </body></html>
    -----------------------------------------------------
    
    I have admin rights and have also enabled 'Authentication Token'. I also have Build, Discover and Read rights on Job. I am using Jenkins 1.614. Please suggest.
    
    Permalink
    
    Jul 13, 2015
    1. Jesse Glick
      
      According to your command line, you are not using this plugin at all. Reread the documentation.
      
      Permalink
      
      Aug 11, 2015
Henry Z
Hi,

This seems to be exactly what I need, I'm writing a script to kick off a job from command line.

I did

curl http://server_name:server_port/buildByToken/build?job=jobName&token=tokenName

but got the following

Authentication required


if I do

wget http://server_name:server_port/buildByToken/build?job=jobName&token=tokenName

I get

HTTP request sent, awaiting response... 403 Forbidden

any advice would be appreciated!
- Permalink
- Aug 26, 2014
eran be
Hi

After you trigger a job from remote, you are being redirected to the JOB's page.

Is there a way to be redirected to the build page instead?

Thanks!
- Permalink
- Sep 03, 2014
1. Jesse Glick
  No, because in general the build may not have started yet; indeed it might never start, if canceled while in queue. Cf. JENKINS-22849.
  Permalink
  
  Sep 03, 2014
eran be
Thanks.
one more question.

When I trigger the job from remote, The build submitter is set to: Started by remote host 123.123.123.123

If I have a user name (getting it in the URL as job parameter), Can I set it to be the submitter of the build instead (or with) the remote one?

Thanks
- Permalink
- Sep 04, 2014
1. Jesse Glick
  No, because that would allow you to pretend that someone else had started the build when they did not. If you need to set the submitter, then you ought to authenticate your HTTP request—which probably means you do not need this plugin to begin with.
  Permalink
  
  Sep 15, 2014
  1. J F
    Jesse, I agree that this would be open for spoofing, but I still think it would be a nice out of the box feature. You could prefix the user with something like "unauthenticated_".
    As a work around, I have just added the following to my pipelines:
    echo 'Remotely executed by unauthenticated user: ${env.user}'
    However this requires that I execute pipelines, not freestyle projects (which don't have executable groovy). So I have had to make wrapper pipelines which execute freestyle projects. But then the execution history of projects executed through the pipleline still just show the IP address, which isn't nice.
    
    Permalink
    
    Jun 19, 2017
Keith Marsh
Hi. I'm getting a 405, even when Anonymous is granted read. Logging just shows
Feb 20, 2015 12:32:01 PM FINE org.jenkinsci.plugins.build_token_root.BuildRootAction no such job remotetes Feb 20, 2015 12:32:45 PM FINE org.jenkinsci.plugins.build_token_root.BuildRootAction build on remotetest Feb 20, 2015 12:33:19 PM FINE org.jenkinsci.plugins.build_token_root.BuildRootAction build on remotetest
I have Jenkins own user database, with matrix security. Even if I give Anonymous all overall and job securities, it gives 405. In this instance, /job/remotetest/build?token=TOKEN_NAME works fine.
The remotetest project has Triggers Build Remotely ticked with a token KEITH, and the url /buildByToken/build?job=remotetest&token=KEITH fails 405.
- Permalink
- Feb 20, 2015
1. Jesse Glick
  The first log message suggests a typo in the job name.
  Permalink
  
  Feb 20, 2015
  1. Keith Marsh
    Yeah, that was just a test to check the correct jobname below it was getting through.
    
    Permalink
    
    Feb 20, 2015
David Harris
Hi there.

I have installed this plug in on 2 different jenkins instances, both running 1.6.17

One instance worked perfectly, the other one says it installed correctly and it shows in the installed plugins on the admin page, but the "Trigger builds remotely (e.g., from scripts)" option is not showing under Build triggers.

Any suggestion on how to diagnose why this is the case?

I've looked at the Jenkins logs and the only mention of this plug in is that it installed correctly. I've reinstalled it a few times and even used the .hpi method with the same results.

Cheers,

David
- Permalink
- Jun 24, 2015
omrispector -
Note: If you are testing this with curl or wget, dont forget to escape the '&', or else you will continue to get 401

e.g. curl http://<my-jenkins>:8080/buildByToken/build?job=job-name\&token=djg32smew
- Permalink
- Jun 27, 2015
Gavin L
Is it possible for the POST response to include the queue URL? When calling a build using authentication the response is something like:

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
Content-Length: 0
Location: https://jenkins.server/queue/item/7/
Server: Jetty(winstone-2.8)
- Permalink
- Aug 10, 2015
1. Jesse Glick
  Added in 1.3.
  Permalink
  
  Aug 11, 2015
  1. Gavin L
    Thank you for the quick addition!
    
    Permalink
    
    Aug 14, 2015
sb brad
Hi

Can you use the branch_specifier in jenkins with Trigger Builds remotely?

I have installed this plugin so i can get the payload data passed from a github webhook and it works great.

But I have an issue now where my jenkins job is triggered for all pushes to the repo - the branch specifier in my job config is not being used to differentiate branches.

I guess this is due to the URL specifing the Job directly in the URL but i am wondering if, using Jenkins, we can still use this and the branch specifier?

Many thanks
- Permalink
- Sep 10, 2015
1. Jesse Glick
  Not following your question. github-webhook is already an UnprotectedRootAction, meaning it can work in an instance with no anonymous read access. That is a different means of triggering builds from this plugin; there is no overlap.
  Permalink
  
  Sep 10, 2015
  1. sb brad
    Many thanks for the reply Jesse.
    
    So is there another way of getting the webhook payload from github other than using the option 'This Build is Parameterized' and also being able to use the branch_specifier?
    
    Many thanks
    
    Permalink
    
    Sep 11, 2015
    1. Jesse Glick
      
      I am not sure, that is more a question for the GitHub plugin.
      
      Permalink
      
      Sep 14, 2015
Brice V
Hi ;

First thanks to the plugin contributors! really usefull!

I just post a little step by step tutorial here: http://goo.gl/aWPNNM

hope this helps
- Permalink
- Feb 05, 2016
Mandeep Gulati
In the second example

`buildByToken/buildWithParameters?job=RevolutionTest&token=TacoTuesday&Type=Mexican`

How can we access the `Type` field inside the pipeline ?
- Permalink
- May 08, 2017
1. J F
  Just like you would with any other parameter in a pipeline... This doesn't create the param, it just sets it.
  ${env.Type}
  Permalink
  
  Jun 18, 2017
Ido Kaplan
Hi,

I get this error when trying to execute a trigger.
Authentication required
<!--
You are authenticated as: anonymous
Groups that you are in:

Please advise,
Thanks
Ido
- Permalink
- Sep 06, 2018
devops mind
I am creating job template using jobdsl and wondering if this plugin offers pipeline-compatible steps? appreciate your help.
- Permalink
- Nov 07, 2018
Verinder Singh
How can we configure the authentication token from within the Jenkinsfile?
I'm using Multi branch pipeline and the DSL seed job that I use to create this Multibranch pipeline doesn't have an option to specify the authentication token. So the only place where I can set the authentication token is in the Jenkinsfile. Please advise how can this be achieved
- Permalink
- Jan 17, 2019
1. devops mind
  Here is how i use token in job dsl
  configure { project ->
  ( project / 'authToken' ).setValue('xxxxxxxxxxx')
  }
  Refer Jobdsl documentation : https://jenkinsci.github.io/job-dsl-plugin/#method/javaposse.jobdsl.dsl.jobs.MultiJob.configure
  Permalink
  
  Jan 19, 2019
  1. Verinder Singh
    Thanks, but how would we do it for a branch of a multibranch pipeline. The above configure block would update the main multibranch config, but not the branch config with in the multibranch job
    
    Permalink
    
    Jan 19, 2019
devops mind
I understood that you are using Build root token plugin to codify your job template to have auth token in it.
I do not think multibranch pipeline has any option to use Build root token to trigger builds remotely using AUTH token.
If you are using MultibranchPipelineJob , you may want to set AUTH token via Jenkins to use it using credentialsId wrapper. I guess I do not understand your use case, you may want to send me your question with your code to my email, I may be able to help you.
- Permalink
- Jan 19, 2019

Space shortcuts

Child pages