julianobarbosa/senhasegura

Senhasegura

Skill Type: Library/API Reference (Type 1) + Data Fetching (Type 3).

Practical integration guide for the senhasegura (Segura) Privileged Access Management platform. Covers A2A OAuth 2.0 auth, PAM Core credential and SSH key APIs, DevOps Secret Manager (DSM) for CI/CD, External Secrets Operator for Kubernetes, MySafe, and an opt-in MCP server.

Voice Notification (on invocation)

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the Senhasegura skill"}' \
  > /dev/null 2>&1 &

Workflow Routing

| Trigger | Workflow | |---------|----------| | "set up A2A", "create senhasegura application", first-time OAuth client | Workflows/SetupA2A.md | | "sync secrets to Kubernetes", ESO + senhasegura DSM | Workflows/SyncKubernetesSecrets.md | | "rotate password", schedule rotation, Executions module | Workflows/RotatePasswords.md | | "fetch secrets in pipeline", DSM runb in CI/CD | Workflows/InjectCiCdSecrets.md | | "register SSH key", manage SSH key rotation | Workflows/RegisterSshKey.md |

Reference Routing

| Topic | File | |-------|------| | OAuth 2.0 flow, A2A application creation, token caching | Authentication.md | | PAM Core endpoints — credentials, custody, SSH keys | PamApi.md | | DSM CLI, runb, mapping.json, External Secrets Operator | Dsm.md | | MySafe, Python/TypeScript clients, CI/CD pipeline templates | Integrations.md | | Errors, debug mode, rate limits, common failure modes | Troubleshooting.md | | MCP server (opt-in Claude Code integration) | References/McpIntegration.md + Tools/SenhaseguraMcpServer.ts | | Legacy OAuth 1.0 reference | References/OAuth1Legacy.md | | Python SDK reference (PAI standard is TypeScript+Bun) | References/PythonSdk.md |

Gotchas

These are non-obvious senhasegura behaviors that bite users. Add new entries as they're discovered.

| # | Gotcha | |---|--------| | 1 | GET /iso/coe/senha?credentialId=N auto-locks the credential into custody. You MUST DELETE /iso/pam/credential/custody/N after, or the credential is held until manual release. Concurrent jobs deadlock on the second fetch. | | 2 | OAuth 2.0 access token TTL is 3600s. Cache and refresh at expiry minus 60s buffer, not on 401 retry. 401 retry storms hammer the IDP and trigger rate limits. | | 3 | /iso/coe/senha is the legacy A2A v1 password retrieval path; /api/pam/credential/{id} returns metadata only. The legacy path is current — do not refactor it away. | | 4 | A2A authorization IP restriction is matched against the HTTP source IP as seen by senhasegura — for Kubernetes, that's the egress NAT, not the pod IP. Whitelist the cluster egress. ESO failures surface as a generic "could not get provider client". | | 5 | DSM runb writes secrets to .runb.vars in the current working directory. If cwd is the repo root, it can be accidentally committed. Always run from a tmpdir or set SENHASEGURA_SECRETS_FILE=/tmp/runb.$$.vars. | | 6 | External Secrets Operator provider key is senhasegura (lowercase) and module is DSM (uppercase). Mixed case = silent provider-not-found; ESO just fails to reconcile with no clear error. | | 7 | dsm runb --tool-name <X> accepts github, azure-devops, gitlab, linux. Using linux outside Linux containers (Windows runners, unspecified) prevents masking of secret values in CI logs — secrets leak into log output. | | 8 | The Python and TypeScript clients in References/ do not auto-release custody on raw getPassword. Use the provided withPassword(...) / password_context(...) helpers, which wrap try/finally. | | 9 | The token endpoint is /iso/oauth2/token — note /iso/, not /api/. Senhasegura's path scheme mixes /iso/ (legacy/console) and /api/ (newer REST) inconsistently. | | 10 | Most enterprise installs use internal CAs. Reach for ignoreSslCertificate: true / SENHASEGURA_INSECURE: true only for local debugging. The proper path is mounting the CA bundle into ESO via the ca field. |

Quick Reference

# 1. Get token (1h TTL)
TOKEN=$(curl -s -X POST "$SENHASEGURA_URL/iso/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$SENHASEGURA_CLIENT_ID" \
  -d "client_secret=$SENHASEGURA_CLIENT_SECRET" | jq -r '.access_token')

# 2. List credentials
curl -H "Authorization: Bearer $TOKEN" "$SENHASEGURA_URL/api/pam/credential"

# 3. Get password (auto-locks custody — see Gotcha #1)
curl -H "Authorization: Bearer $TOKEN" \
  "$SENHASEGURA_URL/iso/coe/senha?credentialId=123"

# 4. Release custody (REQUIRED after step 3)
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$SENHASEGURA_URL/iso/pam/credential/custody/123"

# 5. DSM secret fetch via CLI
dsm runb --tool-name github \
  --application my-app --system production --environment prod
source .runb.vars && rm -f .runb.vars

Environment Variables

SENHASEGURA_URL="https://senhasegura.example.com"
SENHASEGURA_CLIENT_ID="oauth2-client-id"
SENHASEGURA_CLIENT_SECRET="oauth2-client-secret"

# DSM CLI optionals
SENHASEGURA_CONFIG_FILE="/path/to/config.yaml"
SENHASEGURA_MAPPING_FILE="/path/to/mapping.json"
SENHASEGURA_SECRETS_FILE="/tmp/runb.$$.vars"   # don't write into repo root
SENHASEGURA_TIMEOUT="30"
# SENHASEGURA_INSECURE — local debug only; mount the CA bundle in prod

Documentation Links

• Official documentation
• A2A module
• DSM module
• PAM Core API reference
• DSM CLI on GitHub
• External Secrets Operator — senhasegura provider

Execution Log

Append after every workflow run:

echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"Senhasegura","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' \
  >> ~/.claude/PAI/MEMORY/SKILLS/execution.jsonl