Authentication overview
JIRA provides various mechanisms for authenticating users and applications that interact with its services, including its REST APIs. The choice of authentication method depends on the client type (human user, script, or third-party application) and the required level of security and authorization scope. Understanding these methods is crucial for securely integrating external systems or automating workflows within JIRA.
Authentication in JIRA establishes the identity of the requester, while authorization determines what actions that identified requester is permitted to perform. Both are integral to maintaining the security and integrity of project data and configurations within JIRA environments. Atlassian, the company behind JIRA, provides extensive documentation for developers and administrators on setting up and managing these authentication methods to ensure secure access to JIRA Cloud products.
Supported authentication methods
JIRA supports several authentication methods, each suitable for different use cases and security requirements. The primary methods for API access include API tokens, OAuth 2.0, and HTTP Basic Authentication. Session-based authentication is typically used for browser-based user interactions.
| Method | When to Use | Security Level |
|---|---|---|
| API Token | Automated scripts, bots, command-line tools, local development. | Medium. Requires careful management to prevent exposure. More secure than passwords for automation. |
| OAuth 2.0 (3LO) | Third-party web applications, mobile apps, integrations requiring delegated access without sharing user credentials. | High. Provides granular permission control and token expiration. See OAuth 2.0 documentation for further details on its security model. |
| HTTP Basic Authentication | Legacy integrations, simple scripts where API tokens are not feasible, or for JIRA Server/Data Center instances not Cloud. (Note: Atlassian recommends API tokens for Cloud instances instead of passwords for Basic Auth.) | Low to Medium. Transmits credentials as Base64 encoded, susceptible to interception if not over HTTPS. Atlassian recommends API tokens over Basic Auth with passwords for JIRA Cloud. |
| Session-based (Cookie) | Browser-based user interface interactions, not typically for API calls from external applications. | High for interactive user sessions, managed by JIRA's application security. |
Getting your credentials
API Tokens
To generate an API token for JIRA Cloud, follow these steps:
- Log in to your Atlassian account.
- Navigate to your profile and then to 'Manage your account'.
- Select 'Security' from the navigation menu.
- Under 'API tokens', click 'Create and manage API tokens'.
- Click 'Create API token', give it a descriptive label, and copy the generated token immediately. It will only be shown once.
The generated API token acts as a substitute for your password when making API requests. You will use your Atlassian account email as the username and the generated API token as the password in your requests. For detailed instructions, refer to the Atlassian documentation on managing API tokens.
OAuth 2.0 Credentials
Implementing OAuth 2.0 for JIRA involves registering your application with Atlassian and obtaining a Client ID and Client Secret. This process typically requires configuring an OAuth 2.0 integration within your Atlassian developer console. The steps generally involve:
- Register your application on the Atlassian Developer Console.
- Configure your application's permissions (scopes) and redirect URLs.
- Obtain a Client ID and Client Secret for your application.
- Implement the OAuth 2.0 authorization flow in your application to request user consent and exchange an authorization code for an access token and refresh token.
The OAuth 2.0 specification describes the general flow for obtaining delegated access, and JIRA's implementation follows the OAuth 2.0 Authorization Framework. This method is recommended for third-party integrations as it allows users to grant specific permissions to applications without sharing their JIRA login credentials directly.
HTTP Basic Authentication
For HTTP Basic Authentication with JIRA Cloud, you would typically use your Atlassian account email as the username and an API token as the password. While JIRA Server and Data Center might still accept passwords directly for Basic Auth, Atlassian strongly recommends using API tokens for Cloud instances due to enhanced security practices. The credentials (email and API token) are Base64 encoded and sent in the Authorization header of your HTTP requests.
Authenticated request example
Here's an example of an authenticated cURL request to the JIRA Cloud REST API using an API token and HTTP Basic Authentication:
curl --request GET \
--url 'https://your-domain.atlassian.net/rest/api/3/myself' \
--user '[email protected]:YOUR_API_TOKEN' \
--header 'Accept: application/json'
Replace your-domain.atlassian.net with your JIRA Cloud instance domain, [email protected] with your Atlassian account email, and YOUR_API_TOKEN with the API token you generated. This request fetches information about the currently authenticated user.
For OAuth 2.0, requests involve including an Authorization: Bearer <ACCESS_TOKEN> header. An example using cURL after obtaining an access token:
curl --request GET \
--url 'https://api.atlassian.com/ex/jira/YOUR_CLOUD_ID/rest/api/3/myself' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Accept: application/json'
Replace YOUR_CLOUD_ID with your specific Atlassian Cloud ID, which can be found in the URL when accessing your JIRA instance or through the Atlassian developer console. <YOUR_ACCESS_TOKEN> would be the access token obtained through the OAuth 2.0 flow. For specific endpoint details, consult the JIRA Cloud Platform REST API reference.
Security best practices
Adhering to security best practices is essential when integrating with JIRA:
- Use API Tokens over Passwords: For automated access and scripts, always use API tokens instead of your Atlassian account password, especially for JIRA Cloud. API tokens can be revoked independently without changing your main password. Atlassian's guidance on API tokens reinforces this.
- Implement OAuth 2.0 for Third-Party Apps: For applications that need to access JIRA on behalf of users, OAuth 2.0 (3LO) is the most secure method. It allows granular control over permissions and avoids sharing user credentials with third-party applications. The Atlassian OAuth 2.0 (3LO) documentation provides comprehensive implementation details.
- Restrict Token/Client Scope: When creating API tokens or configuring OAuth 2.0 applications, grant only the minimum necessary permissions (scopes) required for the integration to function. This principle of least privilege limits the potential impact if a credential is compromised.
- Securely Store Credentials: API tokens, Client Secrets, and access tokens should never be hardcoded in source code or committed to version control. Use environment variables, secure configuration management tools, or dedicated secret management services for storing and retrieving these credentials.
- Rotate Credentials Regularly: Periodically rotate API tokens and OAuth 2.0 secrets. This reduces the window of exposure if a credential is inadvertently compromised.
- Monitor API Usage: Keep an eye on API usage logs and audit trails within JIRA for any unusual activity that might indicate unauthorized access or misuse of credentials.
- Use HTTPS: All communication with the JIRA API must occur over HTTPS to encrypt data in transit, protecting credentials and sensitive information from interception. This is a fundamental web security best practice, emphasized by organizations like the Mozilla Developer Network on secure contexts.
- Error Handling: Implement robust error handling in your applications to gracefully manage authentication failures and avoid exposing sensitive information in error messages.