System Management

1.0 Introduction

This article describes the Fortanix Armor system administration settings.

2.0 Configure System Administration Settings (Using Armor API)

After logging in as the system administrator (sysadmin), configure platform-level settings such as email, security policies, and account governance.

NOTE

In the current release, platform-level sysadmin settings can be configured using Fortanix Armor APIs. You can use any REST API client or automation tool to configure these settings. The example below uses curl commands to demonstrate the configuration process.

2.1 Retrieve Current Sysadmin Configuration

Retrieve the current sysadmin configuration for Fortanix Armor. Reviewing the existing configuration helps you understand the default settings before applying any updates.

Perform the following steps:

1. Run the following command to log in to Fortanix Armor as a sysadmin user:

   curl -k -sS --fail-with-body -c cookie-jar.txt -H "X-CSRF-Header: true" -X POST https://<armor-domain>/api/v1/iam/session/auth -u "<username>:<password>"

   Where,

   • <armor-domain>: Specifies the Fortanix Armor domain corresponding to the certConfig.subject value configured in Armor Installation Guide - On-premises.

   • <username> and <password>: Specifies the Fortanix Armor sysadmin account credentials.

2. Run the following command to select the Fortanix Armor account:

   curl -k -sS --fail-with-body -c cookie-jar.txt -b cookie-jar.txt -H "X-CSRF-Header: true" -X POST https://<armor-domain>/api/v1/iam/session/select_account -d '{"acct_id": "278fec9c-aa19-4075-a81e-5bca9649a136"}'

3. Run the following command to retrieve the current sysadmin configuration:

   curl -k -sS --fail-with-body -c cookie-jar.txt -H "X-CSRF-Header: true" -X GET https://<armor-domain>/api/v1/iam/system/config

   The following default sysadmin configuration is shown:

   {
     "auth_configs": {},
     "external_services": {
       "email": null,
       "recaptcha": null
     },
     "policies": {
       "account_creation": {
         "creation_notification_recipients": [],
         "pending_approval_notification_recipients": [],
         "sysadmin_approval_required": "never"
       },
       "email_validation": {
         "allowed_domains": null,
         "confirmation": "disabled",
         "maximum_length": null,
         "restricted_characters": []
       },
       "identity_verification": {
         "ticket_lifetime": 600
       },
       "password": {
         "history_size": 0,
         "max_repetition": null,
         "max_sequence": null,
         "minimum_length": 8,
         "use_denylist": false
       },
       "password_auth_lockout": null,
       "session_expiry": {
         "max_session_lifetime": 86400,
         "refresh_token_lifetime": 86400,
         "session_token_lifetime": 60
       },
       "signup": {
         "disable_signup": false
       },
       "third_party_group": {
         "expiry_days": 30
       }
     }
   }
   

2.2 Update Sysadmin Configuration

Run the following script to update the settings:

curl -k -sS --fail-with-body -c cookie-jar.txt \
  -H "X-CSRF-Header: true" \
  -X PATCH https://<armor-domain>/api/v1/iam/system/config \
  -d '<configuration-json>'

Where,

• <armor-domain>: Specifies the Fortanix Armor domain.

• <configuration-json>: Specifies the sysadmin configuration settings to update.

NOTE

The request body can contain one or more configuration sections. For examples of commonly configured settings, see Section 2.3: Additional Configuration Examples.

2.3 Additional Configuration Examples

This section provides sample configuration snippets for commonly used sysadmin settings. These examples can be used as references when customizing Fortanix Armor to meet specific organizational requirements.

• Amazon SES Email Configuration: This setting configures the email provider used by Fortanix Armor to send system-generated emails.

  Path: external_services.email

  {
    "external_services": {
      "email": {
        "from_address": "no-reply@example.com",
        "provider": {
          "$type": "amazon_ses",
          "url": "https://email.us-west-2.amazonaws.com/",
          "access_key": "<access-key>",
          "secret_key": "<secret-key>"
        }
      }
    }
  }

  Where,

  • from_address: Specifies the sender email address used for system-generated emails.

  • $type: Specifies the email provider type.

  • url: Specifies the Amazon SES endpoint URL.

  • access_key: Specifies the AWS access key.

  • secret_key: Specifies the AWS secret access key.

• SMTP Email Configuration: This setting configures the SMTP server for sending system-generated emails from Fortanix Armor.

  Path: external_services.email

  {
    "external_services": {
      "email": {
        "from_address": "no-reply@example.com",
        "provider": {
          "$type": "smtp",
          "host": "smtp.example.com",
          "port": 587,
          "tls": {
            "mode": "required"
          }
        }
      }
    }
  }

  Where,

  • host: Specifies the SMTP server hostname or IP address.

  • port: Specifies the SMTP server port.

  • mode: Specifies the TLS behavior. Supported values include:

    • disabled

    • starttls

    • required

• reCAPTCHA Configuration: This configuration enables Google reCAPTCHA validation for user-facing workflows.

  Path: external_services.recaptcha

  {
    "external_services": {
      "recaptcha": {
        "url": "https://www.google.com/recaptcha/api/siteverify",
        "site_key": "<site-key>",
        "secret_key": "<secret-key>"
      }
    }
  }

  Where,

  • url: Specifies the reCAPTCHA verification endpoint.

  • site_key: Specifies the public reCAPTCHA site key.

  • secret_key: Specifies the private reCAPTCHA secret key.

