Single Sign-On (SSO)

Agent Action Firewall supports enterprise SSO via SAML 2.0, enabling centralized authentication through your identity provider.

• SAML 2.0 — Industry-standard SSO protocol
• JIT Provisioning — Automatic user creation on first login
• Domain Verification — Verified domain ownership required
• Role Mapping — Map IdP groups to AAF roles

Supported Identity Providers

AAF has been tested with:

Setup Process

Step 1: Verify Domain Ownership

Before configuring SSO, verify ownership of your email domain:

1. Go to Settings → SSO → Domains
2. Click Add Domain
3. Enter your domain (e.g., company.com)
4. Add the provided DNS TXT record
5. Click Verify

DNS record format:

_aaf-verification.company.com TXT "aaf-verify=abc123xyz"

Step 2: Configure Identity Provider

In your IdP, create a new SAML application with these settings:

Step 3: Download IdP Metadata

Download the SAML metadata XML from your IdP. This contains:

• IdP Entity ID
• SSO URL
• X.509 Certificate

Step 4: Configure AAF

1. Go to Settings → SSO
2. Click Configure SAML
3. Upload IdP metadata XML (or enter manually):
   • IdP Entity ID: From your IdP
   • SSO URL: IdP login endpoint
   • Certificate: X.509 certificate
4. Click Save

Step 5: Test Connection

1. Click Test SSO
2. You'll be redirected to your IdP
3. Log in with your IdP credentials
4. Verify you're redirected back to AAF

Attribute Mapping

Required Attributes

Optional Attributes

Custom Attribute Names

If your IdP uses different attribute names:

{
  "attribute_mapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
    "groups": "http://schemas.xmlsoap.org/claims/Group"
  }
}

Role Mapping

Map IdP groups to AAF roles:

Configuration

{
  "role_mapping": {
    "AAF-Admins": "admin",
    "AAF-Members": "member",
    "AAF-Viewers": "viewer"
  },
  "default_role": "member"
}

Group Sync

Configure in Settings → SSO → Role Mapping.

Just-In-Time (JIT) Provisioning

JIT provisioning automatically creates users on first SSO login.

Enabling JIT

1. Go to Settings → SSO → Provisioning
2. Enable Just-In-Time Provisioning
3. Configure default settings:
   • Default role
   • Default team
   • Auto-add to organization

JIT Settings

{
  "jit_provisioning": {
    "enabled": true,
    "default_role": "member",
    "default_team": "new-hires",
    "require_domain_match": true,
    "auto_activate": true
  }
}

Domain Restrictions

Only allow users from verified domains:

{
  "allowed_domains": ["company.com", "subsidiary.com"],
  "require_domain_match": true
}

Enforcement Modes

Optional SSO

Users can login via SSO or email/password:

• Good for gradual rollout
• SSO users see "Sign in with SSO" button
• Password users login normally

Required SSO

Force all users to authenticate via SSO:

1. Go to Settings → SSO → Enforcement
2. Select Require SSO for all users
3. Acknowledge existing password users will be migrated
4. Click Enable

Domain-Based Enforcement

Require SSO only for specific email domains:

{
  "enforce_sso_domains": ["company.com"],
  "allow_password_domains": ["contractors.company.com"]
}

SCIM Provisioning

For Enterprise customers, we support SCIM 2.0 for automated user provisioning.

SCIM Endpoint

https://api.agentactionfirewall.com/scim/v2

Supported Operations

Enabling SCIM

1. Go to Settings → SSO → SCIM
2. Click Enable SCIM
3. Copy the SCIM Endpoint URL and Bearer Token
4. Configure in your IdP

Security

Certificate Rotation

To rotate your IdP certificate:

1. Upload new certificate to AAF (keeps old one active)
2. Update certificate in IdP
3. Test SSO with new certificate
4. Remove old certificate from AAF

Session Settings

Configure SSO session behavior:

Audit Logging

All SSO events are logged:

IdP-Specific Guides

Okta

1. In Okta Admin: Applications → Create App Integration → SAML 2.0
2. Configure settings:
   • Single sign-on URL: https://auth.agentactionfirewall.com/saml/acs
   • Audience URI: https://agentactionfirewall.com/saml/sp
   • Name ID format: EmailAddress
3. Add attribute statements: email → user.email, firstName → user.firstName, lastName → user.lastName
4. Assign users or groups to the application
5. Go to the Sign On tab → View SAML setup instructions → download IdP metadata

Azure AD

1. Azure AD → Enterprise Applications → New Application → Create your own
2. Configure SSO:
   • Identifier: https://agentactionfirewall.com/saml/sp
   • Reply URL: https://auth.agentactionfirewall.com/saml/acs
3. Configure claims: Unique User Identifier → user.mail, email → user.mail, firstName → user.givenname, lastName → user.surname
4. Download Federation Metadata XML

Google Workspace

1. Admin Console → Apps → Web and mobile apps → Add custom SAML app
2. Configure settings:
   • ACS URL: https://auth.agentactionfirewall.com/saml/acs
   • Entity ID: https://agentactionfirewall.com/saml/sp
   • Name ID: Basic Information, Primary email
3. Map firstName and lastName to user attributes
4. Turn on access for relevant organizational units

Troubleshooting

SSO login fails with "Invalid SAML response"

1. Verify ACS URL is exactly correct (no trailing slash)
2. Check certificate hasn't expired
3. Ensure NameID is user's email address
4. Verify clock skew is less than 5 minutes

User not provisioned on first login

1. Check JIT provisioning is enabled
2. Verify user's email domain is verified
3. Ensure require_domain_match settings are correct
4. Check IdP is sending required attributes

Role not assigned correctly

1. Verify IdP is sending groups attribute
2. Check role mapping configuration
3. Ensure group names match exactly (case-sensitive)
4. Check group sync mode (additive vs exclusive)

Cannot log in after enabling required SSO

1. Verify your user exists in IdP
2. Check email matches between IdP and AAF
3. Contact AAF support to temporarily disable enforcement
4. Use emergency bypass URL if provided

Emergency Access

Bypass URL

Enterprise customers receive an emergency bypass URL:

https://agentactionfirewall.com/login?bypass_sso=true&token=<emergency_token>

This allows login with password when IdP is unavailable.

Recovery Contacts

Designate recovery contacts who can disable SSO enforcement:

1. Go to Settings → SSO → Recovery
2. Add recovery email addresses
3. These users can disable SSO via email verification