Security Architecture
GrantFlow employs a defense-in-depth approach to protect privileged credentials. This page describes the cryptographic controls that safeguard account passwords throughout their lifecycle—from storage through to secure reveal in your browser.
Overview
Protecting privileged credentials requires multiple layers of encryption. GrantFlow never stores plaintext passwords in databases and uses industry-standard cryptographic algorithms to ensure that sensitive data remains protected at rest, in transit, and even during the brief moment when credentials are revealed to authorized users.
The security architecture addresses four key scenarios:
- At-rest protection: Passwords stored in Azure Key Vault with envelope encryption
- In-transit protection: TLS 1.3 for all network communication
- End-to-end protection: Browser-to-server encryption ensuring only your browser can decrypt revealed passwords
- Agent communication: Mutual TLS with certificate-based identity for on-premises agent connections
End-to-End Encrypted Password Reveal
When you check out an account and reveal its password, GrantFlow uses end-to-end encryption to ensure the credential is protected from the moment it leaves storage until it appears in your browser. Even GrantFlow's own servers cannot see the plaintext password during transmission.
How It Works
The password reveal process uses ephemeral RSA key pairs generated in your browser:
-
Key generation: Your browser generates a unique RSA-2048 key pair using the Web Crypto API. The private key is marked as non-extractable, meaning it cannot be exported or accessed by JavaScript—only the browser's cryptographic engine can use it.
-
Public key exchange: Your browser sends only the public key to GrantFlow's server when you request to reveal a password.
-
Server-side encryption: The server retrieves the password from secure storage, encrypts it using your public key with RSA-OAEP-256 (SHA-256 padding), and returns the ciphertext.
-
Browser-side decryption: Your browser decrypts the ciphertext using the non-extractable private key. The plaintext password is displayed and held only in browser memory.
-
Key expiration: The ephemeral key pair is valid for a limited time (default one hour, maximum 24 hours). After expiration, a new key pair is generated for subsequent reveals.
┌─────────────────────────────────────────────────────────────────────────┐
│ END-TO-END ENCRYPTED REVEAL │
│ │
│ Browser Server │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Generate │ │ │ │
│ │ RSA-2048 │──── Public ─────▶│ Encrypt │ │
│ │ Key Pair │ Key │ Password │ │
│ │ │ │ with RSA- │ │
│ │ Private Key │◀── Ciphertext ───│ OAEP-256 │ │
│ │ (locked in │ │ │ │
│ │ browser) │ └─────────────┘ │
│ │ │ │
│ │ Decrypt │ │
│ │ ───────────▶│ Plaintext visible only here │
│ └─────────────┘ │
└───────────────────────────────────── ────────────────────────────────────┘
Security Properties
This design provides several important security guarantees:
| Property | Description |
|---|---|
| Forward secrecy | Each reveal uses a fresh key pair. Compromising one key doesn't expose past or future reveals. |
| Non-extractable keys | The browser's private key cannot be exported, even by malicious JavaScript. |
| No server-side plaintext in transit | The password is encrypted before leaving the server and decrypted only in your browser. |
| Time-limited keys | Keys expire automatically, limiting the window for potential attacks. |
| No key storage | Private keys exist only in browser memory and are lost when the page closes. |
Key Lifecycle
Ephemeral keys have a configurable lifetime to balance security with usability:
| Setting | Default | Maximum | Description |
|---|---|---|---|
| Key validity | 1 hour | 24 hours | How long a key pair remains valid |
| Auto-regeneration | Enabled | — | New keys generated automatically when current ones expire |
When your key approaches expiration, GrantFlow automatically generates a new key pair in the background. If you're in the middle of a workflow, you won't notice any interruption.
Browser Requirements
End-to-end encryption requires a modern browser with Web Crypto API support:
- Chrome 37+ / Edge 79+
- Firefox 34+
- Safari 11+
All modern browsers that support these versions implement the required cryptographic primitives (RSA-OAEP with SHA-256, non-extractable key generation).
At-Rest Encryption
Beyond end-to-end protection during reveal, GrantFlow protects passwords at rest using multiple layers:
Azure Key Vault Storage
Account passwords are stored as secrets in Azure Key Vault, which provides:
- Hardware Security Modules (HSM): Keys protected by FIPS 140-2 Level 2 validated HSMs
- Encryption at rest: AES-256 encryption managed by Azure
- Access logging: All secret access logged for audit purposes
- Soft delete and purge protection: Protection against accidental or malicious deletion
In-Memory Cache Encryption
When passwords are cached temporarily in memory (for performance during active checkouts), they're protected with AES-256-GCM encryption:
- Runtime keys: Encryption keys are generated at service startup and never persisted
- Per-tenant isolation: Each tenant's cached secrets use separate encryption
- Automatic expiration: Cached entries expire and are securely cleared
This ensures that even if server memory were somehow exposed, cached credentials remain encrypted.
Password Rotation Security
When GrantFlow rotates a password (on checkout, check-in, or schedule), the security architecture ensures:
- Generation: New passwords are generated using cryptographically secure random number generators
- Transmission: Passwords are transmitted to target systems over encrypted channels (LDAPS for AD, TLS for Entra ID)
- Storage: The new password is immediately encrypted and stored in Key Vault
- Old password purging: Previous password versions are marked for deletion per retention policy
At no point is a password written to disk in plaintext or logged.
Agent Communication Security
GrantFlow agents run on your network to execute Active Directory operations. Communication between agents and the GrantFlow control plane uses multiple layers of cryptographic protection.
Mutual TLS (mTLS)
All agent-to-control-plane communication uses mutual TLS, where both parties authenticate each other with certificates:
┌─────────────────────────────────────────────────────────────────────────┐
│ AGENT ↔ CONTROL PLANE mTLS │
│ │
│ Your Network GrantFlow Cloud │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ Agent │ │ Control Plane │ │
│ │ │───── mTLS gRPC ────▶│ │ │
│ │ Certificate │ (TLS 1.3) │ Certificate │ │
│ │ issued by │◀────────────────────│ validates │ │
│ │ GrantFlow │ │ agent cert │ │
│ └─────────────┘ └─────────────────┘ │
│ │ │
│ │ Outbound only (TCP/443) │
│ │ No inbound firewall rules required │
└─────────────────────────────────────────────────────────────────────────┘
Key security properties:
| Property | Description |
|---|---|
| Mutual authentication | Both agent and control plane present certificates—neither can impersonate the other |
| TLS 1.3 | Latest TLS version with forward secrecy and improved cipher suites |
| Outbound-only | Agents connect outward; no inbound firewall rules needed on your network |
| Certificate binding | Agent identity (agent ID, tenant ID) is cryptographically embedded in the certificate |
Agent Enrollment
Before an agent can connect, it must complete a secure enrollment process:
- Token generation: An administrator generates a single-use enrollment token in GrantFlow (valid for ~1 hour)
- Key pair generation: The agent generates an RSA key pair locally
- Certificate signing request: The agent creates a CSR and submits it with the token to the enrollment service
- Certificate issuance: GrantFlow validates the token and issues a signed certificate
- Identity binding: The certificate embeds the agent ID and tenant ID, preventing certificate reuse across tenants
┌─────────────────────────────────────────────────────────────────────────┐
│ AGENT ENROLLMENT FLOW │
│ │
│ Admin Portal Agent Enrollment Control │
│ Service Plane │
│ │ │ │ │ │
│ │─── Generate ────▶│ │ │ │
│ │ Token │ │ │ │
│ │◀── Token ────────│ │ │ │
│ │ │ │ │ │
│ │ ┌───────────┤ │ │ │
│ │ │ Generate │ │ │ │
│ │ │ RSA keys │ │ │ │
│ │ │ + CSR │ │ │ │
│ │ └───────────┤ │ │ │
│ │ │ │ │ │
│ │ │─── CSR + Token ───▶│ │ │
│ │ │ │── Validate ──▶│ │
│ │ │ │◀── OK ────────│ │
│ │ │ │ │ │
│ │ │◀── Certificate ────│ │ │
│ │ │ + CA Chain │── Complete ──▶│ │
│ │ │ │ Enrollment │ │
│ │ │ │ │ │
│ │ │═══ mTLS gRPC ═════════════════════ ▶│ │
│ │ │ (using new cert) │ │
└─────────────────────────────────────────────────────────────────────────┘
Enrollment Token Security
Enrollment tokens are designed to be secure even if intercepted:
| Protection | Implementation |
|---|---|
| Single-use | Token is invalidated immediately after successful enrollment |
| Short-lived | Tokens expire after approximately 1 hour |
| Cryptographically random | 32 bytes from a secure random source |
| Hashed storage | Tokens are stored as Argon2id hashes—never in plaintext |
| Never logged | Tokens never appear in logs or audit trails |
| Displayed once | Shown only at creation; cannot be retrieved later |
Argon2id is a memory-hard password hashing algorithm that won the Password Hashing Competition. It provides strong resistance against GPU-based brute force attacks.
Certificate Security
Agent certificates provide strong identity guarantees:
| Property | Implementation |
|---|---|
| Algorithm | RSA-2048 or higher (RSA-4096 recommended) |
| Signing | Certificates signed via Azure Key Vault (ECDSA P-256) |
| Validity | 90 days with automatic renewal before expiry |
| Identity binding | Agent ID in CN, Tenant ID in OU—cryptographically enforced |
| Revocation support | Certificates can be revoked instantly via the admin portal |
| Validation | Control plane validates certificate on every gRPC request |
The use of Azure Key Vault for certificate signing ensures that the CA private key is protected by hardware security modules (HSMs) and never leaves the secure boundary.
When you revoke an agent, its certificate is immediately invalidated and all active connections are terminated.
Message-Level Encryption
Beyond TLS, every message between agent and control plane is additionally encrypted:
- Session keys: Derived from the TLS session using RFC 8446 exporters
- AEAD encryption: XChaCha20-Poly1305 authenticated encryption on every protobuf message
- Replay protection: Monotonically increasing sequence numbers prevent message replay
- AAD binding: Associated data binds each message to tenant ID, agent ID, and job ID
This defense-in-depth approach means that even if TLS were somehow compromised, individual messages remain protected.
Network Requirements
Agents require only outbound HTTPS connectivity:
| Destination | Port | Purpose |
|---|---|---|
enrollment.grantflow.cloud | 443 | Initial enrollment (one-time) |
agents.grantflow.cloud | 443 | Ongoing agent communication |
No inbound ports need to be opened on your firewall. This significantly reduces your attack surface compared to solutions requiring inbound connections.
API Authentication
GrantFlow's API uses industry-standard authentication protocols to verify user and service identities.
OIDC/PKCE Authentication
User authentication follows the OpenID Connect (OIDC) protocol with PKCE (Proof Key for Code Exchange):
| Property | Implementation |
|---|---|
| Identity provider | Microsoft Entra ID (Azure AD) |
| Flow | Authorization Code with PKCE |
| Token format | JWT (JSON Web Token) with RS256 signature |
| Token validation | Signature, issuer, audience, expiration, not-before |
| Multi-tenant | Accepts tokens from any Entra ID tenant; validates via database lookup |
JWT Security
Every API request is authenticated using JWT tokens:
- Signature verification: Tokens are verified against Microsoft's public keys (JWKS)
- Issuer validation: Only tokens from legitimate Entra ID issuers are accepted
- Audience validation: Tokens must be issued for GrantFlow's API
- Expiration enforcement: Expired tokens are rejected
- Claims extraction: User identity, roles, and tenant are extracted once in middleware
- Immutable principal: Extracted claims cannot be modified by downstream code
Compliance Alignment
GrantFlow's security architecture helps you meet various compliance requirements:
| Framework | Relevant Controls | How GrantFlow Helps |
|---|---|---|
| SOC 2 Type II | CC6.1 (Encryption) | End-to-end encryption, Key Vault storage, mTLS agent communication |
| SOC 2 Type II | CC6.6 (Logical access) | JWT authentication, OIDC/PKCE, role-based access control |
| ISO 27001 | A.10.1.1 (Cryptographic controls) | RSA-2048, AES-256-GCM, TLS 1.3, Argon2id, documented key management |
| ISO 27001 | A.13.1.1 (Network controls) | Outbound-only agent connections, no inbound firewall rules |
| GDPR | Art. 32 (Security of processing) | Encryption at rest and in transit, certificate-based agent identity |
| NIST 800-53 | SC-8 (Transmission confidentiality) | TLS 1.3, end-to-end encryption, mTLS for agent communication |
| NIST 800-53 | IA-3 (Device identification) | Certificate-based agent authentication with identity binding |
| NIST 800-53 | IA-5 (Authenticator management) | Argon2id for token hashing, HMAC-SHA256 for callbacks |
Audit Trail
Security-related operations are logged for compliance and forensic purposes. The following events appear in the Activity Log:
| Event | What's Logged | What's Never Logged |
|---|---|---|
| Password reveal | Timestamp, user, account ID, public key fingerprint | Plaintext password, private key |
| Password rotation | Timestamp, account ID, trigger (checkout/checkin/schedule), outcome | New or old password |
| Agent enrollment | Agent ID, tenant ID, certificate fingerprint, enrolled by | Enrollment token |
| Agent revocation | Agent ID, revoked by, reason, timestamp | — |
| User login | User ID, tenant ID, timestamp, source IP | JWT token, credentials |
| Job callbacks | Job ID, job type, outcome | Callback token |
Internal cryptographic operations (key generation, encryption primitives) are not logged as separate audit events—they occur as part of the operations listed above.
These audit events are available in the Audit Events page and via the API.
Coming Soon: Customer-Managed Keys (BYOK)
Customer-managed keys will be available as an enterprise feature. Contact your account representative to learn more about early access.
GrantFlow is developing support for customer-managed encryption keys, also known as Bring Your Own Key (BYOK). This feature gives enterprise customers complete control over the encryption keys protecting their privileged credentials.
Why Customer-Managed Keys?
For organizations with strict data sovereignty requirements, managed encryption may not provide sufficient control. Customer-managed keys address these needs:
| Requirement | How BYOK Helps |
|---|---|
| Data sovereignty | Encryption keys remain in your Azure tenant—GrantFlow cannot decrypt without your key |
| Key lifecycle control | You control rotation, revocation, and destruction schedules |
| Audit visibility | Full key usage logging in your own Azure Key Vault |
| Compliance | Meet requirements for SOC 2, ISO 27001, BSI C5, and industry-specific regulations |
| Emergency revocation | Instantly revoke GrantFlow's access by disabling the key |
Envelope Encryption Architecture
With customer-managed keys, GrantFlow uses envelope encryption:
┌─────────────────────────── ──────────────────────────────────────────────┐
│ ENVELOPE ENCRYPTION FLOW │
│ │
│ Plaintext Customer's Encrypted GrantFlow │
│ Password ───► RSA Key ───► Ciphertext ───► Key Vault │
│ (in customer's (Base64) (Secret) │
│ Key Vault) │
│ │
│ Storage: Only encrypted ciphertext stored in GrantFlow's Key Vault │
│ Control: Customer controls the RSA key—can revoke access anytime │
└─────────────────────────────────────────────────────────────────────────┘
- Your RSA key: You create and manage an RSA-2048 (or RSA-4096) key in your own Azure Key Vault
- Encryption: Before storing a password, GrantFlow encrypts it using your key
- Storage: The encrypted ciphertext is stored as a secret in GrantFlow's Key Vault
- Decryption: When retrieving a password, GrantFlow calls your Key Vault to decrypt
The plaintext password never exists in GrantFlow's infrastructure—only encrypted ciphertext.
Encryption Modes
Three modes will be available to match different organizational needs:
| Mode | Description | Best For |
|---|---|---|
| Managed (default) | GrantFlow manages the encryption key | Most customers—simple, no setup required |
| Customer Vault | Your RSA key in your Azure Key Vault, accessed via federated identity | Enterprises requiring key control without credential exchange |
| Customer Service Principal | Your RSA key accessed via service principal you provide | Organizations with existing key management processes |
Setup Overview
Setting up customer-managed keys involves:
- Create a Key Vault in your Azure tenant (or use an existing one)
- Create an RSA key for password encryption (RSA-2048 minimum, RSA-4096 recommended)
- Grant GrantFlow access with the "Key Vault Crypto User" role (encrypt/decrypt only—no secret access)
- Configure in GrantFlow via the Admin settings
- Validate the connection with a test encrypt/decrypt roundtrip
- Migrate existing passwords to the new key (optional, can be gradual)
Detailed setup instructions will be provided when this feature becomes available.
Security Model
Customer-managed keys provide additional security guarantees:
| Scenario | With Managed Keys | With Customer Keys |
|---|---|---|
| GrantFlow database breach | Attacker gets Key Vault secret references (need KV access) | Attacker gets encrypted ciphertext (need your key) |
| GrantFlow Key Vault breach | Attacker gets plaintext passwords | Attacker gets encrypted ciphertext (need your key) |
| You revoke GrantFlow access | N/A | Immediate—passwords become unreadable |
| Key rotation | Managed by GrantFlow | Controlled by you, migration tool provided |
Access Requirements
GrantFlow requires minimal permissions in your Key Vault:
# Required RBAC role
role: "Key Vault Crypto User"
# Specific permissions needed
permissions:
- Microsoft.KeyVault/vaults/keys/encrypt/action
- Microsoft.KeyVault/vaults/keys/decrypt/action
- Microsoft.KeyVault/vaults/keys/read # For validation only
# NOT required (secrets stay in GrantFlow's vault)
# - Microsoft.KeyVault/vaults/secrets/*
GrantFlow never has access to your Key Vault secrets—only cryptographic operations on keys.
Migration Support
When enabling customer-managed keys, you can migrate existing passwords:
- Gradual migration: New passwords use your key; existing passwords remain with managed encryption
- Bulk migration: Re-encrypt all existing passwords with your key
- Rollback capability: If you disable BYOK, passwords can be re-encrypted with managed keys
The migration process is non-destructive and maintains password availability throughout.
FAQ
End-to-End Encryption
Why generate keys in the browser instead of using TLS alone?
TLS protects data in transit, but the server still sees plaintext. End-to-end encryption ensures that even if someone gained access to our servers during a reveal operation, they would only see encrypted data. Your browser is the only place where the password exists in plaintext.
What happens if my browser tab crashes during a reveal?
The ephemeral private key is lost, but you can simply reveal the password again. A new key pair will be generated, and the server will re-encrypt the password for you.
Can browser extensions access the revealed password?
Extensions with sufficient permissions could theoretically read DOM content after you've revealed a password. We recommend using a clean browser profile for privileged access management and reviewing installed extensions.
Customer-Managed Keys
What happens if I accidentally delete my key?
Azure Key Vault's soft delete and purge protection (which we recommend enabling) gives you a recovery window. If the key is permanently destroyed, passwords encrypted with it become unrecoverable. We strongly recommend maintaining key backups per your disaster recovery procedures.
Can I use the same key for multiple tenants?
Yes, but we recommend separate keys for tenant isolation. Each password is tagged with its key version, so rotation and revocation can be managed independently.
How does key rotation work?
When you rotate your key in Azure Key Vault, new passwords are encrypted with the new version. Existing passwords remain readable (Key Vault maintains version history). You can use our migration tool to re-encrypt all passwords with the latest version.
Agent Security
What happens if an agent's certificate is compromised?
Immediately revoke the agent from the GrantFlow admin portal. This invalidates the certificate and terminates all active connections. The compromised certificate cannot be used to connect again. Then enroll a new agent with a fresh certificate.
Can I use my own CA for agent certificates?
Currently, GrantFlow issues all agent certificates from our managed CA. This ensures consistent security properties and simplifies certificate lifecycle management. Customer-managed agent CAs may be considered for future enterprise features.
How often are agent certificates renewed?
Agent certificates are valid for one year. The agent automatically requests renewal before expiry, so no manual intervention is required. You can monitor certificate expiration dates in the agent management interface.
Related Topics
- Account Checkout — How users reveal passwords
- Active Directory Agents — Installing and managing on-premises agents
- Audit Events — Viewing cryptographic operation logs
- Connector Management — Managing identity provider connections