AccessBuilder Client Library

Gerenciador reutilizável de clientes AWS com suporte completo a SSO, AWS Organizations, Cross-Account Access e External ID.

Características (v1.1.1)

✅ SSO (IAM Identity Center): Autenticação nativa com perfis SSO
✅ AWS Organizations: Descoberta automática de contas e filtro por OU
✅ External ID: Segurança cross-account contra "Confused Deputy"
✅ Factory Pattern: Crie clientes AWS facilmente
✅ Lazy Loading: @property para clientes principais (s3, ec2, rds)
✅ Cache Automático: Performance otimizada
✅ 5 Estratégias de Autenticação: SSO, IAM User, Temporary, Cross-Account, Default
✅ Extensível: Adicione novos serviços sem modificar código core
✅ Type Hints: Suporte completo a tipagem Python
✅ ConfigLoader: Auto-detecção com prioridade SSO

Uso Rápido

Estratégia 1: SSO (Recomendado)

from AccessBuilder import AWSClientManager

# Configure SSO no ~/.aws/config primeiro
# Execute: aws sso login --profile my-profile

manager = AWSClientManager(
    region='us-east-1',
    sso_profile='my-profile'  # ✨ Novo v1.1.0
)
manager.initialize()

# Usar S3
s3 = manager.s3_client
buckets = s3.list_buckets()

# Usar qualquer outro serviço
ec2 = manager.get_client('ec2')
rds = manager.get_client('rds')

Estratégia 2: IAM User (Credenciais Persistentes)

from AccessBuilder import AWSClientManager

manager = AWSClientManager(
    region='us-east-1',
    aws_access_key_id='AKIA1234567890ABCDEF',
    aws_secret_access_key='wJalrXUtnFEMI/K7MDENG...'
)
manager.initialize()

# Usar S3
s3 = manager.s3_client
buckets = s3.list_buckets()

Estratégia 3: Credenciais Temporárias (STS Token)

manager = AWSClientManager(
    region='us-east-1',
    aws_access_key_id='ASIA1234567890ABCDEF',
    aws_secret_access_key='wJalrXUtnFEMI/K7MDENG...',
    aws_session_token='FwoGZXIvYXdzEOz...'  # Inclua o token!
)
manager.initialize()

Estratégia 4: Cross-Account Role com External ID

manager = AWSClientManager(
    region='us-east-1',
    cross_account_role='arn:aws:iam::123456789012:role/AthenaRole',
    external_id='my-secure-external-id'  # ✨ Novo v1.1.0 (recomendado!)
)
manager.initialize()

Estratégia 5: Credenciais Padrão (EC2 IAM Role)

# Em uma EC2/ECS/Lambda com IAM role
manager = AWSClientManager(region='us-east-1')
manager.initialize()

Novas Funcionalidades v1.1.0

Descoberta de Contas via AWS Organizations

from AccessBuilder import AWSClientManager, OrganizationsHelper

# Autenticar na Management Account
manager = AWSClientManager(
    region='us-east-1',
    sso_profile='management-account'
)
manager.initialize()

# Descobrir contas
org = OrganizationsHelper(session=manager.session)

# Listar todas as contas
all_accounts = org.list_all_accounts()

# Filtrar por OU
prod_accounts = org.filter_by_ou(['Production'])

for account in prod_accounts:
    print(f"{account['Name']}: {account['Id']}")

Workflow Multi-Conta Completo

# 1. Autenticar via SSO
manager_security = AWSClientManager(
    region='us-east-1',
    sso_profile='security-account'
)
manager_security.initialize()

# 2. Descobrir contas por OU
org = OrganizationsHelper(session=manager_security.session)
accounts = org.filter_by_ou(['Production'])

# 3. Para cada conta, assumir role com External ID
for account in accounts:
    manager_target = AWSClientManager(
        region='us-east-1',
        cross_account_role=f"arn:aws:iam::{account['Id']}:role/Auditor",
        external_id='audit-external-id-2024'
    )
    manager_target.initialize()
    
    s3 = manager_target.s3_client
    ec2 = manager_target.get_client('ec2')
    # ... sua lógica de auditoria aqui

Cache de Credenciais STS em Memória ✨ Novo

O CredentialCacheManager permite assumir roles em múltiplas contas e armazenar as credenciais STS em memória durante a execução, evitando chamadas repetidas ao STS.

Sobre Permission Sets:

As permissões efetivas são as da role assumida, não do usuário original
Se usar AWS SSO, cada permission set cria uma role na conta de destino
Exemplos de roles: OrganizationAccountAccessRole, AWSReservedSSO_AdministratorAccess_xxx

from AccessBuilder import CredentialCacheManager
import boto3

# 1. Criar sessão da security/management account
base_session = boto3.Session(profile_name='security-account')

# 2. Criar cache manager
cache = CredentialCacheManager(
    base_session=base_session,
    role_name='OrganizationAccountAccessRole',  # Role a assumir em cada conta
    region='us-east-1',
    external_id='my-secure-id'  # Opcional, para segurança adicional
)

# 3. Assumir roles (escolha uma opção):

