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
atFINE
or below.
Version 1.0 (2013 May 14)
- Initial release.
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
<!--
You are authenticated as: anonymous
Groups that you are in:
Permission you need to have (but didn't): hudson.model.Item.Build
... which is implied by: hudson.security.Permission.GenericUpdate
... which is implied by: hudson.security.Permission.GenericWrite
... which is implied by: hudson.model.Hudson.Administer
-->
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!
Jesse Glick
This error would be sent if you had forgotten to configure the job to use a build token at all.
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
<!--
You are authenticated as: anonymous
Groups that you are in:
Permission you need to have (but didn't): hudson.model.Hudson.Read
... which is implied by: hudson.security.Permission.GenericRead
... which is implied by: hudson.model.Hudson.Administer
-->
</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.
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
<!--
You are authenticated as: anonymous
Groups that you are in:
Permission you need to have (but didn't): hudson.model.Hudson.Read
... which is implied by: hudson.security.Permission.GenericRead
... which is implied by: hudson.model.Hudson.Administer
-->
</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.
Jesse Glick
According to your command line, you are not using this plugin at all. Reread the documentation.
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
<!--
You are authenticated as: anonymous
Groups that you are in:
Permission you need to have (but didn't): hudson.model.Item.Build
... which is implied by: hudson.security.Permission.GenericUpdate
... which is implied by: hudson.security.Permission.GenericWrite
... which is implied by: hudson.model.Hudson.Administer
-->
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!
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!
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.
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
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.
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.
Keith Marsh
Hi. I'm getting a 405, even when Anonymous is granted read. Logging just shows
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.
Jesse Glick
The first log message suggests a typo in the job name.
Keith Marsh
Yeah, that was just a test to check the correct jobname below it was getting through.
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
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
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)
Jesse Glick
Added in 1.3.
Gavin L
Thank you for the quick addition!
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
Jesse Glick
Not following your question.
github-webhook
is already anUnprotectedRootAction
, 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.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
Jesse Glick
I am not sure, that is more a question for the GitHub plugin.
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
Mandeep Gulati
In the second example
`buildByToken/buildWithParameters?job=RevolutionTest&token=TacoTuesday&Type=Mexican`
How can we access the `Type` field inside the pipeline ?
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}
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
devops mind
I am creating job template using jobdsl and wondering if this plugin offers pipeline-compatible steps? appreciate your help.
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
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
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
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.