[JENKINS-27027] Log/notify REST authentication via API token

[jenkins-infra-bot]

Original request: SecurityListener should be notified when ApiTokenFilter approves or denies a REST authentication attempt. jglick says that the logic should be reviewed from scratch.

TL;DR:

• Investigate how it works
• Send events when it does not

Acceptance criteria:

• We cover REST, CLI, Web UI...
• Data should be forwarded to SecurityListener and logged here:

  jenkins/core/src/main/java/jenkins/security/SecurityListener.java

  Line 91 in 08def67

  LOGGER.log(Level.FINE, "authenticated: {0} {1}", new Object[] {details.getUsername(), groups});

   
• Anybody should be able to attach to the Security Listener and get the information (via plugin or so)
• Nice2have: Review Javadoc of the engine and ensure it is still correct
• Nice2have: Document the login flow in Wiki (or Jenkins.io developer docs)
• What should happen:
  • When you login, you get event
  • When the authentication is sent, you get event. Includes REST API (password != API token) and Web calls. Example:

    jenkins/core/src/main/java/hudson/security/AbstractPasswordBasedSecurityRealm.java

    Line 116 in 7290169

    SecurityListener.fireAuthenticated(user);

      

Not in scope:

• SecurityListener Audit Trail patch is not in the scope. May be used as reference impl if we need to add new API

---

Originally reported by jglick, imported from: Log/notify REST authentication via API token

• assignee: wfollonier
• status: Resolved
• priority: Major
• component(s): core
• label(s): api, logging, rest, security
• resolution: Fixed
• resolved: 2017-12-05T14:05:53+00:00
• votes: 0
• watchers: 5
• imported: 2025-11-24

Raw content of original issue

Original request: SecurityListener should be notified when ApiTokenFilter approves or denies a REST authentication attempt. jglick says that the logic should be reviewed from scratch.

TL;DR:

	
Investigate how it works
	
Send events when it does not



Acceptance criteria:

	
We cover REST, CLI, Web UI...
	
Data should be forwarded to SecurityListener and logged here: 

  

    

      jenkins/core/src/main/java/jenkins/security/SecurityListener.java
    
    

         Line 91
      in
      08def67
    
  
  

    


        

          

          
 LOGGER.log(Level.FINE, "authenticated: {0} {1}", new Object[] {details.getUsername(), groups}); 
        
    
  

 
	
Anybody should be able to attach to the Security Listener and get the information (via plugin or so)
	
Nice2have: Review Javadoc of the engine and ensure it is still correct
	
Nice2have: Document the login flow in Wiki (or Jenkins.io developer docs)
	
What should happen:
	

		
When you login, you get event
		
When the authentication is sent, you get event. Includes REST API (password != API token) and Web calls. Example: 

  

    

      jenkins/core/src/main/java/hudson/security/AbstractPasswordBasedSecurityRealm.java
    
    

         Line 116
      in
      7290169
    
  
  

    


        

          

          
 SecurityListener.fireAuthenticated(user); 
        
    
  

  
	
	



Not in scope:

	
SecurityListener Audit Trail patch is not in the scope. May be used as reference impl if we need to add new API

[jenkins-infra-bot]

• Remote links associated with this issue:

  • #​3074
  • #​1192 (jenkins-io)

[jenkins-infra-bot]

jglick:

• Original comment link
• Raw content of original comment:

  More broadly, a filter notifying you of any HTTP connection for which Jenkins.authentication can be established.
  

More broadly, a filter notifying you of any HTTP connection for which Jenkins.authentication can be established.

[jenkins-infra-bot]

ifernandezcalvo:

