Skip to end of metadata
Go to start of metadata

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)

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)

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.

27 Comments

  1. 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!

    1. This error would be sent if you had forgotten to configure the job to use a build token at all.

      1. @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.

      2. @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.

        1. According to your command line, you are not using this plugin at all. Reread the documentation.

  2. 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!

  3. 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!

    1. No, because in general the build may not have started yet; indeed it might never start, if canceled while in queue. Cf. JENKINS-22849.

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

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

      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.

  5. Hi.  I'm getting a 405, even when Anonymous is granted read.  Logging just shows

    Feb 20, 2015 12:32:01 PM&nbsp;FINE&nbsp;org.jenkinsci.plugins.build_token_root.BuildRootAction
    no such job remotetes
    
    Feb 20, 2015 12:32:45 PM&nbsp;FINE&nbsp;org.jenkinsci.plugins.build_token_root.BuildRootAction
    build on remotetest
    
    Feb 20, 2015 12:33:19 PM&nbsp;FINE&nbsp;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.

    1. The first log message suggests a typo in the job name.

      1. Yeah, that was just a test to check the correct jobname below it was getting through.

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

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

  8. 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)

      1. Thank you for the quick addition!

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

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

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

        1. I am not sure, that is more a question for the GitHub plugin.

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

  11. In the second example 
     

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


    How can we access the `Type` field inside the pipeline ? 


    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}

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