FedRAMP Security Admin Guide

This guide provides comprehensive information on securely managing top-level administrative accounts in Descope's customer-facing applications. It covers administrative role definitions, account lifecycle procedures, and security settings to help organizations maintain FedRAMP compliance and follow secure configuration best practices.

FedRAMP Compliance Considerations

Descope supports FedRAMP security requirements through the following capabilities:

1. Access Control: Role-based access control with least-privilege enforcement
2. Multi-Factor Authentication: Support for FIDO2/WebAuthn, TOTP, and SMS OTP
3. Audit Logging: Comprehensive logging of all authentication and administrative events
4. Session Management: Configurable session timeouts and inactivity detection
5. Data Residency: Region-specific data storage (US, EU, AU)
6. Encryption: TLS 1.2+ for data in transit; AES-256 for data at rest
7. Secure Configuration: Extensive security settings with secure defaults

Administrative Account Role Definitions

Descope provides hierarchical administrative roles with distinct permissions and operational capabilities. Understanding these roles is critical for implementing least-privilege access control.

Company-Level Administrative Roles

Company-level roles apply across all projects within a Descope company and provide varying levels of administrative access.

Company Admin

Privilege Level: Highest administrative privilege across the entire company

Permissions and Actions:

• Full read/write access to all company settings
• Full read/write access to all projects within the company
• Manage all Descopers (create, modify, delete administrative users)
• Create and manage management keys with any permission level
• Configure company-wide SSO settings
• Enforce MFA requirements for all Descopers
• Configure SCIM provisioning for company access
• Access and modify all project configurations
• Manage project creation, cloning, export, and deletion
• View and manage all tenants across all projects
• Full access to audit logs across all projects

Security Impact: Company Admins have unrestricted access to all resources and configurations. This role should be assigned only to senior administrators who require full organizational control.

Recommended Assignment: Limit to 2-3 trusted senior administrators per organization.

Project Admin

Privilege Level: Full administrative access to assigned projects

Permissions and Actions:

• Full read/write access to assigned project(s) settings
• Configure authentication methods and flows
• Manage users, tenants, and access keys within assigned projects
• Configure authorization (roles, permissions, RBAC, FGA)
• Manage connectors and integrations
• Configure SSO applications and identity federation
• Manage project-level security settings
• Access audit logs for assigned projects
• Cannot access company-level settings
• Cannot manage Descopers or management keys

Security Impact: Project Admins have full control over project resources but are isolated from company-wide settings and other projects.

Recommended Assignment: Assign to project leads and senior engineers responsible for specific applications.

Project Developer

Privilege Level: Read/write access to project configurations, excluding sensitive settings

Permissions and Actions:

• Read/write access to authentication methods and flows
• Read/write access to authorization configurations
• Read/write access to connectors and integrations
• Manage users, tenants, and access keys
• View and modify project settings (excluding company-level settings)
• Access audit logs for assigned projects
• Cannot manage Descopers or company settings
• Cannot manage management keys
• Cannot delete projects or modify critical security settings

Security Impact: Developers can configure application behavior but cannot access company-wide administrative functions.

Recommended Assignment: Assign to development team members who need to configure authentication and authorization.

Project Support

Privilege Level: Read-only access to most configurations, read/write access to user management

Permissions and Actions:

• Read-only access to authentication methods, flows, connectors, IdP apps, authorization, and project settings
• Full read/write access to users, access keys, tenants, and audit logs
• Can assist users with account issues and password resets
• Can create and manage test users
• Cannot modify authentication methods, flows, or security configurations
• Cannot access company-level settings

Security Impact: Support personnel can assist users without the ability to modify security-critical configurations.

Recommended Assignment: Assign to customer support team members who need to help users with account issues.

Tenant-Level Administrative Roles

Tenant-level roles provide administrative capabilities scoped to specific tenants (multi-tenant applications).

Tenant Admin

Privilege Level: Full administrative access within a specific tenant

Permissions and Actions:

• Full user management within the tenant (create, modify, delete users)
• Assign roles and permissions to tenant users
• Configure tenant-specific SSO settings (with SSO Admin permission)
• Manage tenant-level roles and permissions
• Generate and manage access keys for tenant users (with appropriate permissions)
• Access tenant-specific audit logs
• Configure tenant profile and settings
• Impersonate users within the tenant (with Impersonate permission)
• Cannot access other tenants or project-level settings

Required Permissions:

• User Admin: Required for reading and modifying user data within the tenant
• SSO Admin: Required for reading and modifying tenant SSO configurations
• Impersonate: Required for acting on behalf of another user in the tenant

Security Impact: Tenant Admins have full control over tenant resources but are isolated from other tenants and project-wide settings.

Recommended Assignment: Assign to customer organization administrators in B2B applications.

Management Keys and Service Accounts

Management keys provide programmatic access to Descope's Management APIs for automated operations.

Privilege Levels:

• Company-level management keys: Access to all projects and company settings
• Project-level management keys: Access to specific project resources
• Tenant-level management keys: Access to specific tenant resources

Available Roles for Management Keys:

• Full Management: Complete read/write access to management APIs
• User Management: User CRUD operations only
• Tenant Management: Tenant CRUD operations only
• Access Key Management: Access key CRUD operations only
• FGA Read/Write: Fine-grained authorization read/write operations
• Descoper Access (SCIM): SCIM provisioning for Descope console access

Security Impact: Management keys provide powerful programmatic access and should be treated as highly sensitive credentials.

Recommended Practices:

• Use the principle of least privilege when assigning management key roles
• Generate separate keys for different automation purposes
• Rotate management keys regularly (at least every 90 days)
• Store keys securely in secrets management systems (e.g., HashiCorp Vault, AWS Secrets Manager)
• Never commit management keys to version control
• Monitor management key usage through audit logs

Admin Account Lifecycle Procedures

This section describes procedures for securely managing administrative accounts throughout their lifecycle.

Initial Account Setup

Creating Company Admin Accounts

1. Account Creation:

   • Navigate to Company Settings > Descopers
   • Click "+ Descoper" to create a new administrative account
   • Enter the administrator's email address
   • Select "Full access" or configure granular permissions with "Company Admin" role
   • Optionally send an invitation email

2. Initial Authentication:

   • If invitation email is sent, the administrator receives an email with authentication instructions
   • Administrator completes initial authentication using configured methods (email OTP, magic link, SSO, or passkey)
   • If MFA is enforced (recommended), administrator must enroll in MFA during first login

3. Post-Setup Verification:

   • Verify the account appears in the Descopers list with correct role assignment
   • Test account access by logging into the Descope console
   • Verify the administrator can access intended resources and configurations

Creating Project/Tenant Admin Accounts

1. Project Admin Creation:

   • Navigate to Company Settings > Descopers
   • Click "+ Descoper"
   • Enter administrator's email address
   • Select "Granular permissions"
   • Choose specific projects or tags and assign "Admin", "Developer", or "Support" role
   • Send invitation email

2. Tenant Admin Creation:

   • Navigate to Users in the relevant project
   • Click "+ User" to create a new user account
   • Enter user details and select the appropriate tenant
   • Navigate to the user's details and assign the "Tenant Admin" role for the tenant
   • Alternatively, use the User Management Widget to allow existing Tenant Admins to create new admin accounts

3. Role Assignment Verification:

   • Verify role assignment in the user's profile
   • Test account access to ensure proper tenant isolation
   • Verify the administrator cannot access resources outside their assigned scope

Multi-Factor Authentication (MFA) Requirements

MFA is a critical security control for all administrative accounts and should be enforced as a baseline security requirement.

Enforcing MFA for Company Administrators

1. Company-Wide MFA Enforcement:

   • Navigate to Company Settings > Settings
   • Under "Console Access", enable "Enforce MFA"
   • Supported MFA methods:
     • Passkeys (FIDO2/WebAuthn) - Strongest authentication method, recommended
     • TOTP (Time-based One-Time Password) - Compatible with authenticator apps (Google Authenticator, Authy, etc.)
     • OTP via SMS - Text message-based verification (less secure, use only if other methods unavailable)

2. Administrator MFA Enrollment:

   • Upon next login after MFA enforcement, administrators are prompted to enroll in MFA
   • Administrator selects preferred MFA method and completes enrollment
   • Backup MFA methods should be configured for account recovery

3. MFA Verification:

   • After enrollment, administrators must complete MFA verification on each login
   • MFA is required for all administrative sessions

Enforcing MFA for End-User Administrators (Tenant Admins)

1. Project-Level MFA Configuration:

   • MFA for tenant admins and end users is configured through Descope Flows
   • Navigate to Flows
   • Edit the relevant authentication flow (e.g., "sign-up-or-in")
   • Add MFA steps to the flow:
     • TOTP enrollment and verification
     • OTP via SMS enrollment and verification
     • Passkey enrollment and verification (recommended)

2. Conditional MFA Based on Role:

   • Use flow conditions to enforce MFA only for users with administrative roles
   • Example condition: Check if user has "Tenant Admin" role, then require MFA
   • This allows flexible MFA policies based on risk level

3. Step-Up Authentication:

   • For highly sensitive operations, implement step-up authentication
   • Configure step-up flows that require re-authentication with MFA
   • Use step-up tokens with short expiration times (5-15 minutes)

MFA Backup and Recovery

1. Backup Authentication Methods:

   • Administrators should enroll in multiple MFA methods
   • Store backup codes securely for emergency access
   • Document MFA recovery procedures for locked-out administrators

2. MFA Reset Procedures:

   • Company Admins can reset MFA for Descopers through the Descope console
   • For Tenant Admins, Project Admins can reset MFA through user management
   • MFA resets should be logged and monitored for security incidents

Account Configuration Best Practices

Strong Authentication Configuration

1. Disable Weak Authentication Methods:

   • For administrative accounts, disable password-based authentication in favor of:
     • Passkeys (FIDO2/WebAuthn) - Hardware security keys or platform authenticators
     • SSO with enterprise identity provider
     • Magic links with email verification
   • If passwords must be used, enforce strong password policies through flow configurations

2. Configure Session Timeouts:

   • Navigate to Project Settings > Session Management
   • Configure appropriate session token timeouts:
     • Session Token Timeout: 15-60 minutes for administrative sessions
     • Refresh Token Timeout: 1-7 days depending on security requirements
   • Enable Session Inactivity detection:
     • Set inactivity timeout to 15-30 minutes for administrative accounts
     • Idle sessions will automatically expire to prevent unauthorized access

3. Enable Refresh Token Rotation:

   • Navigate to Project Settings > Session Management
   • Enable "Refresh Token Rotation" for enhanced security
   • Each session refresh generates a new refresh token, invalidating the previous one
   • Helps detect and prevent token theft

Audit Logging Configuration

1. Enable Comprehensive Audit Logging:

   • All administrative actions are automatically logged in Descope
   • Access audit logs at Audit
   • Audit logs include:
     • User authentication events (login, logout, MFA)
     • Administrative actions (user creation, role changes, configuration updates)
     • API calls via management keys
     • SSO configuration changes
     • Access key generation and usage

2. Audit Log Monitoring:

   • Regularly review audit logs for suspicious activity
   • Use the Audit Widget to provide tenant admins with visibility into tenant-specific events
   • Export audit logs for integration with SIEM systems
   • Set up alerts for critical administrative actions

3. Audit Log Retention:

   • Descope retains audit logs according to your subscription plan
   • For compliance requirements, export and archive logs regularly
   • Maintain logs for at least 90 days (recommended: 1 year for administrative actions)

Account Modification and Access Reviews

Regular Access Reviews

1. Quarterly Access Review Process:

   • Review all Descoper accounts every 90 days
   • Navigate to Company Settings > Descopers
   • Verify each administrator still requires their assigned role
   • Remove access for administrators who no longer need it
   • Document access review outcomes

2. Tenant Admin Access Review:

   • Review Tenant Admin assignments quarterly
   • Use the Role Management Widget or Users page to review role assignments
   • Verify tenant admins are assigned to correct tenants
   • Remove unnecessary administrative privileges

3. Management Key Review:

   • Review all management keys every 90 days
   • Navigate to Company Settings > Management Keys
   • Verify each key is still needed and being used
   • Rotate or delete unused management keys
   • Verify keys follow least-privilege principle

Role and Permission Changes

1. Modifying Descoper Roles:

   • Navigate to Company Settings > Descopers
   • Click the menu (three dots) next to the Descoper's name
   • Select "Edit" to modify permissions
   • Change between "Full access" and "Granular permissions"
   • Update project/tag assignments and roles
   • Save changes

2. Modifying Tenant Admin Roles:

   • Navigate to Users
   • Search for and select the user
   • In the user details, navigate to the "Roles" section
   • Add or remove the "Tenant Admin" role or associated permissions
   • Changes take effect immediately for new sessions

3. Change Documentation:

   • Document all role and permission changes
   • Record justification for privilege changes
   • Use audit logs to track who made changes and when

Account Decommissioning

Proper account decommissioning is critical to prevent unauthorized access after an administrator leaves the organization or changes roles.

Descoper Account Decommissioning

1. Immediate Deactivation:

   • Upon administrator departure or role change, immediately disable account access
   • Navigate to Company Settings > Descopers
   • Click the menu (three dots) next to the Descoper's name
   • Select "Delete" to remove the Descoper account
   • Descoper is immediately logged out and cannot access the console

2. Session Invalidation:

   • Deletion of a Descoper account immediately invalidates all active sessions
   • The administrator is logged out of the Descope console
   • All associated access tokens are revoked

3. Management Key Rotation:

   • If the departing administrator had access to management keys, rotate those keys immediately
   • Navigate to Company Settings > Management Keys
   • Delete compromised keys
   • Generate new keys and update applications that use them
   • Verify no orphaned keys remain

Tenant Admin Account Decommissioning

1. Remove Tenant Admin Role:

   • Navigate to Users
   • Search for and select the user
   • Remove the "Tenant Admin" role and associated permissions (SSO Admin, User Admin, Impersonate)
   • Alternatively, use the User Management Widget for tenant-scoped admin removal

2. Optional: Full User Account Deletion:

   • If the user no longer needs any access to the application, delete the user account
   • In the user details, click the menu (three dots)
   • Select "Delete User"
   • User is immediately logged out and cannot access the application

3. Access Key Revocation:

   • If the user had generated any access keys (M2M tokens), revoke them
   • Navigate to Access Keys
   • Search for keys associated with the user
   • Deactivate or delete the access keys

Post-Decommissioning Verification

1. Verify Account Removal:

   • Confirm the account no longer appears in the Descopers list (for Descopers)
   • Confirm the user no longer has administrative roles (for Tenant Admins)
   • Attempt to log in with the decommissioned account to verify access is denied

2. Audit Log Review:

   • Review audit logs to confirm decommissioning actions were completed
   • Document decommissioning date and administrator who performed the action
   • Verify no suspicious activity occurred during the administrator's final sessions

3. Resource Handoff:

   • If the administrator managed specific resources (flows, connectors, etc.), reassign ownership
   • Document any pending work or configurations the administrator was responsible for
   • Update team documentation to reflect role changes

Security Settings Reference

This section provides a comprehensive reference of all administrative security settings, their functions, security impacts, and recommended values.

Company-Level Security Settings

These settings are configured at the company level and apply across all projects or to specific projects.

Project-Level Security Settings

These settings are configured per project and control security behavior for end users and tenant administrators.

Authorization and Role-Based Access Control (RBAC) Settings

These settings control user roles, permissions, and tenant-based access.

Authentication Method Security Settings

These settings control which authentication methods are available and their security configurations.

Rate Limiting and Abuse Prevention Settings

These settings protect against brute force attacks and API abuse.

Data Protection and Privacy Settings

These settings control data handling, encryption, and privacy.

Audit and Monitoring Settings

These settings control logging, monitoring, and visibility into system activity.

Advanced Security Settings

These settings provide additional security controls for specific use cases.

Additional Resources

For more information on security features and best practices in Descope, refer to the following documentation:

• Company Settings - Managing Descopers and company-level configuration
• Role-Based Access Control - Configuring roles and permissions
• Admin Widgets - Implementing user, role, and audit management for tenant admins
• Session Management - Configuring session tokens and authentication
• Security Best Practices - Additional security hardening guidance (see links throughout this document)
• Rate Limiting - Configuring rate limits to prevent abuse
• Project Settings - Configuring project-level security settings
• FedRAMP Recommended Secure Configuration - Official FedRAMP guidance