senhasegura-skill

Senhasegura PAM 平台技能

关于如何与 senhasegura（Segura）特权访问管理平台集成的全面指南。涵盖 A2A API、DevOps Secrets Management（DSM）、MySafe、凭据管理、SSH 密钥轮换和 Kubernetes 集成。

---

平台概述

核心模块

模块	用途	使用场景
PAM Core	凭据保管、密码轮换、会话管理	企业凭据管理
A2A	应用到应用的 API 身份验证	以编程方式访问机密
DSM	用于 CI/CD 管道的 DevOps Secret Manager	管道机密注入
MySafe	个人／团队密码管理器	企业凭据共享
Executions	自动密码轮换、脚本执行	计划的凭据变更
SCIM	身份预配与管理	与 IdP 同步用户

身份验证方法

方法	使用场景	安全级别
OAuth 2.0	所有集成的推荐方式	高（推荐）
OAuth 1.0	旧版支持	中
AWS Signature	AWS 工作负载	高

---

身份验证设置

OAuth 2.0 配置（推荐）

步骤 1：创建 A2A 应用程序

senhasegura Console:
1. Navigate to: A2A > Applications
2. Click: + New Application
3. Configure:
   - Name: my-app-integration
   - Authentication: OAuth 2.0
   - Enabled: Yes
4. Save and note the Client ID

步骤 2：获取凭据

After saving:
1. Go to: A2A > Applications > [your-app]
2. Click: Authorization > View
3. Copy:
   - client_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   - client_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

步骤 3：请求访问令牌

# OAuth 2.0 Token Request
curl -X POST "https://senhasegura.example.com/iso/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

响应：

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "token_type": "Bearer",
  "expires_in": 3600
}

步骤 4：在 API 调用中使用令牌

curl -X GET "https://senhasegura.example.com/api/pam/credential" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

---

PAM Core API 参考

凭据端点

方法	端点	说明
GET	/api/pam/credential	列出所有凭据
GET	/api/pam/credential/{id}	按 ID 获取凭据
POST	/api/pam/credential	创建新凭据
PUT	/api/pam/credential/{id}	更新凭据
DELETE	/api/pam/credential/{id}	停用凭据
DELETE	/iso/pam/credential/custody/{id}	释放凭据托管

列出所有凭据

curl -X GET "https://senhasegura.example.com/api/pam/credential" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

响应：

{
  "response": {
    "status": 200,
    "message": "Credentials found",
    "error": false,
    "error_code": 0,
    "credentials": [
      {
        "id": "123",
        "identifier": "db-admin-prod",
        "username": "admin",
        "hostname": "db.example.com",
        "ip": "10.0.1.50",
        "type": "Local User"
      }
    ]
  }
}

获取凭据密码

# Legacy endpoint for password retrieval
curl -X GET "https://senhasegura.example.com/iso/coe/senha" \
  -H "Authorization: Bearer $TOKEN" \
  -d "credentialId=123"

响应：

{
  "response": {
    "status": 200,
    "credential": {
      "id": "123",
      "password": "S3cur3P@ssw0rd!",
      "expiration": "2024-12-31T23:59:59Z"
    }
  }
}

创建凭据

curl -X POST "https://senhasegura.example.com/api/pam/credential" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "new-service-account",
    "username": "svc_app",
    "password": "InitialP@ss123",
    "hostname": "app-server.example.com",
    "ip": "10.0.2.100",
    "type": "Local User",
    "additional_info": "Service account for app",
    "tags": ["production", "critical"]
  }'

释放凭据托管

# After API password request, release custody
curl -X DELETE "https://senhasegura.example.com/iso/pam/credential/custody/123" \
  -H "Authorization: Bearer $TOKEN"

---

SSH 密钥 API

端点

方法	端点	说明
GET	/api/pam/sshkey	列出所有 SSH 密钥
GET	/api/pam/sshkey/{id}	按 ID 获取 SSH 密钥
POST	/api/pam/sshkey	注册新 SSH 密钥
PUT	/api/pam/sshkey/{id}	更新 SSH 密钥
POST	/api/pam/sshkey/{id}/rotate	触发密钥轮换

注册 SSH 密钥

