Skip to content

Conversation

nimish-ks
Copy link
Member

@nimish-ks nimish-ks commented Aug 25, 2025

🔍 Overview

This PR adds support for authenticating with the Phase API via external third-parry identity systems, starting with AWS IAM.

This has been a much requested feature that will make it easier for users integrating Phase with their existing AWS infrastructure.

Example flow:

  • Client calls the get_calleridentity() to fetch an AWS Sigv4 signed API request
  • Client sends the signed request to the Phase API
  • Phase backend sends the signed request to AWS STS API endpoint and receives UserId, AccountId, Arn.
  • Phase API validates the client identity and checks for a entity trust relationship. If client is trusted, return Access Token. If not, deny access.
  • Client uses the Access Token to access secrets.

Benefits:

  • Dynamic secret 0 management
  • No-pre provisioning of Phase Access Tokens.

💡 Proposed Changes

  • Added support for external identities
  • AWS IAM external identity
  • Identities permissions in Role-based Access Control

🖼️ Screenshots or Demo

AWS IAM external identity creation flow:

image

Service Account - enable server-side key management state

image

Service Account - no identities enabled state

image

Service Account - AWS IAM external identity

image

❓ Open Questions

  • Can we improve how the code is structured to make it faster and easier to roll our new external identity providers?
  • UI improvements - the current UI is functional but not quite up to our standards
  • Given we are dynamically generating tokens and showing the ones that have been expired, we should add a larger table with pages and move the tokens into it's sub section
  • Is there an edge case where we can expand our test suite for AWS IAM?

🎯 Reviewer Focus

  • Review database models and migration - backend/api/migrations/0107_identity_serviceaccount_identities.py
  • Audit crypto utils in backend/api/utils/crypto.py
  • Identities permission RBAC policies for Phase managed roles and CRUD enforcement
  • Human readable time conversion (eg. 1m -> 60s) utils in frontend/utils/ttl.ts
  • GraphQL mutations - compound queries / unions (common, provider specific config)

💚 Did You...

  • Ensure linting passes (code style checks)?
  • Update dependencies and lockfiles (if required)
  • Update migrations (if required)
  • Regenerate graphql schema and types (if required)
  • Verify the app builds locally?
  • Manually test the changes on different browsers/devices?

- Introduced a new module with functions to parse, format, and validate TTL strings, enhancing the handling of time-related data.
- Added examples for common TTL formats, improving usability and clarity for developers working with time-to-live values.
@nimish-ks nimish-ks self-assigned this Aug 25, 2025
@nimish-ks nimish-ks marked this pull request as draft August 25, 2025 16:53
@nimish-ks nimish-ks changed the base branch from main to feat--service-account-kms August 25, 2025 16:54
…rations

- Introduced a new IdentityProviders class to encapsulate configurations for supported identity providers, enhancing the structure for identity authentication.
- Implemented methods to retrieve all providers, supported providers, and specific provider configurations, improving the usability and maintainability of identity management.
- Introduced a new Identity model to manage third-party identity configurations at the organization level, allowing multiple service accounts to be associated with a single identity.
- Added fields for provider-specific configurations, token settings, and methods to retrieve trusted principals, enhancing the flexibility and usability of identity management.
…conversion

- Introduced new functions for XORing byte strings, splitting secrets into shares, generating random hex strings, and converting Ed25519 keys to Curve25519 format.
- Enhanced cryptographic capabilities by implementing a wrapping function for encrypting hex-encoded shares, improving the overall utility of the crypto module.
- Introduced a new function `list_sts_endpoints` that retrieves and formats a list of STS endpoints based on botocore's endpoint metadata.
- The function enhances AWS identity management by providing a structured output of available STS endpoints, including region codes and names.
- Added functions for resolving service accounts and identities, minting service account tokens, and handling token expiration.
- Enhanced the identity management system by providing a structured approach to create and manage service account tokens, including cryptographic operations for secure token generation.
- Added a new endpoint `aws_iam_auth` to handle SigV4-signed requests for service account authentication.
- Implemented request validation, signature verification, and integration with AWS STS for identity validation.
- Enhanced error handling for various failure scenarios, ensuring robust responses for invalid requests and configurations.
- Introduced new mutations for creating, updating, and deleting identities, enhancing the identity management capabilities.
- Added queries to retrieve identities, AWS STS endpoints, and identity providers, improving the overall functionality of the identity system.
- Updated the GraphQL schema to include new types and resolvers for better integration with identity-related operations.
- Added a new URL path for the `aws_iam_auth` endpoint, enabling access to AWS IAM authentication for identity management.
- This integration enhances the existing identity system by providing a dedicated route for service account authentication.
…e operations

