Jira Auth Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to composer.json:

   composer require dg/jira-auth-bundle
   

   Register it in config/bundles.php (Symfony 4+):

   return [
       // ...
       DG\JiraAuthBundle\DGJiraAuthBundle::class => ['all' => true],
   ];
   

2. Routing Import the bundle’s routes in config/routes.yaml:

   jira_auth:
       resource: "@DGJiraAuthBundle/Resources/config/routing.yml"
       prefix: /jira
   

3. Configuration Publish the default config (if needed) and override in config/packages/dg_jira_auth.yaml:

   dg_jira_auth:
       jira_url: "https://your-jira-instance.atlassian.net"
       client_id: "%env(JIRA_CLIENT_ID)%"
       client_secret: "%env(JIRA_CLIENT_SECRET)%"
       callback_path: "/jira/callback"
   

4. First Use Case Redirect users to Jira for OAuth:

   use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
   
   // In a controller
   return $this->redirectToRoute('jira_auth_login', [], UrlGeneratorInterface::ABSOLUTE_URL);
   

Implementation Patterns

Workflow: OAuth Flow

1. Initiate Login Use the jira_auth_login route to trigger the OAuth flow. The bundle handles:

   • Generating a Jira auth URL.
   • Storing state for CSRF protection.

2. Callback Handling After Jira redirects back to your callback_path, the bundle:

   • Validates the state.
   • Exchanges the code for an access token.
   • Stores the token in the session (default: jira_auth_token).

3. User Data Fetching Manually fetch user data (the bundle doesn’t auto-map Jira users to Symfony users):

   use DG\JiraAuthBundle\Service\JiraAuthService;
   
   $jiraAuth = $this->container->get(JiraAuthService::class);
   $userData = $jiraAuth->getUserInfo(); // Requires valid session token
   

Integration Tips

• Symfony Security Component Extend the bundle’s JiraAuthService to integrate with Symfony’s security system:

  // src/Security/JiraAuthenticator.php
  use DG\JiraAuthBundle\Service\JiraAuthService;
  
  class JiraAuthenticator extends AbstractAuthenticator
  {
      public function supports(Request $request): ?bool
      {
          return $request->getPathInfo() === '/jira/callback';
      }
  
      public function authenticate(Request $request): Passport
      {
          $jiraAuth = $this->container->get(JiraAuthService::class);
          if (!$jiraAuth->isAuthenticated()) {
              throw new AuthenticationException('Jira auth failed');
          }
          return new Passport(new User($jiraAuth->getUserInfo()));
      }
  }
  

• Token Storage Override the session storage key in config:

  dg_jira_auth:
      token_storage_key: "custom_jira_token_key"
  

• API Rate Limits Cache Jira API responses (e.g., user info) to avoid hitting rate limits:

  $cache = $this->container->get('cache.app');
  $userInfo = $cache->get('jira_user_info', function() use ($jiraAuth) {
      return $jiraAuth->getUserInfo();
  });
  

Gotchas and Tips

Pitfalls

1. Session Token Expiry

   • The bundle stores tokens in the session, which may expire if the session times out. Implement token refresh logic:

     if (!$jiraAuth->isAuthenticated()) {
         // Redirect to login or refresh token
     }
     

2. Missing User Mapping

   • The bundle doesn’t auto-create Symfony users. Manually map Jira users:

     $jiraUser = $jiraAuth->getUserInfo();
     $symfonyUser = $this->userRepository->findOneBy(['jira_id' => $jiraUser['accountId']]);
     

3. CSRF State Validation

   • Ensure callback_path matches the config. Mismatches cause auth failures.

4. Jira API Changes

   • Atlassian may modify OAuth endpoints. Test thoroughly after Jira updates.

Debugging

• Enable Debugging Set debug: true in config to log OAuth flow details:

  dg_jira_auth:
      debug: true
  

• Token Validation Manually verify tokens:

  $token = $this->container->get('session')->get('jira_auth_token');
  $response = $jiraAuth->callJiraApi('/rest/auth/1/session', 'GET', ['Authorization' => "Bearer $token"]);
  

Extension Points

1. Custom User Provider Extend JiraAuthService to fetch additional user attributes:

   class CustomJiraAuthService extends JiraAuthService
   {
       public function getUserInfo()
       {
           $data = parent::getUserInfo();
           $data['custom_field'] = $this->callJiraApi('/rest/api/2/user?accountId=' . $data['accountId']);
           return $data;
       }
   }
   

2. Multi-Tenant Support Store tenant-specific tokens in session:

   $this->container->get('session')->set('jira_auth_token_' . $tenantId, $token);
   

3. Webhook Validation Validate Jira webhook signatures if using Jira’s webhook feature:

   use Symfony\Component\HttpFoundation\Request;
   
   $request = $this->container->get('request_stack')->getCurrentRequest();
   $signature = $request->headers->get('X-Atlassian-Event-Key');
   // Implement signature validation logic