Qalá Best Practices

This guide outlines best practices for using Qalá to manage your secrets securely and efficiently.

Setting Up Your Environment

Project Organization

• Use meaningful project names: Choose descriptive names that reflect your application or service.
• Create separate projects for distinct applications: This ensures better access control and minimizes cross-contamination risk.
• Document your project structure: Add descriptions to projects that clarify their purpose.

Environment Configuration

• Create environments that mirror your deployment pipeline: Typical environments include:
  • development - For local development
  • staging - For pre-production testing
  • production - For live application use
• Restrict access to production environments: Limit the number of team members who can access production secrets.
• Use consistent naming conventions across environments to ensure smooth transitions.

Secret Management

Naming Conventions

• Use descriptive names: Choose names that clearly indicate the purpose of the secret.
• Use consistent prefixes: For example, DB_* for database credentials, API_* for API keys.
• Avoid using actual values in names: Never include sensitive data in the secret name itself.

Value Security

• Generate strong secrets: Use high-entropy values for passwords and keys.

  <SERVICE>_<TYPE>_<ENVIRONMENT>_<DETAIL>

• Avoid hardcoding secrets: Never commit secrets to source code repositories.

• Use the secret rotation feature for credentials that require periodic updates.

Secret Descriptions

• Add detailed descriptions: Include information about:
  • What the secret is used for
  • Who owns or manages the external service
  • When it was last updated manually
  • Any expiration dates

Integration with Applications

Direct API Integration

When integrating Qalá directly with your application code:

<SERVICE>_<TYPE>_<ENVIRONMENT>_<DETAIL>

Local Development

For local development:

1. Use the CLI to export secrets to .env file:

   <SERVICE>_<TYPE>_<ENVIRONMENT>_<DETAIL>

2. Use .env files with gitignore: Add .env to your .gitignore file.

3. Use the vault for offline development:

   <SERVICE>_<TYPE>_<ENVIRONMENT>_<DETAIL>

Security Best Practices

API Keys and Authentication

• Rotate API keys regularly: Create a schedule for key rotation.
• Use the most restrictive permissions necessary: Don't use admin credentials for read-only operations.
• Set environment variables for API keys: Never hardcode them in your application.

Access Control

• Implement the principle of least privilege: Give users access only to what they need.
• Audit access regularly: Review who has access to which projects and environments.
• Revoke access immediately when team members change roles or leave the organization.

Monitoring and Logging

• Enable access logging: Track when and who accesses secrets.
• Review logs periodically: Look for unusual access patterns.
• Set up alerts for suspicious activity.

CI/CD Integration

GitHub Actions

<SERVICE>_<TYPE>_<ENVIRONMENT>_<DETAIL>

Jenkins

<SERVICE>_<TYPE>_<ENVIRONMENT>_<DETAIL>

Troubleshooting

Common Issues

1. Authentication failures:
   • Ensure your API key or credentials are correct
   • Check token expiration
   • Verify network connectivity to the API server
2. Missing secrets:
   • Verify the secret exists in the correct environment
   • Check access permissions for the authenticated user
   • Ensure correct project ID and environment name
3. Local vault issues:
   • Ensure the vault is initialized: qala vault init
   • Check for file permission issues in the .qala directory
   • Try re-syncing: qala vault sync

Getting Support

If you encounter issues that you can't resolve:

1. Check the Qalá documentation
2. Contact support at support@qala-security.com
3. Include error messages, steps to reproduce, and environment details

Performance Optimization

• Cache secrets locally for short periods to reduce API calls
• Batch secret retrievals where possible
• Use local vault for offline operations
• Initialize QalaClient once at application startup

Migration Strategies

From Environment Variables

1. Export your current .env files

2. Import them into Qalá:

   <SERVICE>_<TYPE>_<ENVIRONMENT>_<DETAIL>

3. Update application code to use Qalá client

From Other Secret Managers

1. Export secrets from your current solution
2. Transform them to Qalá format if necessary
3. Import into Qalá using the CLI or API
4. Test thoroughly before removing the original solution

Compliance and Auditing

• Document your secret management processes
• Use access logs for compliance reporting
• Create rotation schedules for regulated credentials
• Perform regular access audits

By following these best practices, you'll ensure that your secrets are securely managed and effectively utilized throughout your organization.