HackerOne Authentication: Methods, Setup, & Best Practices

Authentication overview

HackerOne provides a platform for organizations to manage vulnerability disclosure programs and bug bounties, connecting them with security researchers. Authentication on HackerOne ensures that only authorized users and applications can access program data, submit reports, or manage program settings. The platform supports various authentication mechanisms to accommodate different user types and integration needs, from individual researcher logins to programmatic API access for enterprise systems.

For human users, HackerOne integrates with several identity providers and standard login methods. For automated interactions, such as integrating vulnerability data into an existing security information and event management (SIEM) system or a ticketing platform, HackerOne's API requires token-based authentication. This distinction allows for both interactive user sessions and secure, scriptable access to the platform's features, aligning with the principle of least privilege by enabling specific permissions for API tokens distinct from user accounts.

Supported authentication methods

HackerOne supports a range of authentication methods tailored for its diverse user base, which includes security researchers, program administrators, and integrated applications. The choice of method depends on the user's role and the nature of the interaction (interactive login vs. programmatic API access).

User authentication

• Email and Password: Standard login method for HackerOne accounts, secured with best practices like strong password requirements and optional multi-factor authentication.
• SAML (Security Assertion Markup Language): Primarily used by enterprise organizations for single sign-on (SSO), allowing users to authenticate via their corporate identity provider (IdP) and gain access to HackerOne without separate credentials. This streamlines user management and enhances security by centralizing identity control, as described in the Microsoft Azure SAML authentication overview.
• Google OAuth: Allows users to sign in using their existing Google account credentials, simplifying the registration and login process.
• GitHub OAuth: Similar to Google OAuth, this method enables users to authenticate via their GitHub account, which is common for developers and researchers.

API authentication

For programmatic access, the HackerOne API utilizes token-based authentication. This method involves generating specific API tokens within the HackerOne platform and using them in HTTP requests. API tokens are designed for secure automation and integration, allowing external systems to interact with HackerOne data and functionalities.

• API Tokens (Identifier + Access Token): The primary method for authenticating API requests. Each API token consists of an identifier and a secret access token. These credentials must be included in the HTTP request headers for authentication. The HackerOne API authentication documentation provides detailed instructions on how to structure requests using these tokens.

The following table summarizes the supported authentication methods, their typical use cases, and their general security level:

Getting your credentials

The process for obtaining authentication credentials on HackerOne varies based on the method you intend to use.

For user accounts (Email/Password, Google OAuth, GitHub OAuth)

If you are a new user, you can create an account directly on the HackerOne platform using your email and a password. Alternatively, you can opt to sign up and log in using your existing Google or GitHub accounts, which will prompt you to authorize HackerOne to access basic profile information from those services. Existing users can log in directly with their chosen method.

For SAML SSO

SAML SSO is typically configured by an organization's administrator. This involves setting up HackerOne as a service provider (SP) within your organization's identity provider (IdP). The administrator will exchange metadata with HackerOne to establish trust and configure assertions. Once configured, users within that organization can log in via their corporate portal or a specific HackerOne SSO URL.

For API tokens

API tokens are generated within the HackerOne platform's user interface. The specific steps are as follows, as detailed in the HackerOne API token creation guide:

1. Log in to your HackerOne account.
2. Navigate to your User Settings or Organization Settings, depending on whether you need a personal API token or an organizational one.
3. Locate the section for API Tokens or Developer Settings.
4. Click on Generate New Token.
5. Provide a descriptive name for your token to help identify its purpose (e.g., "Jira Integration Token," "Reporting Automation").
6. Review and select the necessary permissions for the token. Adhere to the principle of least privilege by granting only the minimum permissions required for the token's intended function.
7. Confirm the generation. HackerOne will display the Identifier and the Access Token. It is crucial to copy both immediately, as the Access Token will only be shown once and cannot be retrieved later for security reasons.
8. Store these credentials securely in an environment variable or a secure secrets management system.

Authenticated request example

When making API requests to HackerOne, the API token (consisting of an identifier and an access token) is typically sent in the Authorization header using Basic Authentication. This is a common pattern for token-based authentication in RESTful APIs, as outlined in the IETF RFC 7617 for HTTP Basic Authentication.

Here's an example of an authenticated API request using curl to fetch reports from a HackerOne program:

curl -X GET \
  'https://api.hackerone.com/v1/reports' \
  -H 'Authorization: Basic <BASE64_ENCODED_IDENTIFIER:ACCESS_TOKEN>' \
  -H 'Accept: application/json'

In this example:

• <BASE64_ENCODED_IDENTIFIER:ACCESS_TOKEN> should be replaced with the Base64 encoded string of your API token identifier followed by a colon and then your access token. For example, if your identifier is my_identifier and your access token is my_access_token, you would encode my_identifier:my_access_token.
• The -H 'Accept: application/json' header indicates that the client prefers a JSON response.

Many programming languages provide libraries or built-in functions to handle Base64 encoding. For instance, in Python, you might use base64.b64encode(f"{identifier}:{access_token}".encode()).decode().

Security best practices

Adhering to security best practices for authentication on HackerOne is essential to protect sensitive vulnerability data and maintain the integrity of your programs.

• Enable Multi-Factor Authentication (MFA): For all human user accounts, enable MFA. This adds an extra layer of security by requiring a second verification method (e.g., a code from a mobile app or a physical security key) in addition to the password. HackerOne supports various MFA options, significantly reducing the risk of unauthorized access even if a password is compromised.
• Use Strong, Unique Passwords: Ensure all user accounts use strong, unique passwords that are not reused across other services. Password managers can assist users in generating and storing complex passwords securely.
• Principle of Least Privilege for API Tokens: When generating API tokens, grant only the minimum necessary permissions required for the token's specific task. Avoid giving broad administrative access to tokens that only need to read reports or submit updates. Regularly review token permissions and revoke any unnecessary access.
• Securely Store API Tokens: Never hardcode API tokens directly into source code. Instead, use environment variables, secure configuration files, or dedicated secrets management services (e.g., AWS Secrets Manager, Azure Key Vault, HashiCorp Vault). This prevents tokens from being exposed in version control systems or insecure deployments.
• Rotate API Tokens Regularly: Implement a schedule for rotating API tokens. Regular rotation limits the window of exposure if a token is inadvertently compromised. When rotating, generate a new token, update all systems using the old token, and then revoke the old token.
• Monitor API Token Usage: If available, monitor the logs for API token usage to detect unusual activity or potential unauthorized access attempts. Anomalies could indicate a compromised token.
• Leverage SSO for Enterprise Users: For organizations, utilize SAML SSO to centralize identity management. This allows your corporate identity provider to enforce password policies, MFA, and user provisioning, reducing the administrative burden and enhancing security on the HackerOne platform.
• Educate Users: Provide training and guidelines to users on secure authentication practices, including recognizing phishing attempts and the importance of reporting suspicious activity.
• Revoke Access Promptly: When an employee or contractor leaves the organization, or if an API token is no longer needed, revoke their access immediately. Timely revocation prevents former personnel or deprecated systems from retaining access to sensitive data.