• Original comment link
• Raw content of original comment:

  Authentication Points
  
  
    
  
      
  
        jenkins/core/src/main/java/hudson/security/BasicAuthenticationFilter.java
      
      
  
          Lines 141 to 149
        in
        d1d1ab1
      
    
    
  
      
  
  
          
  
            
  
            
   ApiTokenProperty t = u.getProperty(ApiTokenProperty.class); 
          
  
          
  
            
  
            
   if (t!=null && t.matchesPassword(password)) { 
          
  
          
  
            
  
            
       SecurityContextHolder.getContext().setAuthentication(u.impersonate()); 
          
  
          
  
            
  
            
       try { 
          
  
          
  
            
  
            
           chain.doFilter(request,response); 
          
  
          
  
            
  
            
       } finally { 
          
  
          
  
            
  
            
           SecurityContextHolder.clearContext(); 
          
  
          
  
            
  
            
       } 
          
  
          
  
            
  
            
       return; 
          
      
    
  
  
  
  
    
  
      
  
        jenkins/core/src/main/java/jenkins/security/BasicHeaderApiTokenAuthenticator.java
      
      
  
          Lines 28 to 41
        in
        d1d1ab1
      
    
    
  
      
  
  
          
  
            
  
            
   ApiTokenProperty t = u.getProperty(ApiTokenProperty.class); 
          
  
          
  
            
  
            
   if (t!=null && t.matchesPassword(password)) { 
          
  
          
  
            
  
            
       try { 
          
  
          
  
            
  
            
           return u.impersonate(); 
          
  
          
  
            
  
            
       } catch (UsernameNotFoundException x) { 
          
  
          
  
            
  
            
           // The token was valid, but the impersonation failed. This token is clearly not his real password, 
          
  
          
  
            
  
            
           // so there's no point in continuing the request processing. Report this error and abort. 
          
  
          
  
            
  
            
           LOGGER.log(WARNING, "API token matched for user "+username+" but the impersonation failed",x); 
          
  
          
  
            
  
            
           throw new ServletException(x); 
          
  
          
  
            
  
            
       } catch (DataAccessException x) { 
          
  
          
  
            
  
            
           throw new ServletException(x); 
          
  
          
  
            
  
            
       } 
          
  
          
  
            
  
            
   } 
          
  
          
  
            
  
            
   return null; 
          
      
    
  
  
  
  Authorization Point
  
  
    
  
      
  
        jenkins/core/src/main/java/hudson/model/User.java
      
      
  
          Lines 311 to 313
        in
        d1d1ab1
      
    
    
  
      
  
  
          
  
            
  
            
   UserDetails u = new ImpersonatingUserDetailsService( 
          
  
          
  
            
  
            
           Jenkins.getInstance().getSecurityRealm().getSecurityComponents().userDetails).loadUserByUsername(id); 
          
  
          
  
            
  
            
   return new UsernamePasswordAuthenticationToken(u.getUsername(), "", u.getAuthorities()); 
          
      
    
  
  
  
  
    
  
      
  
        jenkins/core/src/main/java/hudson/model/User.java
      
      
  
          Lines 325 to 326
        in
        d1d1ab1
      
    
    
  
      
  
  
          
  
            
  
            
   return new UsernamePasswordAuthenticationToken(id, "", 
          
  
          
  
            
  
            
       new GrantedAuthority[]{SecurityRealm.AUTHENTICATED_AUTHORITY}); 
          
      
    
  
  
  
   
  
  It should trigger something like https://github.com/jenkinsci/saml-plugin/blob/master/src/main/java/org/jenkinsci/plugins/saml/SamlSecurityRealm.java#L288 but it does not.
  
   
  

Authentication Points

jenkins/core/src/main/java/hudson/security/BasicAuthenticationFilter.java

Lines 141 to 149 in d1d1ab1

	ApiTokenProperty t = u.getProperty(ApiTokenProperty.class);
	if (t!=null && t.matchesPassword(password)) {
	SecurityContextHolder.getContext().setAuthentication(u.impersonate());
	try {
	chain.doFilter(request,response);
	} finally {
	SecurityContextHolder.clearContext();
	}
	return;

jenkins/core/src/main/java/jenkins/security/BasicHeaderApiTokenAuthenticator.java

Lines 28 to 41 in d1d1ab1

	ApiTokenProperty t = u.getProperty(ApiTokenProperty.class);
	if (t!=null && t.matchesPassword(password)) {
	try {
	return u.impersonate();
	} catch (UsernameNotFoundException x) {
	// The token was valid, but the impersonation failed. This token is clearly not his real password,
	// so there's no point in continuing the request processing. Report this error and abort.
	LOGGER.log(WARNING, "API token matched for user "+username+" but the impersonation failed",x);
	throw new ServletException(x);
	} catch (DataAccessException x) {
	throw new ServletException(x);
	}
	}
	return null;

Authorization Point

jenkins/core/src/main/java/hudson/model/User.java

Lines 311 to 313 in d1d1ab1

	UserDetails u = new ImpersonatingUserDetailsService(
	Jenkins.getInstance().getSecurityRealm().getSecurityComponents().userDetails).loadUserByUsername(id);
	return new UsernamePasswordAuthenticationToken(u.getUsername(), "", u.getAuthorities());

jenkins/core/src/main/java/hudson/model/User.java

Lines 325 to 326 in d1d1ab1

	return new UsernamePasswordAuthenticationToken(id, "",
	new GrantedAuthority[]{SecurityRealm.AUTHENTICATED_AUTHORITY});

 

It should trigger something like https://github.com/jenkinsci/saml-plugin/blob/master/src/main/java/org/jenkinsci/plugins/saml/SamlSecurityRealm.java#L288 but it does not.

 

[jenkins-infra-bot]

scm_issue_link:

• Original comment link
• Raw content of original comment:

  Code changed in jenkins
  User: Wadeck Follonier
  Path:
   content/doc/developer/security/index.adoc
   content/doc/developer/security/resources/_auth_flow_schema.svg
   content/doc/developer/security/resources/cli_flow.png
   content/doc/developer/security/resources/web_rest_flow.png
  http://jenkins-ci.org/commit/jenkins.io/a5ded7a1738f1e7a0f521e4ed5d685e5b6bfc34d
  Log:
    JENKINS-27027 documentation for the authentication flow inside the application for default authentication possibilities
  
  
  

Code changed in jenkins
User: Wadeck Follonier
Path:
content/doc/developer/security/index.adoc
content/doc/developer/security/resources/_auth_flow_schema.svg
content/doc/developer/security/resources/cli_flow.png
content/doc/developer/security/resources/web_rest_flow.png
http://jenkins-ci.org/commit/jenkins.io/a5ded7a1738f1e7a0f521e4ed5d685e5b6bfc34d
Log:
JENKINS-27027 documentation for the authentication flow inside the application for default authentication possibilities

[jenkins-infra-bot]

scm_issue_link:

• Original comment link
• Raw content of original comment:

  Code changed in jenkins
  User: R. Tyler Croy
  Path:
   content/doc/developer/security/index.adoc
   content/doc/developer/security/resources/cli_flow.svg
   content/doc/developer/security/resources/web_rest_flow.svg
  http://jenkins-ci.org/commit/jenkins.io/b953d6c376cc099c0ed9c008c781b444f639ffe6
  Log:
    Merge pull request #1192 from Wadeck/JENKINS-27027_AUTHENTICATION_FLOW
  
  JENKINS-27027 Documentation for Authentication flow
  
  
  Compare: jenkins-infra/jenkins.io@5293a1d...b953d6c
  
  

Code changed in jenkins
User: R. Tyler Croy
Path:
content/doc/developer/security/index.adoc
content/doc/developer/security/resources/cli_flow.svg
content/doc/developer/security/resources/web_rest_flow.svg
http://jenkins-ci.org/commit/jenkins.io/b953d6c376cc099c0ed9c008c781b444f639ffe6
Log:
Merge pull request #1192 from Wadeck/JENKINS-27027_AUTHENTICATION_FLOW

JENKINS-27027 Documentation for Authentication flow

Compare: jenkins-infra/jenkins.io@5293a1d...b953d6c

[jenkins-infra-bot]

scm_issue_link:

• Original comment link
• Raw content of original comment:

  Code changed in jenkins
  User: Wadeck Follonier
  Path:
   core/src/main/java/hudson/Functions.java
   core/src/main/java/hudson/cli/CLICommand.java
   core/src/main/java/hudson/cli/ClientAuthenticationCache.java
   core/src/main/java/hudson/cli/LoginCommand.java
   core/src/main/java/hudson/cli/LogoutCommand.java
   core/src/main/java/hudson/model/User.java
   core/src/main/java/hudson/security/ACL.java
   core/src/main/java/hudson/security/BasicAuthenticationFilter.java
   core/src/main/java/jenkins/security/BasicHeaderApiTokenAuthenticator.java
   core/src/main/java/jenkins/security/SecurityListener.java
   test/src/test/java/hudson/security/CliAuthenticationTest.java
   test/src/test/java/jenkins/security/BasicHeaderProcessorTest.java
   test/src/test/java/jenkins/security/SpySecurityListener.java
  http://jenkins-ci.org/commit/jenkins/b7f42b2e59b2081782d6e51da18b0c93808d98da
  Log:
    JENKINS-27027 Notify the SecurityListener on authentication (#3074)
  
  
  	
  JENKINS-27026 Notify the SecurityListener in case of Token based authentication success
  
  
  	
  due the current version of the method, the UserDetails required for the event was not accessible. In order to stay with the same API in SecurityListener, two "protected" methods were created to split the job and let the UserDetails accessible
  
  
  
  
  	
  - add test to ensure the SecurityListener is called for REST Token but also for regular basic auth
  
  
  
  
  	
  - remove the comment about the split, will be put in GitHub comment instead
  
  
  
  
  	
  - add check for anonymous call instead of just putting a comment
  
  
  	
  remove the constructor in the dummy
  	
  add link to PR from Daniel to simplify a call
  
  
  
  
  	
  - separate the before/after to save one clear and be more explicit
  
  
  	
  put more meaning in the assertLastEventIs method by explicitly say we will remove the last event
  
  
  
  
  	
  - add comment about why we do not fire the "failedToAuthenticated" in the case of an invalid token (tips: it's because it could be a valid password)
  
  
  
  
  	
  - also add the authenticated trigger on legacy filter as pointed by Ivan
  
  
  
  
  	
  - add support of event on CLI remoting authentication
  
  
  	
  adjust tests by moving the helper class used to spy on events
  
  
  
  
  	
  - as mentioned Yvan, the code had some problems with null checking, so the approach is changed in order to encapsulate all that internal mechanism
  
  
  
  
  	
  - add javadoc
  
  
  	
  open the getUserDetailsForImpersonation from the User (will let the SSHD module to retrieve UserDetails from that)
  
  
  
  
  	
  - remove single quote in log messages
  
  
  
  
  	
  - basic corrections requested by Jesse
  
  
  
  
  	
  - just another typo
  
  
  
  
  	
  - adjust the javadoc for SecurityListener events
  
  
  
  
  	
  - add the link to Jenkins#Anonymous
  
  
  
  
  	
  - add link (not using see)
  
  
  
  
  	
  - update comment on the isAnonymous as we (me + Oleg) do not find a best place at the moment
  
  
  
  
  	
  - put the new method isAnonymous in ACL instead of Functions
  
  
  
  
  	
  - little typo
  
  
  	
  add requirement about the SecurityContext authentication
  
  
  
  
  

Code changed in jenkins
User: Wadeck Follonier
Path:
core/src/main/java/hudson/Functions.java
core/src/main/java/hudson/cli/CLICommand.java
core/src/main/java/hudson/cli/ClientAuthenticationCache.java
core/src/main/java/hudson/cli/LoginCommand.java
core/src/main/java/hudson/cli/LogoutCommand.java
core/src/main/java/hudson/model/User.java
core/src/main/java/hudson/security/ACL.java
core/src/main/java/hudson/security/BasicAuthenticationFilter.java
core/src/main/java/jenkins/security/BasicHeaderApiTokenAuthenticator.java
core/src/main/java/jenkins/security/SecurityListener.java
test/src/test/java/hudson/security/CliAuthenticationTest.java
test/src/test/java/jenkins/security/BasicHeaderProcessorTest.java
test/src/test/java/jenkins/security/SpySecurityListener.java
http://jenkins-ci.org/commit/jenkins/b7f42b2e59b2081782d6e51da18b0c93808d98da
Log:
JENKINS-27027 Notify the SecurityListener on authentication (#3074)

• JENKINS-27026 Notify the SecurityListener in case of Token based authentication success

• due the current version of the method, the UserDetails required for the event was not accessible. In order to stay with the same API in SecurityListener, two "protected" methods were created to split the job and let the UserDetails accessible

• - add test to ensure the SecurityListener is called for REST Token but also for regular basic auth

• - remove the comment about the split, will be put in GitHub comment instead

• - add check for anonymous call instead of just putting a comment

• remove the constructor in the dummy
• add link to PR from Daniel to simplify a call

• - separate the before/after to save one clear and be more explicit

• put more meaning in the assertLastEventIs method by explicitly say we will remove the last event

• - add comment about why we do not fire the "failedToAuthenticated" in the case of an invalid token (tips: it's because it could be a valid password)

• - also add the authenticated trigger on legacy filter as pointed by Ivan

• - add support of event on CLI remoting authentication

• adjust tests by moving the helper class used to spy on events

• - as mentioned Yvan, the code had some problems with null checking, so the approach is changed in order to encapsulate all that internal mechanism

• - add javadoc

• open the getUserDetailsForImpersonation from the User (will let the SSHD module to retrieve UserDetails from that)

• - remove single quote in log messages

• - basic corrections requested by Jesse

• - just another typo

• - adjust the javadoc for SecurityListener events

• - add the link to Jenkins#Anonymous

• - add link (not using see)

• - update comment on the isAnonymous as we (me + Oleg) do not find a best place at the moment

• - put the new method isAnonymous in ACL instead of Functions

• - little typo

• add requirement about the SecurityContext authentication

[jenkins-infra-bot]

[Original depends_on from Jira: JENKINS-20999]