curl -X POST "https://senhasegura.example.com/api/pam/sshkey" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "deploy-key-prod",
    "username": "deploy",
    "hostname": "*.prod.example.com",
    "public_key": "ssh-ed25519 AAAAC3Nza...",
    "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----...",
    "passphrase": "optional-passphrase",
    "auto_rotate": true,
    "rotation_days": 90
  }'

触发密钥轮换

curl -X POST "https://senhasegura.example.com/api/pam/sshkey/456/rotate" \
  -H "Authorization: Bearer $TOKEN"

---

DevOps Secret Manager（DSM）

DSM CLI 安装

# Download latest binary
curl -LO https://github.com/senhasegura/dsmcli/releases/latest/download/dsm-linux-amd64
chmod +x dsm-linux-amd64
sudo mv dsm-linux-amd64 /usr/local/bin/dsm

# Verify installation
dsm --version

DSM CLI 配置

创建 ~/.senhasegura/config.yaml：

# Required
SENHASEGURA_URL: "https://senhasegura.example.com"
SENHASEGURA_CLIENT_ID: "your-client-id"
SENHASEGURA_CLIENT_SECRET: "your-client-secret"

# Optional
SENHASEGURA_MAPPING_FILE: "/path/to/mapping.json"
SENHASEGURA_SECRETS_FILE: ".runb.vars"
SENHASEGURA_DISABLE_RUNB: 0

环境变量（替代方式）

export SENHASEGURA_URL="https://senhasegura.example.com"
export SENHASEGURA_CLIENT_ID="your-client-id"
export SENHASEGURA_CLIENT_SECRET="your-client-secret"
export SENHASEGURA_CONFIG_FILE="/path/to/config.yaml"

运行 Belt（runb）——机密注入

# Fetch secrets and create environment file
dsm runb \
  --application "my-application" \
  --system "production" \
  --environment "prod" \
  --config ~/.senhasegura/config.yaml

# Source the secrets
source .runb.vars

# Use in your application
echo "Database password: $DB_PASSWORD"

# Clean up after use (IMPORTANT)
rm -f .runb.vars

CI/CD 工具集成

# GitHub Actions
dsm runb --tool-name github --application myapp --system prod --environment prod

# Azure DevOps
dsm runb --tool-name azure-devops --application myapp --system prod --environment prod

# GitLab CI
dsm runb --tool-name gitlab --application myapp --system prod --environment prod

# Jenkins
dsm runb --tool-name linux --application myapp --system prod --environment prod

用于注册机密的映射文件

创建 mapping.json，以便从 CI/CD 注册／更新机密：

{
  "access_keys": [
    {
      "name": "AWS_PROD_KEYS",
      "type": "aws",
      "fields": {
        "access_key_id": "AWS_ACCESS_KEY_ID",
        "secret_access_key": "AWS_SECRET_ACCESS_KEY"
      }
    }
  ],
  "credentials": [
    {
      "name": "DATABASE_CREDS",
      "fields": {
        "user": "DB_USER",
        "password": "DB_PASSWORD",
        "host": "DB_HOST"
      }
    }
  ],
  "key_value": [
    {
      "name": "API_TOKENS",
      "fields": ["API_KEY", "API_SECRET", "WEBHOOK_SECRET"]
    }
  ]
}

DSM API 端点

方法	端点	说明
GET	/api/dsm/secret	列出机密
GET	/api/dsm/secret/{identifier}	按标识符获取机密
POST	/api/dsm/secret	创建机密
PUT	/api/dsm/secret/{identifier}	更新机密
DELETE	/api/dsm/secret/{identifier}	删除机密

---

Kubernetes 集成

External Secrets Operator 设置

安装 ESO

helm repo add external-secrets https://charts.external-secrets.io
helm install external-secrets external-secrets/external-secrets \
  -n external-secrets --create-namespace

创建身份验证机密

apiVersion: v1
kind: Secret
metadata:
  name: senhasegura-auth
  namespace: external-secrets
type: Opaque
stringData:
  clientId: "your-oauth2-client-id"
  clientSecret: "your-oauth2-client-secret"

配置 SecretStore

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: senhasegura-dsm
  namespace: default
spec:
  provider:
    senhasegura:
      url: "https://senhasegura.example.com"
      module: DSM
      auth:
        clientId:
          secretRef:
            name: senhasegura-auth
            key: clientId
            namespace: external-secrets
        clientSecretSecretRef:
          name: senhasegura-auth
          key: clientSecret
          namespace: external-secrets
      # Optional: skip TLS verification (not recommended for production)
      # ignoreSslCertificate: true

ClusterSecretStore（多命名空间）

apiVersion: external-secrets.io/v1beta1
kind: ClusterSecretStore
metadata:
  name: senhasegura-dsm-global
spec:
  provider:
    senhasegura:
      url: "https://senhasegura.example.com"
      module: DSM
      auth:
        clientId:
          secretRef:
            name: senhasegura-auth
            key: clientId
            namespace: external-secrets
        clientSecretSecretRef:
          name: senhasegura-auth
          key: clientSecret
          namespace: external-secrets

ExternalSecret——显式键

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: database-credentials
  namespace: default
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: senhasegura-dsm
    kind: SecretStore
  target:
    name: db-secret
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: database-prod
        property: username
    - secretKey: password
      remoteRef:
        key: database-prod
        property: password
    - secretKey: host
      remoteRef:
        key: database-prod
        property: host

ExternalSecret——提取所有字段

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: api-secrets
  namespace: default
spec:
  refreshInterval: 30m
  secretStoreRef:
    name: senhasegura-dsm
    kind: SecretStore
  target:
    name: api-config
    creationPolicy: Owner
  dataFrom:
    - extract:
        key: api-settings-prod

---

MySafe 集成

MySafe 功能

• 密码：存储和共享登录凭据
• 笔记：安全的文本笔记
• 文件：加密文件存储
• API 机密：存储 API 密钥、令牌和客户端凭据

Web 访问

URL: https://senhasegura.example.com/mysafe
Features:
- Central vault administration
- Credential creation and management
- Sharing with internal/external users
- Access history and auditing

浏览器扩展

Chrome: Segura MySafe Extension
Features:
- Auto-fill passwords
- Create new credentials
- Quick access to notes

分享项目

Sharing Options:
1. Internal sharing (MySafe users)
   - Select users/groups
   - Set permissions (view/edit)

2. External sharing (temporary)
   - Generate unique link
   - Set expiration time
   - Limit number of views
   - Revoke access anytime

---

Python SDK 集成

安装

pip install senhasegura

基本用法

from senhasegura import A2A

# Initialize with OAuth 2.0 (recommended)
client = A2A(
    base_url="https://senhasegura.example.com",
    client_id="your-client-id",
    client_secret="your-client-secret",
    auth_method="oauth2"  # or "oauth1"
)

# Get credential password
response = client.get(
    "/iso/coe/senha",
    params={"credentialId": 123}
)
password = response.json()["response"]["credential"]["password"]

# List all credentials
credentials = client.get("/api/pam/credential")
for cred in credentials.json()["response"]["credentials"]:
    print(f"{cred['identifier']}: {cred['username']}@{cred['hostname']}")

# Create new credential
new_cred = client.post(
    "/api/pam/credential",
    json={
        "identifier": "new-service",
        "username": "svc_user",
        "password": "SecurePass123!",
        "hostname": "server.example.com"
    }
)

# Release credential custody
client.delete(f"/iso/pam/credential/custody/{credential_id}")

OAuth 1.0（旧版）

from senhasegura import A2A

client = A2A(
    base_url="https://senhasegura.example.com",
    consumer_key="your-consumer-key",
    consumer_secret="your-consumer-secret",
    token_key="your-token-key",
    token_secret="your-token-secret",
    auth_method="oauth1"
)

错误处理

from senhasegura import A2A
from senhasegura.exceptions import AuthenticationError, APIError

try:
    client = A2A(
        base_url="https://senhasegura.example.com",
        client_id="client-id",
        client_secret="client-secret"
    )

    response = client.get("/api/pam/credential/999")
    response.raise_for_status()

except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except APIError as e:
    print(f"API error: {e.status_code} - {e.message}")

---

CI/CD 流水线示例

GitHub Actions

name: Deploy with Secrets

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install DSM CLI
        run: |
          curl -LO https://github.com/senhasegura/dsmcli/releases/latest/download/dsm-linux-amd64
          chmod +x dsm-linux-amd64
          sudo mv dsm-linux-amd64 /usr/local/bin/dsm

      - name: Fetch Secrets
        env:
          SENHASEGURA_URL: ${{ secrets.SENHASEGURA_URL }}
          SENHASEGURA_CLIENT_ID: ${{ secrets.SENHASEGURA_CLIENT_ID }}
          SENHASEGURA_CLIENT_SECRET: ${{ secrets.SENHASEGURA_CLIENT_SECRET }}
        run: |
          dsm runb \
            --tool-name github \
            --application my-app \
            --system production \
            --environment prod
          source .runb.vars

      - name: Deploy
        run: |
          # Secrets are now available as environment variables
          ./deploy.sh

      - name: Cleanup
        if: always()
        run: rm -f .runb.vars

Azure DevOps 流水线

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - script: |
      curl -LO https://github.com/senhasegura/dsmcli/releases/latest/download/dsm-linux-amd64
      chmod +x dsm-linux-amd64
      sudo mv dsm-linux-amd64 /usr/local/bin/dsm
    displayName: Install DSM CLI

  - script: |
      dsm runb \
        --tool-name azure-devops \
        --application $(APPLICATION_NAME) \
        --system $(SYSTEM_NAME) \
        --environment $(ENVIRONMENT)
    displayName: Fetch Secrets
    env:
      SENHASEGURA_URL: $(SENHASEGURA_URL)
      SENHASEGURA_CLIENT_ID: $(SENHASEGURA_CLIENT_ID)
      SENHASEGURA_CLIENT_SECRET: $(SENHASEGURA_CLIENT_SECRET)

  - script: |
      source .runb.vars
      ./deploy.sh
    displayName: Deploy Application

  - script: rm -f .runb.vars
    displayName: Cleanup
    condition: always()

GitLab CI

stages:
  - deploy

deploy:
  stage: deploy
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y curl
    - curl -LO https://github.com/senhasegura/dsmcli/releases/latest/download/dsm-linux-amd64
    - chmod +x dsm-linux-amd64 && mv dsm-linux-amd64 /usr/local/bin/dsm
  script:
    - |
      dsm runb \
        --tool-name gitlab \
        --application $APPLICATION_NAME \
        --system $SYSTEM_NAME \
        --environment $CI_ENVIRONMENT_NAME
    - source .runb.vars
    - ./deploy.sh
  after_script:
    - rm -f .runb.vars
  variables:
    SENHASEGURA_URL: $SENHASEGURA_URL
    SENHASEGURA_CLIENT_ID: $SENHASEGURA_CLIENT_ID
    SENHASEGURA_CLIENT_SECRET: $SENHASEGURA_CLIENT_SECRET

---

工作流

工作流 1：初始 A2A 设置

1. Create Application
   Console: A2A > Applications > New
   - Name: app-integration
   - Authentication: OAuth 2.0
   - Status: Enabled

2. Configure Authorization
   Console: A2A > Authorizations > New
   - Application: app-integration
   - Module: PAM Core (or DSM)
   - Permission: Read/Write
   - IP Restriction: 10.0.0.0/8 (optional)
   - Credential filter: tag:production (optional)

3. Test Authentication
   curl -X POST "$URL/iso/oauth2/token" \
     -d "grant_type=client_credentials" \
     -d "client_id=$CLIENT_ID" \
     -d "client_secret=$CLIENT_SECRET"

4. Verify Access
   curl -X GET "$URL/api/pam/credential" \
     -H "Authorization: Bearer $TOKEN"

工作流 2：Kubernetes Secret 同步

1. Install External Secrets Operator
   helm install external-secrets external-secrets/external-secrets

2. Create Auth Secret
   kubectl create secret generic senhasegura-auth \
     --from-literal=clientId=xxx \
     --from-literal=clientSecret=xxx

3. Create SecretStore
   kubectl apply -f secretstore.yaml

4. Create ExternalSecret
   kubectl apply -f externalsecret.yaml

5. Verify Sync
   kubectl get externalsecret
   kubectl get secret db-secret -o yaml

工作流 3：密码轮换自动化

1. Configure Execution Template
   Console: Executions > Templates
   - Template: Linux Password Change
   - Commands: passwd, chage
   - Verification: SSH login test

2. Create Execution Policy
   Console: Executions > Policies
   - Credentials: tag:linux-servers
   - Schedule: Every 30 days
   - Template: Linux Password Change
   - Notification: [email protected]

3. Monitor Executions
   Console: Executions > History
   - Filter by date/status
   - Review logs
   - Handle failures

---

安全最佳实践

凭据管理

DO:
- Use one credential per A2A authorization
- Apply IP restrictions to authorized networks only
- Enable automatic password rotation
- Use unique identifiers for credentials
- Audit access logs regularly

DON'T:
- Share A2A credentials across applications
- Disable IP restrictions in production
- Store credentials in source code
- Use weak or default passwords
- Ignore failed authentication alerts

API 安全

# Good: Use environment variables
import os
client = A2A(
    base_url=os.environ["SENHASEGURA_URL"],
    client_id=os.environ["SENHASEGURA_CLIENT_ID"],
    client_secret=os.environ["SENHASEGURA_CLIENT_SECRET"]
)

# Good: Release custody after use
try:
    password = client.get_password(credential_id)
    # Use password
finally:
    client.release_custody(credential_id)

Kubernetes 安全

# Use namespaced SecretStore when possible
apiVersion: external-secrets.io/v1beta1
kind: SecretStore  # Not ClusterSecretStore
metadata:
  name: app-secrets
  namespace: my-app  # Limit scope
spec:
  provider:
    senhasegura:
      # ...
---
# Restrict RBAC
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: secret-reader
  namespace: my-app
rules:
  - apiGroups: [""]
    resources: ["secrets"]
    resourceNames: ["db-secret", "api-secret"]  # Specific secrets only
    verbs: ["get"]

---

故障排除

身份验证错误

错误	原因	解决方案
401 Unauthorized	令牌无效或已过期	请求新的访问令牌
403 Forbidden	权限不足	检查 A2A 授权
invalid_client	client_id/secret 错误	在控制台中验证凭据
IP not allowed	IP 限制	将源 IP 添加到白名单

DSM CLI 问题

# Debug mode
dsm runb --debug \
  --application myapp \
  --system prod \
  --environment prod

# Common fixes
# 1. Config file not found
export SENHASEGURA_CONFIG_FILE=/absolute/path/to/config.yaml

# 2. SSL certificate errors
# Add to config.yaml:
# SENHASEGURA_INSECURE: true  # Not recommended for production

# 3. Permission denied
chmod 600 ~/.senhasegura/config.yaml

External Secrets Operator

# Check SecretStore status
kubectl describe secretstore senhasegura-dsm

# Check ExternalSecret status
kubectl describe externalsecret database-credentials

# View ESO logs
kubectl logs -n external-secrets -l app.kubernetes.io/name=external-secrets

# Common issues:
# - "could not get provider client": Check auth secret
# - "could not find secret": Verify secret identifier in DSM
# - "refresh failed": Check network/firewall to senhasegura

API 响应代码

代码	含义	操作
200	成功	处理响应
400	请求错误	检查请求格式
401	未授权	重新进行身份验证
403	禁止访问	检查权限
404	未找到	验证资源 ID
429	请求过多	实现退避机制
500	服务器错误	联系支持人员

---

快速参考

环境变量

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

# DSM CLI
SENHASEGURA_CONFIG_FILE="/path/to/config.yaml"
SENHASEGURA_MAPPING_FILE="/path/to/mapping.json"
SENHASEGURA_SECRETS_FILE=".runb.vars"

# Optional
SENHASEGURA_INSECURE="false"  # Skip TLS verify
SENHASEGURA_TIMEOUT="30"      # Request timeout

常见 API 模式

# Get token
TOKEN=$(curl -s -X POST "$URL/iso/oauth2/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" | jq -r '.access_token')

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

# Get password
curl -H "Authorization: Bearer $TOKEN" "$URL/iso/coe/senha?credentialId=123"

# Release custody
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$URL/iso/pam/credential/custody/123"

---

文档链接

• 官方文档
• A2A 模块
• DSM 文档
• MySafe
• API 参考
• DSM CLI GitHub
• External Secrets 集成
• 社区论坛