Authentication
==============

The Community DevOps Agent API uses AWS SigV4 authentication directly, without the complex JWT exchange flow used by some other AWS services.

Overview
--------

Unlike many AWS services that require JWT generation and credential exchange, the DevOps Agent API uses direct AWS SigV4 signing with your existing AWS credentials. This simplifies authentication and reduces latency.

How It Works
------------

1. **Direct Credential Usage**: The library uses your AWS credentials directly without modification
2. **SigV4 Signing**: All API requests are signed using the AWS Signature Version 4 algorithm
3. **Standard Resolution**: Credentials are resolved using boto3's standard credential chain

Credential Provider
-------------------

.. automodule:: devopsagent_api.auth
   :members:
   :undoc-members:
   :show-inheritance:

Supported Credential Sources
-----------------------------

The library supports all standard AWS credential sources:

**Environment Variables**

.. code-block:: bash

   export AWS_ACCESS_KEY_ID=your-access-key
   export AWS_SECRET_ACCESS_KEY=your-secret-key
   export AWS_REGION=us-east-1

**Shared Credentials File**

.. code-block:: ini

   # ~/.aws/credentials
   [default]
   aws_access_key_id = your-access-key
   aws_secret_access_key = your-secret-key

**AWS CLI Configuration**

.. code-block:: ini

   # ~/.aws/config
   [default]
   region = us-east-1

**IAM Roles** (for EC2, Lambda, etc.)

The library automatically detects and uses IAM roles when running on AWS infrastructure.

**Custom Credential Providers**

You can also use custom boto3 credential providers by configuring them in your boto3 session.

Authentication Flow
-------------------

.. code-block:: text

   1. User imports devopsagent_api
   2. Service registration triggers
   3. DevOpsAgentCredentialProvider loads AWS credentials
   4. Credentials are used for SigV4 signing
   5. All API requests are signed automatically

No JWT Generation
-----------------

Unlike some AWS services, the DevOps Agent API does not require:

- JWT token generation
- Credential exchange workflows
- Temporary credential management
- Complex authentication state

This makes the authentication process simpler and more reliable.

Troubleshooting
---------------

**Authentication Errors**

If you encounter authentication errors:

.. code-block:: bash

   # Check your AWS credentials
   aws sts get-caller-identity

   # Verify region configuration
   aws configure list

**Permission Issues**

Ensure your AWS credentials have the necessary permissions:

.. code-block:: json

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "devops-agent:*"
               ],
               "Resource": "*"
           }
       ]
   }

**Region Mismatch**

Ensure you're using the correct AWS region for the DevOps Agent service.

Security Best Practices
-----------------------

- **Rotate Credentials**: Regularly rotate your AWS access keys
- **Use IAM Roles**: Prefer IAM roles over long-term access keys
- **Least Privilege**: Grant only the minimum required permissions
- **Monitor Usage**: Monitor AWS CloudTrail for API usage patterns

Advanced Usage
--------------

For advanced authentication scenarios:

.. code-block:: python

   import boto3
   from botocore.credentials import CredentialProvider

   # Custom credential provider
   class CustomProvider(CredentialProvider):
       def load(self):
           # Your custom credential logic
           pass

   # Register custom provider
   session = boto3.Session()
   session._session.register_component(
       'credential_provider',
       CustomProvider(),
       priority=10
   )