- Introduced new mutations for creating, updating, and deleting identities, enhancing the identity management capabilities.
- Implemented permission checks to ensure users have the necessary rights for identity operations.
- Updated the GraphQL schema to include the new IdentityType and associated mutations, improving integration with identity-related functionalities.
- Added IdentityProviderType to represent identity providers with relevant fields.
- Introduced IdentityType to manage identity configurations, including a resolver for provider-specific settings.
- Updated ServiceAccountType to include a list of identities, improving the integration of identity management within service accounts.
- Enhanced the UpdateServiceAccountMutation to accept an optional list of identity IDs.
- Implemented logic to associate specified identities with the service account during the update process, improving identity management capabilities within service accounts.
- Introduced the "Identities" role with permissions for create, read, update, and delete operations in the default roles configuration.
- Updated multiple sections of the roles.py file to ensure consistent access control for identity management functionalities.
- Implemented a new resolver function to retrieve identities associated with a specific organisation.
- Added permission checks to ensure users have access to read identities, enhancing security and access control within the identity management system.
- Implemented a resolver to dynamically return AWS STS endpoints using botocore's endpoint resolver data.
- Added a resolver to retrieve all supported identity providers, enhancing the identity management capabilities within the GraphQL API.
- Created a new IdentityPage component to manage identities within an organisation.
- Integrated permission checks for reading, creating, updating, and deleting identities.
- Added functionality to display, edit, and delete identities, along with a provider selection dialog for creating new identities.
- Enhanced user experience with empty state handling and toast notifications for actions.
- Added ServiceAccountIdentities component to display associated identities for the service account.
- Integrated a CopyButton for the service account ID, improving user experience by allowing easy copying of the ID to the clipboard.
…iated identities

- Added ServiceAccountIdentities component to manage third-party identities linked to a service account.
- Integrated search functionality and toggle options for selecting identities.
- Enhanced user experience with empty state handling and modal dialogs for identity management.
…roviders

- Introduced the IdentityProviderSelector component to facilitate the selection of identity providers for creating new identities.
- Integrated AWS IAM provider selection with a dialog for additional configuration.
- Enhanced user experience with a modal interface and improved accessibility for managing identity providers.
- Introduced the ProviderCards component to render a grid of identity providers.
- Integrated Apollo Client to fetch identity provider data via GraphQL.
- Enhanced user interaction with clickable cards for selecting providers, improving the identity selection process.
- Introduced the AwsIamIdentityDialog component to facilitate the creation and updating of AWS IAM identities.
- Integrated Apollo Client for GraphQL mutations and queries to manage identity configurations.
- Enhanced user experience with a modal interface for configuring trusted entities, token settings, and STS endpoints.
- Implemented form validation and state management for identity attributes, improving usability and error handling.
- Introduced mutations for creating, updating, and deleting identities, enhancing the identity management capabilities.
- Added queries to retrieve AWS STS endpoints, identity providers, and organisation-specific identities, improving data accessibility.
- Enhanced the service account detail query to include associated identities, providing a comprehensive view of identity relationships.
… tab

- Removed unused organisation context import and related code for improved clarity.
- Added a new tab for 'Third-party Identities' to enhance navigation within the access layout.
- Added new queries for retrieving identities associated with an organisation and AWS STS endpoints, improving data accessibility.
- Introduced new types for Identity and IdentityProvider, enhancing the schema for identity management.
- Updated existing queries and mutations for better readability and structure, facilitating easier maintenance and understanding of the schema.
…eries

- Added mutations for creating, updating, and deleting identities, enhancing identity management capabilities.
- Introduced new queries for retrieving AWS STS endpoints, identity providers, and organisation-specific identities, improving data accessibility.
- Updated service account detail query to include associated identities, providing a comprehensive view of identity relationships.
- Introduced the Identity model to manage identity attributes, including provider, name, and configuration.
- Established a ManyToMany relationship between ServiceAccount and Identity, allowing for better management of associated identities.
…ServiceAccountDialog

- Eliminated commented-out code for the third-party authentication toggle to improve code clarity and maintainability.
…tities component

- Changed the label from "third-party identities" to "external identities" for improved clarity and consistency in terminology.
- Changed the label from "Third-party Identities" to "External Identities" for improved clarity and consistency in terminology.
- Changed the label from "Third-party identities" to "External identities" for improved clarity and consistency in terminology.
- Introduced comprehensive unit tests for the AWS IAM authentication functionality, covering various scenarios including valid authentication, error handling for malformed requests, and validation of service account configurations.
- Ensured robust testing for edge cases such as missing headers, invalid payloads, and service account resolution failures, enhancing the reliability of the authentication process.
@nimish-ks nimish-ks changed the base branch from feat--service-account-kms to main August 27, 2025 08:59
- Added a new test suite for the AWS IAM authentication logic, covering various scenarios including invalid JSON payloads, missing account IDs, and signature expiration.
- Ensured comprehensive testing of edge cases such as STS endpoint mismatches, untrusted principals, and token minting failures, enhancing the reliability of the authentication process.
- Removed the previous test file for AWS IAM authentication to consolidate testing efforts in a single location.
- Created new modules for identity management and AWS identity handling, laying the groundwork for future authentication and identity features.
- These modules will facilitate the implementation of identity-related functionalities in the backend API.
- Updated mutation names for creating, deleting, and updating identities to include "Ext" prefix, enhancing clarity and consistency in the identity management module.
- Renamed mutation operations for creating, deleting, and updating identities to include the "Ext" prefix, enhancing clarity and consistency in the identity management module.
- Updated corresponding types and documents to reflect these changes.
@nimish-ks nimish-ks changed the title feat: identities feat: identities - AWS IAM Aug 27, 2025
@nimish-ks nimish-ks changed the title feat: identities - AWS IAM feat: external identities - AWS IAM Aug 27, 2025
@nimish-ks nimish-ks changed the base branch from main to feat--service-account-kms August 27, 2025 15:55
@nimish-ks nimish-ks marked this pull request as ready for review August 27, 2025 17:34
@nimish-ks
Copy link
Member Author

@cursor review

Copy link

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no bugs!


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant