Skip to main content

Service Accounts

This guide covers the complete lifecycle of managing service accounts with spirlctl, including creation, key management, role assignment, and deletion.

Understanding Service Accounts​

Service accounts are non-human identities used to authenticate automated systems, CI/CD pipelines, scripts, and other programmatic access to Defakto. Unlike user accounts that authenticate via SSO, service accounts use asymmetric key pairs (Ed25519) for authentication.

Key Characteristics​

  • Non-human identities - Designed for automated systems and applications
  • Ed25519 key-based authentication - Uses public/private key pairs for secure authentication
  • Role-based access control - Service accounts are assigned IAM roles that determine their permissions
  • Multiple keys per account - Each service account can have multiple keys for rotation
  • Owner-based management - The user who creates a service account becomes its owner

Common Use Cases​

  • CI/CD pipelines - Authenticate deployment workflows (GitHub Actions, Jenkins, etc.)
  • Infrastructure automation - Terraform, Pulumi, or other IaC tools
  • Monitoring systems - Automated health checks and status reporting
  • Integration scripts - Automated workload registration and configuration

Creating Service Accounts​

Basic Service Account Creation​

Create a simple service account:

spirlctl iam service-account create ci-pipeline --role-name auditor

Example output:

Service Account 'ci-pipeline' created successfully
ID:          sa-pkdve1m2rw
Name:        ci-pipeline
Role ID:     or----auditor
Created At:  2025-11-03T19:47:50Z
info

All service accounts must be assigned a role at creation. Click here for a list of built-in roles and their permissions.

Users can only create service accounts with roles equal to or lower than their own role. For example, an Operator cannot create a service account with the Administrator role.

Create with Description​

Add a description to document the service account's purpose:

spirlctl iam service-account create ci-pipeline \
  --role-name operator \
  --description "Used by GitHub Actions for deployment"

Example output:

Service Account 'ci-pipeline' created successfully
ID:          sa-l9jo3tys6m
Name:        ci-pipeline
Description: Used by GitHub Actions for deployment
Role ID:     or---operator
Created At:  2025-11-03T19:53:15Z

Create with Initial Key​

Generate a service account with an authentication key in one command:

spirlctl iam service-account create ci-pipeline \
  --role-name operator \
  --description "Used by GitHub Actions for deployment" \
  --generate-key

Example output:

Service Account 'ci-pipeline' created successfully
ID:          sa-f0xde4ki1a
Name:        ci-pipeline
Description: Used by GitHub Actions for deployment
Role ID:     or---operator
Created At:  2025-11-03T19:54:48Z

Initial key added successfully
ID:          sak-je6ybhhp53
Public Key:  MCowBQYDK2VwAyEAmw4KSHa9tuYg8LhL/akNtl5PF6DgEYmgPjT/Cx25HLg=
Enabled:     true
Created At:  2025-11-03T19:54:48Z
Private Key:
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEINMcj36kZk+OFktD7GONkIHO31D71J8haBExt9FJvYEg
-----END PRIVATE KEY-----
warning

Save the private key immediately! It is only displayed once and cannot be retrieved later. Store it securely in a secrets management system (e.g., AWS Secrets Manager, or GitHub Secrets).

Listing Service Accounts​

View all service accounts in your organization:

spirlctl iam service-account list

Example output:

ID             Name            Description                            Role ID        Created By                 Created At
sa-f0xde4ki1a  ci-pipeline     Used by GitHub Actions for deployment  or---operator  admin@defakto.security     2025-11-03T19:54:48Z
sa-3nz18t7yvh  monitoring-bot  Automated health checks                or----auditor  engineer@defakto.security  2025-11-03T20:37:39Z
sa-wv2xa7hgf5  terraform-sa    Infrastructure as Code automation      or------admin  ops@defakto.security       2025-11-03T19:59:04Z

3 service accounts found.

Viewing Service Account Details​

Get detailed information about a specific service account:

spirlctl iam service-account info ci-pipeline

Example output:

ID:          sa-f0xde4ki1a
Name:        ci-pipeline
Description: Used by GitHub Actions for deployment
Role ID :    or---operator
Created By:  admin@example.com
Created At:  2025-11-03T19:54:48Z

Service account Keys:
ID              Public Key                                                    Enabled  Created At
sak-je6ybhhp53  MCowBQYDK2VwAyEAmw4KSHa9tuYg8LhL/akNtl5PF6DgEYmgPjT/Cx25HLg=  true     2025-11-03T19:54:48Z
sak-mno345pqr6  MCowBQYDK2VwAyEAZGLJoJxSdBaBAJ7THGCehR6Q0UzBNPyD4Ks7akl76Xo=  false    2025-10-20T16:45:22Z