• Account Approval Policy: This setting configures notifications and approval requirements for new account creation requests.

  Path: policies.account_creation

  {
    "policies": {
      "account_creation": {
        "creation_notification_recipients": [
          "armor-account-creations@example.com"
        ],
        "pending_approval_notification_recipients": [
          "admin@example.com"
        ],
        "sysadmin_approval_required": "never"
      }
    }
  }

  Where,

  • creation_notification_recipients: Specifies the list of email addresses notified when a new account is created.

  • pending_approval_notification_recipients: Specifies the list of email addresses notified when an account is pending approval.

  • sysadmin_approval_required: Specifies whether sysadmin approval is required for account creation.

    Supported values include: never and always

• Email Validation Policy: This setting configures email address validation and verification requirements for user accounts.

  Path: policies.email_validation

  {
    "policies": {
      "email_validation": {
        "allowed_domains": [
          "fortanix.com",
          "example.com"
        ],
        "confirmation": "enabled",
        "maximum_length": "ietf_standard",
        "restricted_characters": [
          "#",
          "[",
          "]"
        ]
      }
    }
  }

  Where,

  • allowed_domains: Specifies the list of email domains permitted for user registration.

  • confirmation: Specifies the email verification behavior:

    • enabled: Email verification is mandatory.

    • not_enforced: Email verification is optional.

    • disabled: No email verification required.

  • maximum_length: Specifies the maximum allowed length for email addresses (for example, ietf_standard).

  • restricted_characters: Specifies the list of characters that are not allowed in email addresses.

• Identity Verification Policy: This setting configures the validity period for identity verification tickets.

  Path: policies.identity_verification

  {
    "policies": {
      "identity_verification": {
        "ticket_lifetime": 600
      }
    }
  }

  Where,

  • ticket_lifetime: Specifies the validity period, in seconds, for identity verification tickets.

• Password Policy: This setting configures password complexity, history, and password quality requirements.

  Path: policies.password

  {
    "policies": {
      "password": {
        "minimum_length": 12,
        "history_size": 5,
        "use_denylist": true
      }
    }
  }

  Where,

  • minimum_length: Specifies the minimum password length.

  • history_size: Specifies the number of previously used passwords that cannot be reused.

  • use_denylist: Specifies whether commonly used or weak passwords are rejected.

• Password Lockout Policy: This setting configures account lockout behavior after consecutive failed authentication attempts.

  Path: policies.password_auth_lockout

  {
    "policies": {
      "password_auth_lockout": {
        "allowed_attempts": 10,
        "lockout_behavior": {
          "$type": "temporary",
          "period": 1800
        }
      }
    }
  }

  Where,

  • allowed_attempts: Specifies the number of failed login attempts allowed before account lockout.

  • $type: Specifies the lockout behavior:

    • temporary

    • permanent

  • period: Specifies the lockout duration, in seconds.

• Session Expiry Policy: This setting configures session and token lifetimes for authenticated users.

  Path: policies.session_expiry

  {
    "policies": {
      "session_expiry": {
        "max_session_lifetime": 86400,
        "refresh_token_lifetime": 86400,
        "session_token_lifetime": 60
      }
    }
  }

  Where,

  • max_session_lifetime: Specifies the maximum duration, in seconds, for a user session.

  • refresh_token_lifetime: Specifies refresh token lifetime, in seconds.

  • session_token_lifetime: Specifies the session token lifetime, in seconds.

• Signup Policy: This setting configures whether users can create accounts through self-service signup.

  Path: policies.signup

  {
    "policies": {
      "signup": {
        "disable_signup": false
      }
    }
  }

  Where, disable_signup specifies whether self-service account registration is disabled.

• Third-Party Group Membership Policy: This setting configures the expiration period for memberships synchronized from third-party identity providers.

  Path: policies.third_party_group

  {
    "policies": {
      "third_party_group": {
        "expiry_days": 30
      }
    }
  }

  Where, expiry_days specifies the number of days after which third-party group memberships expire.

2.4 Example Sysadmin Configuration

The following is an example sysadmin configuration.

```json
{
  "auth_configs": {},
  "external_services": {
    "email": {
      "from_address": "no-reply@fortanix.com",
      "provider": {
        "$type": "amazon_ses",
        "url": "https://email.us-west-2.amazonaws.com/",
        "region": null,
        "access_key": "AKIARFH3AGIDJRQHIIGJ"
      }
    },
    "recaptcha": {
      "url": "https://www.google.com/recaptcha/api/siteverify",
      "site_key": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
    }
  },
  "policies": {
    "account_creation": {
      "creation_notification_recipients": [
        "armor-account-creations@fortanix.com"
      ],
      "pending_approval_notification_recipients": [
        "em-admin@fortanix.com"
      ],
      "sysadmin_approval_required": "always"
    },
    "email_validation": {
      "allowed_domains": [
        "fortanix.com",
        "example.com"
      ],
      "confirmation": "not_enforced",
      "maximum_length": "ietf_standard",
      "restricted_characters": [
        "$",
        "~",
        "`"
      ]
    },
    "identity_verification": {
      "ticket_lifetime": 600
    },
    "password": {
      "history_size": 1,
      "max_repetition": 6,
      "max_sequence": 3,
      "minimum_length": 12,
      "use_denylist": true
    },
    "password_auth_lockout": {
      "allowed_attempts": 2,
      "lockout_behavior": {
        "$type": "temporary",
        "period": 60
      }
    },
    "session_expiry": {
      "max_session_lifetime": 86400,
      "refresh_token_lifetime": 86400,
      "session_token_lifetime": 60
    },
    "signup": {
      "disable_signup": false
    },
    "third_party_group": {
      "expiry_days": 30
    }
  }
}
```