# Opção A: Contas específicas
cache.assume_roles_for_accounts(['123456789012', '234567890123'])

# Opção B: Filtrar por OUs
cache.assume_roles_for_ous(['Production', 'Development'])

# Opção C: TODAS as contas da organização
cache.assume_roles_for_all_accounts()

# 4. Usar credenciais para acessar as contas
for account_id in cache.list_cached_accounts():
    manager = cache.get_manager(account_id['account_id'])
    
    if manager:
        s3 = manager.s3_client
        buckets = s3.list_buckets()
        print(f"Conta {account_id['name']}: {len(buckets['Buckets'])} buckets")

# 5. Estatísticas do cache
stats = cache.get_statistics()
print(f"Credenciais válidas: {stats['valid']} de {stats['total']}")

# 6. Renovar todas as credenciais (se expirarem)
cache.refresh_all()

Veja exemplo completo em: examples/exemplo_credential_cache.py

Auto-inicialização e tratamento de erros

A partir da versão atual, o AWSClientManager tentará inicializar a boto3.Session automaticamente quando você acessar um cliente via s3_client, athena_client ou get_client(...) caso initialize() ainda não tenha sido chamado.

Conveniência: você pode criar o manager sem chamar initialize() explicitamente; o acesso ao cliente fará a inicialização automática.
Segurança/erros: se a inicialização falhar (credenciais inválidas, STS sem permissão etc.), será lançada uma RuntimeError com a mensagem "Falha ao inicializar sessão AWS. Verifique credenciais e permissões." e a exceção original ficará encadeada para fins de debug.

Exemplo (auto-init):

from AccessBuilder import AWSClientManager

# Não é necessário chamar initialize() explicitamente
manager = AWSClientManager(region='us-east-1')

# Ao acessar, o manager inicializa automaticamente a sessão
s3 = manager.s3_client
print(type(s3))

Se preferir o comportamento antigo (chamar initialize() explicitamente), continue a chamar manager.initialize() — o comportamento permanece suportado.

Usar ConfigLoader para Automação

from AccessBuilder import ConfigLoader

# Carregar do arquivo .env
config = ConfigLoader('.env')
manager = config.get_manager()  # Detecta estratégia automaticamente

# Ou especificar estratégia
manager = config.get_manager('temporary')

📝 Arquivo .env

Crie um arquivo .env com suas credenciais:

# Prioridade 1: SSO (Recomendado) ✨ Novo v1.1.0
AWS_PROFILE=my-sso-profile
AWS_REGION=us-east-1

# External ID (opcional, para AssumeRole) ✨ Novo v1.1.0
AWS_EXTERNAL_ID=my-secure-external-id

# Ou use IAM User:
# AWS_ACCESS_KEY_ID=AKIA1234567890ABCDEF
# AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG+bPxRfiCY...

# Ou use Temp Token (adicione se usar STS):
# AWS_SESSION_TOKEN=FwoGZXIvYXdzEOz...

# Ou use Cross-Account:
# AWS_CROSS_ACCOUNT_ROLE=arn:aws:iam::123456789012:role/AthenaRole
# AWS_EXTERNAL_ID=my-external-id

Segurança: Nunca commite .env no Git. Use .gitignore:

.env
*.key
secrets/

Dica: Veja .env.example para referência completa.

Recursos Principais

@property (Interface Limpa)

manager.initialize()

# Acesso simples como atributo
s3 = manager.s3_client      # Lazy loading automático
athena = manager.athena_client

# Transparente: sintaxe de atributo, lógica de método

Factory Method (Extensibilidade)

# Qualquer serviço AWS
dynamodb = manager.get_client('dynamodb')
lambda_svc = manager.get_client('lambda')
sqs = manager.get_client('sqs')
ec2 = manager.get_client('ec2')

# Com argumentos customizados
s3_custom = manager.get_client('s3', endpoint_url='http://localhost:9000')

Cache Management

# Listar clientes ativos
active = manager.list_active_clients()
print(active)  # ['s3', 'athena', 'dynamodb']

# Limpar cache específico
manager.clear_client_cache('s3')

# Limpar tudo
manager.clear_client_cache()

Rotação de Credenciais

# Token expirado? Rotacionar!
manager.rotate_credentials(
    aws_access_key_id='ASIA_NEW_...',
    aws_secret_access_key='new_secret...',
    aws_session_token='FwoG_NEW_...'
)
# Próximas requisições usam novas credenciais

Logging

Habilite logs para debug:

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('aws_client_lib')
logger.setLevel(logging.DEBUG)

Saída esperada:

INFO:aws_client_lib.config:ConfigLoader inicializado (env_path=.env)
INFO:aws_client_lib.aws_client:Using IAM User (access_key_id provided)
DEBUG:aws_client_lib.aws_client:Creating S3 client (lazy loading)
INFO:aws_client_lib.aws_client:Session AWS inicializada para região: us-east-1

Exemplos Completos

Listar buckets S3

from AccessBuilder import AWSClientManager

manager = AWSClientManager(
    region='us-east-1',
    aws_access_key_id='AKIA...',
    aws_secret_access_key='wJalr...'
)
manager.initialize()