This command displays:

  • Service account metadata (ID, name, description, role)
  • Creator information
  • All associated keys with their status

Service Account Key Management​

Understanding Service Account Keys​

Service accounts authenticate using Ed25519 public/private key pairs:

  • Public key - These are stored in Defakto and used to authenticate requests by automated processes.
  • Private key - Used for authentication and kept secret by the service account owner.
  • Multiple keys - Each service account can have multiple active keys for rotation.

Key Lifecycle​

The typical key rotation workflow:

  1. Create a new key
  2. Deploy the new key to your systems
  3. Verify the new key works correctly
  4. Disable the old key
  5. Monitor for any issues
  6. Delete the old key

Create Service Account Key​

Add a new authentication key to an existing service account:

spirlctl iam service-account key add --service-account ci-pipeline

Example output:

Service account key created successfully
ID:          sak-kz6w4si5s6
Public Key:  MCowBQYDK2VwAyEADkxzSVNjd44RUbYeuTZ4plCwKbnytxVrkOCmajcXtVU=
Enabled:     true
Created At:  2025-11-03T20:53:51Z
Private Key:
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIB8twFZyVKGEO0wprs+w9JIfTseZEE/mQIK3MhbGNHmp
-----END PRIVATE KEY-----
warning

Save the private key immediately! It is only displayed once and cannot be retrieved later. If you lose the private key, you must create a new key.

Disable Service Account Key​

Temporarily disable a key without deleting it:

spirlctl iam service-account key disable sak-mno345pqr678

Example output:

Key "sak-mno345pqr678" disabled successfully.
info

Disabling a key immediately prevents it from being used for authentication. This is useful when rotating keys or investigating potential security issues.

Enable Service Account Key​

Re-enable a previously disabled key:

spirlctl iam service-account key enable sak-mno345pqr678

Example output:

Key "sak-mno345pqr678" enabled successfully.

Delete Service Account Key​

danger

Deleted keys cannot be recovered. Only delete keys if the following conditions have been met:

  1. The key will not be necessary for any applications in the future
  2. The key has been disabled long enough to verify they are no longer in use

Permanently remove a key from a service account:

spirlctl iam service-account key remove sak-mno345pqr678

If the key is still enabled, you'll receive an error. Disable it first, or use --force:

spirlctl iam service-account key remove sak-mno345pqr678 --force

Example output:

Key "sak-mno345pqr678" removed successfully.

Role Management​

Change Service Account Role​

Update the IAM role assigned to a service account:

spirlctl iam service-account role change ci-pipeline --role-name admin

Example output:

Service account role updated successfully to admin.
info

You can only assign roles that are equal to or lower than your own role. See the IAM Roles documentation for available roles and their permissions.

Disabling Service Accounts​

Disable all keys for a service account, which will prevent it from authenticating:

spirlctl iam service-account disable ci-pipeline

Example output:

All keys for service account 'ci-pipeline' have been marked as disabled

This disables all active keys associated with the service account. The service account can be re-enabled by enabling at least one of its keys.

Deleting Service Accounts​

danger

Deleted service accounts cannot be recovered. All associated keys will be permanently removed.

Remove a service account and all its keys:

spirlctl iam service-account delete ci-pipeline

If the service account has active keys, you'll receive an error. Disable all keys first, or use --force:

spirlctl iam service-account delete ci-pipeline --force

Example output:

Service account 'ci-pipeline' deleted successfully.

The --force flag will automatically disable all active keys before deletion.

Common Workflows​

Secure Service Account Creation for CI/CD​

Create a service account for GitHub Actions with proper scoping:

# Create service account with initial key
spirlctl iam service-account create github-actions-prod \
  --description "GitHub Actions deployment for production" \
  --role-name operator \
  --generate-key | \
  sed -n '/-----BEGIN PRIVATE KEY-----/,/-----END PRIVATE KEY-----/p' \
  > sa-key.pem


# Extract the private key and store in GitHub Secrets
# (This is a manual step - copy from sa-key.txt to GitHub repo settings)

# Securely delete the local file after storing in GitHub
rm sa-key.pem

Key Rotation​

Rotate service account keys without downtime:

  1. Create new key.
spirlctl iam service-account key add --service-account ci-pipeline > new-key.txt
  1. Deploy new key to your systems (e.g., update GitHub Secrets, Kubernetes secrets, etc.). This is environment-specific.
  2. Verify new key works by checking authentication logs.
  3. Get the old key ID from service account info.
spirlctl iam service-account info ci-pipeline
  1. Disable the old key.
spirlctl iam service-account key disable sak-old-key-id
  1. Monitor for 24-48 hours.
  2. Delete the old key permanently.
spirlctl iam service-account key remove sak-old-key-id
  1. Remove old key from secret-management systems.

Multi-Environment Setup​

Create service accounts for different environments:

# Create service accounts for each environment
for env in dev staging prod; do
  spirlctl iam service-account create "ci-pipeline-${env}" \
    --description "CI/CD for ${env} environment" \
    --role-name operator \
    --generate-key | \
    sed -n '/-----BEGIN PRIVATE KEY-----/,/-----END PRIVATE KEY-----/p' \
    > "sa-${env}-key.pem"
done

# View all created service accounts
spirlctl iam service-account list

Troubleshooting​

Cannot Create Service Account​

Permission denied:

  • Verify you're logged in: spirlctl whoami
  • Check your IAM role has permission to create service accounts. Only Admin and Owner roles can manage service accounts.
  • Contact your organization administrator for help.

Cannot create service account with requested role:

  • You can only create service accounts with roles equal to or lower than your own
  • Check your current role: spirlctl whoami
  • Request a role change if needed, or create the service account with a lower role

Service Account Cannot Authenticate​

Private key not working:

  1. Verify the key is enabled: 
    spirlctl iam service-account info service-account-name
  2. Check if the correct private key is being used
  3. Ensure the private key format is correct (PEM-encoded PKCS#8)
  4. Verify no whitespace or line break issues in the key

Key was disabled or deleted:

  • Check key status: spirlctl iam service-account info service-account-name
  • Enable the key if it was disabled: spirlctl iam service-account key enable sak-key-id
  • Create a new key if the old one was deleted

Lost Private Key​

If you lose a service account key's private key:

  1. Create a new key: 
    spirlctl iam service-account key add --service-account service-account-name
  2. Deploy the new key to your systems
  3. Disable the lost key: 
    spirlctl iam service-account key disable sak-lost-key-id
  4. Delete the lost key after verifying the new key works: 
    spirlctl iam service-account key remove sak-lost-key-id
warning

There is no way to retrieve a lost private key. Always store keys securely in a secrets management system.

Cannot Delete Service Account​

Error: Service account has active keys:

# Option 1: Manually disable all keys
spirlctl iam service-account info service-account-name
spirlctl iam service-account key disable sak-key-id-1
spirlctl iam service-account key disable sak-key-id-2
spirlctl iam service-account delete service-account-name

# Option 2: Use force flag to disable all keys automatically
spirlctl iam service-account delete service-account-name --force

Permission denied:

  • Only Admin and Owner roles can manage service accounts.
  • Check who created the service account: spirlctl iam service-account info service-account-name
  • Contact the owner or an administrator for assistance.

Best Practices​

Security​

  1. Store keys securely - Always use a secrets management system:

    • AWS Secrets Manager
    • GitHub Secrets
    • Azure Key Vault
    • Google Secret Manager

  2. Rotate keys regularly - Rotate service account keys every 90-180 days

  3. Use principle of least privilege - Assign the minimum role needed:

    • Auditor for read-only access
    • Operator for typical CI/CD operations
    • Manager for most IaC operations
    • Admin to create trust domains and service accounts in IaC

  4. Never commit keys to version control - Use .gitignore and secrets scanning tools. If a key is found, replace it and delete it.

  5. Monitor key usage - Track when and where service accounts are used

Key Management​

  1. Multiple keys for rotation - Maintain 2 keys per service account during rotation
  2. Disable before delete - Always disable keys before deleting them
  3. Test new keys - Verify new keys work before disabling old ones
  4. Document key ownership - Track which systems use which keys

Service Account Organization​

  1. Descriptive names - Use clear, purpose-driven names:

    • ✅ github-actions-prod
    • ✅ terraform-infra
    • ❌ sa1, test-account

  2. Add descriptions - Always include descriptions explaining purpose and usage

  3. Environment separation - Create separate service accounts per environment:

    • ci-pipeline-dev
    • ci-pipeline-staging
    • ci-pipeline-prod

  4. Audit regularly - Review service accounts at least quarterly:

    spirlctl iam service-account list

    Remove unused accounts to reduce the attack surface.

CI/CD Integration​

  1. Use environment variables - Never hardcode keys in scripts
  2. Scope per pipeline - Create dedicated service accounts per pipeline or job
  3. Automate rotation - Build key rotation into your automation
  4. Log authentication attempts - Monitor for unauthorized access attempts

Next Steps​