[RFC] Support for API Keys in OpenSearch Security Plugin

[cwperks]

Introduction

This proposal seeks to introduce API Key authentication as a feature within the OpenSearch Security Plugin, responding to significant community demand as evidenced by the number of thumbs up reactions on #1504. This feature aims to enhance security and usability for OpenSearch users by providing a more flexible and secure method of authentication for various use cases, including scheduled jobs.

Background

The OpenSearch Security Plugin currently supports a variety of authentication methods including HTTP Basic Authentication, JWT, SAML, OpenID Connect and others. However, the lack of API Key support limits the flexibility and ease of use for developers and administrators, particularly in scenarios involving automated processes or services that require access to the OpenSearch cluster without human intervention.

API Keys are a widely adopted method for service-to-service authentication, offering a secure and convenient way to grant access to APIs without exposing user credentials. They are particularly useful for scheduled jobs, where a job needs to authenticate with OpenSearch to perform operations in a known context.

Proposal

We propose the addition of an API Key authentication mechanism to the OpenSearch Security Plugin with the following features:

1. API Key Generation

• Users can generate API Keys through a REST API endpoint or the OpenSearch Dashboards UI.
• The generation process should allow users to specify:
  • The name of the API Key for identification.
  • An optional expiration date/time.
  • Permissions associated with the API Key, leveraging the existing roles and permissions model in OpenSearch Security.

2. API Key Storage

• Generated API Keys will be securely stored in the OpenSearch cluster with their metadata, including the creator, creation date, expiration date, and associated permissions.

3. API Key Usage

• API Keys can be used by including them in the request header when making calls to the OpenSearch cluster.
• The Security Plugin will authenticate requests by validating the API Key against the stored keys and their associated permissions.

4. API Key Revocation

• Users can revoke API Keys at any time before their expiration through the REST API or the OpenSearch Dashboards UI.
• Revoked keys will be immediately invalidated and cannot be used for authentication.

5. UX Component

• The OpenSearch Dashboards UI will include a new section for managing API Keys, allowing users to:
  • Generate new API Keys.
  • List all their API Keys with their status (active, expired, revoked) and expiration dates.
  • Revoke active API Keys.

6. Scheduled Jobs Support

• API Keys can be used to authenticate scheduled jobs, allowing these jobs to run in a known context with specific permissions.
• This will enable more secure and controlled access for automated processes interacting with the OpenSearch cluster.

Security Considerations

• API Key transmission will be secured using HTTPS to prevent exposure.
• The storage of API Keys will be encrypted at rest (as is done with encrypted passwords using bcrypt).
• Audit logging will be enhanced to include all operations related to API Key management (generation, usage, revocation).

Conclusion

The introduction of API Key support in the OpenSearch Security Plugin will significantly enhance the security and usability of OpenSearch, particularly for automated processes and services. This feature will provide a flexible, secure, and user-friendly method of authentication, aligning with modern security practices and meeting the needs of the OpenSearch community.

We invite comments, suggestions, and contributions from the community to refine and implement this proposal.

[cwperks]

1. UX for Listing API Keys for a User

Page Layout:

• Title: "API Keys Management"
• Primary action button: "Generate New API Key"
• Below the primary action, a table lists all the API Keys associated with the user's account.

Table Columns:

• API Key Name
• Status (Active, Expired, Revoked)
• Creation Date
• Expiration Date
• Actions (with icons for "Revoke" and "View Details")

Functionality:

• Each row represents an API Key.
• The "Revoke" action button is available for active API Keys.
• Hovering over an API Key row highlights it, indicating it's selectable for more details.
• Pagination controls are available at the bottom of the table if there are more API Keys than can be displayed on one page.

2. UX for Revoking an API Key

Modal Dialog:

• Triggered by clicking the "Revoke" action icon next to an API Key.
• Title: "Confirm API Key Revocation"
• Message: "Are you sure you want to revoke access for API Key '[API Key Name]'? This action cannot be undone."
• Actions: "Cancel" (secondary action, closes modal) and "Revoke" (primary action, red button).

Functionality:

• Clicking "Revoke" immediately revokes the API Key and closes the modal.
• A toast notification appears to confirm the revocation: "API Key '[API Key Name]' has been successfully revoked."

3. UX for Generating an API Key

Page/Modal Layout:

• Accessed by clicking the "Generate New API Key" button.
• Title: "Generate New API Key"
• Form Fields:
  • API Key Name (text input)
  • Expiration (date-time picker or duration input, optional)
  • Permissions - (either select existing roles or fill out custom permissions similar to role creation UX. If role is selected, permissions from the role are frozen at that point in time.)
• Actions: "Cancel" (secondary action) and "Generate" (primary action).

Functionality:

• Upon filling out the form and clicking "Generate," the API Key is created.
• A modal/dialog shows the newly created API Key with a message: "Your API Key has been generated successfully. Please copy your new API Key now. You won’t be able to see it again."
• The API Key is displayed in a read-only text field with a copy button next to it.
• Actions: "Close" (closes the modal and returns to the API Keys management page).

[stephen-crawford]

[Triage] Hi @cwperks thank you for creating this very detailed RFC. Hopefully we can get some community input for this and move forward from there.

[merlinz01]

This RFC looks great as far as I'm concerned; I would be happy to see it implemented.

I noticed on this issue that the author says "API Keys are not generally considered secure". What is the rationale for considering them less secure than username/password authentication?