s3 = manager.s3_client
response = s3.list_buckets()
for bucket in response['Buckets']:
    print(bucket['Name'])

Executar query Athena

from AccessBuilder import ConfigLoader

config = ConfigLoader('.env')
manager = config.get_manager()

athena = manager.athena_client
response = athena.start_query_execution(
    QueryString='SELECT COUNT(*) FROM table',
    QueryExecutionContext={'Database': 'default'},
    ResultConfiguration={'OutputLocation': 's3://bucket/prefix/'}
)
print(response['QueryExecutionId'])

Multi-serviço

from AccessBuilder import ConfigLoader

config = ConfigLoader('.env')
manager = config.get_manager()

# S3
s3 = manager.s3_client
s3.put_object(Bucket='bucket', Key='file', Body=b'data')

# DynamoDB
dynamodb = manager.get_client('dynamodb')
dynamodb.put_item(TableName='table', Item={'id': {'S': 'value'}})

# SQS
sqs = manager.get_client('sqs')
sqs.send_message(QueueUrl='https://...', MessageBody='hello')

# Lambda
lambda_svc = manager.get_client('lambda')
lambda_svc.invoke(FunctionName='my-function', Payload='{}')

Arquitetura

Camadas

┌─────────────────────────────────────┐
│   Seu Código da Aplicação           │
│   (main.py, app.py, etc)            │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│   ConfigLoader                      │
│   - Carrega .env / Env Vars         │
│   - Cria AWSClientManager           │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│   AWSClientManager                  │
│   - @property s3_client             │
│   - @property athena_client         │
│   - get_client(service)             │
│   - Cache Management                │
│   - Credential Rotation             │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│   boto3.Session                     │
│   (Centraliza credenciais)          │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│   AWS Services                      │
│   (S3, Athena, DynamoDB, etc)       │
└─────────────────────────────────────┘

Design Patterns

Factory Pattern: get_client(service_name) cria clientes dinamicamente
Property Pattern: @property s3_client fornece interface limpa
Lazy Loading: Clientes criados apenas quando acessados
Cache Pattern: Clientes reutilizados em próximos acessos
Credential Rotation: Suporte a renovação de tokens

Desenvolvimento

Criar ambiente virtual

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

Instalar com dependências de dev

pip install -e ".[dev]"

Rodar testes

pytest tests/ -v --cov=AccessBuilder

Code style

black AccessBuilder
flake8 AccessBuilder
mypy AccessBuilder

License

MIT License - veja LICENSE arquivo

Documentação Adicional

Novas Funcionalidades v1.1.1 - Correção da função de validação de expiração de credenciais temporárias
Novas Funcionalidades v1.1.0 - Guia completo de SSO, Organizations e External ID
Exemplos Práticos - 6 exemplos funcionais completos
Configuração .env - Template de configuração com todos os cenários

O Que Há de Novo

v1.1.1 (Fevereiro 2026)

✅ Correção da função de validação de expiração de credenciais temporárias

v1.1.0 (Fevereiro 2026)

✨ SSO Authentication: Suporte completo a IAM Identity Center
✨ AWS Organizations: Descoberta automática de contas e filtro por OU
✨ External ID: Segurança cross-account contra "Confused Deputy Problem"
✨ ConfigLoader melhorado: Auto-detecção de SSO profiles
📝 Documentação expandida: Guias, exemplos e troubleshooting
🔒 Segurança aprimorada: Validação de credenciais e expiration checking

v1.0.0

✅ Factory Pattern e Lazy Loading
✅ 4 estratégias de autenticação básicas
✅ Cache automático de clientes
✅ ConfigLoader com .env

Contribuições

Contribuições são bem-vindas! Abra um PR ou issue.

Versão: 1.1.1 Data: 11 de fevereiro de 2026
Feito com ❤️ para a comunidade AWS

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
src/AccessBuilder		src/AccessBuilder
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
py.typed		py.typed
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

AccessBuilder Client Library

Características (v1.1.1)

Uso Rápido

Estratégia 1: SSO (Recomendado)

Estratégia 2: IAM User (Credenciais Persistentes)

Estratégia 3: Credenciais Temporárias (STS Token)

Estratégia 4: Cross-Account Role com External ID

Estratégia 5: Credenciais Padrão (EC2 IAM Role)

Novas Funcionalidades v1.1.0

Descoberta de Contas via AWS Organizations

Workflow Multi-Conta Completo

Cache de Credenciais STS em Memória ✨ Novo

Auto-inicialização e tratamento de erros

Usar ConfigLoader para Automação

📝 Arquivo .env

Recursos Principais

@property (Interface Limpa)

Factory Method (Extensibilidade)

Cache Management

Rotação de Credenciais

Logging

Exemplos Completos

Listar buckets S3

Executar query Athena

Multi-serviço

Arquitetura

Camadas

Design Patterns

Desenvolvimento

Criar ambiente virtual

Instalar com dependências de dev

Rodar testes

Code style

License

Documentação Adicional

O Que Há de Novo

v1.1.1 (Fevereiro 2026)

v1.1.0 (Fevereiro 2026)

v1.0.0

Contribuições

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages