Advanced Features
Nexla's authentication system provides advanced features for complex enterprise scenarios, including multi-tenant organizations, user impersonation, and sophisticated access control mechanisms.
Overview
Advanced authentication features provide powerful capabilities for complex enterprise scenarios. These features enable sophisticated authentication workflows and multi-tenant operations that go beyond basic authentication.
Advanced authentication features enable several key capabilities that support complex enterprise requirements:
- Multi-Tenant Operations: Work across multiple organizations
- Administrative Control: Manage user access and permissions
- Security Auditing: Track authentication and access patterns
- Enterprise Integration: Complex authentication workflows
Organization Context
Organization context allows you to work within specific organizational boundaries and manage multi-tenant scenarios effectively. This section explains how to specify and work with different organization contexts during authentication.
Understanding Organization Context
When authenticating with Nexla, you can specify the organization context for your requests. This is particularly useful for multi-tenant scenarios or when working across multiple organizations within the same platform.
Default Organization
To authenticate within your default organization context, use the asterisk wildcard:
curl -X POST <nexla-api-endpoint>/token \
-H "Authorization: Basic <email>:<password>:*" \
-H "Accept: application/vnd.nexla.api.v1+json" \
-H "Content-Length: 0"
This approach:
- Uses Default: Authenticates within your primary organization
- Simplifies Setup: No need to specify organization IDs
- Maintains Context: All subsequent requests use the same organization
Specific Organization
To authenticate within a specific organization, include the organization ID:
curl -X POST <nexla-api-endpoint>/token \
-H "Authorization: Basic <email>:<password>:<org-id>" \
-H "Accept: application/vnd.nexla.api.v1+json" \
-H "Content-Length: 0"
This approach:
- Targets Specific Org: Authenticates within the specified organization
- Multi-Tenant Support: Enables working across multiple organizations
- Permission Scoping: Limits access to the specified organization's resources
Organization Context in Responses
When authenticating with organization context, the response includes organization information:
{
"access_token": "<access-token>",
"token_type": "Bearer",
"expires_in": 3600,
"user": {
"id": 12345,
"email": "user@example.com",
"full_name": "Example User",
"api_key": "<user-api-key>",
"super_user": false,
"impersonated": false
},
"org_membership": {
"api_key": "<org-api-key>"
},
"org": {
"id": 9876,
"name": "Example Organization",
"description": "Organization Description",
"email_domain": "example.com",
"access_roles": ["member"],
"require_org_admin_to_publish": true,
"require_org_admin_to_subscribe": true
}
}
User Impersonation
User impersonation allows administrators to temporarily assume the identity of other users for troubleshooting and support purposes. This powerful feature requires appropriate administrative privileges and is subject to comprehensive audit logging.
Overview
Organization administrators can impersonate other users within their organization for troubleshooting, support, or administrative purposes. This feature requires appropriate administrative privileges and is subject to audit logging.
Use Cases
Impersonation is useful for several administrative and support scenarios:
- Troubleshooting: Diagnose user-specific issues
- Support: Provide assistance with user accounts
- Auditing: Verify user permissions and access
- Development: Test user-specific functionality
Security Considerations
Several security measures control and monitor impersonation usage:
- Admin Only: Only organization administrators can impersonate users
- Audit Logging: All impersonation actions are logged
- Limited Scope: Impersonation is restricted to organization members
- Temporary: Impersonation tokens have limited duration
Impersonation via Basic Authentication
You can impersonate a user directly during authentication:
curl -X POST <nexla-api-endpoint>/token \
-H "Authorization: Basic <admin-email>:<admin-password>:*" \
-H "Accept: application/vnd.nexla.api.v1+json" \
-H "Content-Type: application/json" \
-d "{ \"email\" : \"<user-email>\", \"org_id\" : \"<org-id>\" }"
Impersonation via Token Refresh
For more secure impersonation, use the token refresh endpoint:
# Step 1: Authenticate as admin
curl -X POST <nexla-api-endpoint>/token \
-H "Authorization: Basic <admin-email>:<admin-password>:*" \
-H "Accept: application/vnd.nexla.api.v1+json" \
-H "Content-Length: 0"
# Step 2: Use admin token to impersonate user
curl -X POST <nexla-api-endpoint>/token/refresh \
-H "Authorization: Bearer <admin-access-token>" \
-H "Accept: application/vnd.nexla.api.v1+json" \
-H "Content-Type: application/json" \
-d "{ \"email\" : \"<user-email>\", \"org_id\" : \"<org-id>\" }"
Impersonation Response
The impersonation response includes detailed information about the impersonated user:
{
"access_token": "<impersonated-access-token>",
"token_type": "Bearer",
"expires_in": 86400,
"user": {
"id": 5002,
"email": "user@example.com",
"full_name": "Example User",
"api_key": null,
"super_user": true,
"impersonated": true,
"impersonator": {
"id": 5003,
"email": "admin@example.com",
"full_name": "Admin User",
"email_verified_at": "2024-01-15T10:30:00.000Z",
"org": 5000
},
"default_org": {
"id": 5000,
"name": "Example Organization"
},
"user_tier": null,
"status": "ACTIVE",
"org_memberships": [
{
"id": 5000,
"name": "Example Organization",
"is_admin?": true,
"org_membership_status": "ACTIVE"
}
]
},
"org_membership": {
"api_key": null,
"status": "ACTIVE"
},
"org": {
"id": 5000,
"name": "Example Organization",
"description": "Example Organization",
"email_domain": "example.com",
"access_roles": ["member"],
"require_org_admin_to_publish": true,
"require_org_admin_to_subscribe": true
}
}
Impersonation Best Practices
Following these best practices ensures secure and responsible use of impersonation:
- Limited Use: Only use impersonation when necessary
- Audit Trail: Document the reason for impersonation
- Time Limitation: Use impersonation tokens for the shortest time possible
- Permission Verification: Ensure you have the right to impersonate the target user
Multi-Tenant Scenarios
Multi-tenant scenarios require the ability to work across multiple organizations seamlessly. This section covers organization switching, cross-organization operations, and best practices for managing complex multi-tenant environments.
Organization Switching
In multi-tenant environments, you may need to switch between organizations:
import requests
class MultiTenantClient:
def __init__(self, base_url, email, password):
self.base_url = base_url
self.email = email
self.password = password
self.current_org = None
self.access_token = None
def authenticate_with_org(self, org_id=None):
"""Authenticate with a specific organization"""
if org_id:
# Authenticate with specific organization
auth_string = f"{self.email}:{self.password}:{org_id}"
else:
# Authenticate with default organization
auth_string = f"{self.email}:{self.password}:*"
encoded_auth = base64.b64encode(auth_string.encode()).decode()
headers = {
'Authorization': f'Basic {encoded_auth}',
'Accept': 'application/vnd.nexla.api.v1+json'
}
response = requests.post(f'{self.base_url}/token', headers=headers)
token_data = response.json()
self.access_token = token_data['access_token']
self.current_org = token_data['org']['id']
return token_data
def switch_organization(self, org_id):
"""Switch to a different organization"""
return self.authenticate_with_org(org_id)
def get_org_resources(self, endpoint):
"""Get resources from the current organization context"""
headers = {
'Authorization': f'Bearer {self.access_token}',
'Accept': 'application/vnd.nexla.api.v1+json'
}
response = requests.get(f'{self.base_url}{endpoint}', headers=headers)
return response.json()
# Usage example
client = MultiTenantClient('https://api.nexla.io', 'user@example.com', 'password')
# Authenticate with default organization
client.authenticate_with_org()
# Switch to specific organization
client.switch_organization(12345)
# Get resources from current organization
teams = client.get_org_resources('/teams')
Cross-Organization Operations
Some operations may require working across multiple organizations:
def compare_orgs_teams(client, org_ids):
"""Compare teams across multiple organizations"""
org_teams = {}
for org_id in org_ids:
# Switch to organization
client.switch_organization(org_id)
# Get teams for this organization
teams = client.get_org_resources('/teams')
org_teams[org_id] = teams
return org_teams
# Compare teams across organizations
org_ids = [12345, 67890, 11111]
comparison = compare_orgs_teams(client, org_ids)
Access Control and Permissions
Access control and permissions determine what resources users can access within different organizations. This section explains how permissions are structured and how to work with organization-specific access controls.
Organization-Level Permissions
Organizations can have specific permission requirements:
{
"org": {
"id": 5000,
"name": "Example Organization",
"require_org_admin_to_publish": true,
"require_org_admin_to_subscribe": true,
"access_roles": ["member", "admin"],
"email_domain": "example.com"
}
}
Permission Inheritance
Users inherit permissions based on their organization membership and role within the system:
- Organization Members: Access to organization resources
- Organization Admins: Additional administrative privileges
- Super Users: Cross-organization access (if applicable)
Resource Access Control
Resources can be accessed based on organization context:
# Access resources in current organization context
curl https://api.nexla.io/teams \
-H "Authorization: Bearer <access-token>" \
-H "Accept: application/vnd.nexla.api.v1+json"
# Access resources with specific organization context
curl "https://api.nexla.io/teams?org_id=12345" \
-H "Authorization: Bearer <access-token>" \
-H "Accept: application/vnd.nexla.api.v1+json"
Security and Auditing
Security and auditing features ensure that all advanced authentication operations are properly tracked and monitored. This section covers audit logging, security monitoring, and how to detect unusual patterns in your authentication system.
Audit Logging
All advanced authentication features are comprehensively logged for security and compliance purposes:
- Impersonation Events: Who impersonated whom and when
- Organization Switches: Organization context changes
- Permission Changes: Access level modifications
- Security Events: Failed authentication attempts
Security Monitoring
Monitor for unusual patterns that may indicate security issues or policy violations:
- Frequent Organization Switches: Potential security issues
- Impersonation Patterns: Unusual impersonation activity
- Permission Escalation: Unexpected permission changes
- Cross-Organization Access: Unusual access patterns
Best Practices
Following best practices ensures that your advanced authentication features are implemented securely and effectively. These guidelines help you maintain proper security, performance, and operational excellence.
Organization Management
Effective organization management requires attention to structure, permissions, and monitoring:
- Clear Structure: Maintain clear organization hierarchies
- Permission Review: Regularly review organization permissions
- Access Monitoring: Monitor cross-organization access
- Documentation: Document organization relationships and permissions
Impersonation Guidelines
Following these guidelines ensures responsible and secure use of impersonation features:
- Justification: Document reasons for impersonation
- Time Limitation: Limit impersonation duration
- Permission Verification: Verify impersonation rights
- Audit Review: Regularly review impersonation logs
Multi-Tenant Security
Multi-tenant security requires careful attention to isolation and access control:
- Isolation: Ensure proper organization isolation
- Access Control: Implement strict access controls
- Monitoring: Monitor cross-organization activities
- Incident Response: Plan for security incidents
Troubleshooting
When issues arise with advanced authentication features, systematic troubleshooting helps identify and resolve problems quickly. This section covers common issues and provides solutions to get your advanced authentication working properly.
Common Issues
Most advanced authentication problems fall into these categories. Understanding the root causes and solutions helps you resolve issues quickly and prevent them from recurring.
Organization Access Denied
- Verify organization membership
- Check organization permissions
- Ensure proper authentication context
Impersonation Fails
- Verify administrative privileges
- Check user organization membership
- Review audit logs for errors
Cross-Organization Errors
- Verify cross-organization permissions
- Check organization relationships
- Review access control policies
Debugging Tips
These debugging tips help you systematically identify and resolve advanced authentication issues:
- Check Organization Context: Verify current organization context
- Review Permissions: Check user and organization permissions
- Monitor Logs: Review authentication and access logs
- Test Isolation: Verify organization isolation
Next Steps
- Security Best Practices: Follow comprehensive security guidelines
- Error Handling: Learn about authentication error handling
- Rate Limiting: Understand rate limiting and throttling
- Connector Authentication: Handle connector-specific authentication
For comprehensive authentication information, return to the Authentication Overview.