moai-adk 0.32.8__py3-none-any.whl → 0.41.2__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/adaptive-mfa.md

@@ -0,0 +1,233 @@
+# Adaptive MFA
+
+Adaptive MFA is a flexible, extensible multi-factor authentication policy that assesses potential risk during every login transaction and prompts for additional verification when appropriate.
+
+## Requirements
+
+Plan: Enterprise Plan with Adaptive MFA add-on
+
+## How It Works
+
+Adaptive MFA evaluates multiple risk signals for each login attempt, generates a confidence score, and triggers MFA challenges when the risk exceeds acceptable thresholds.
+
+Key Characteristic: Adaptive MFA ignores any existing MFA sessions and cannot be bypassed by previous authentication.
+
+## Risk Signals
+
+### NewDevice
+
+Detection: Login attempt from a device not used in the past 30 days.
+
+Identification Method:
+- User agent analysis
+- Browser cookies
+- Device fingerprinting
+
+Risk Assessment:
+- Unknown device increases risk
+- Known device reduces risk
+- Compares against historical account access
+
+### ImpossibleTravel
+
+Detection: Geographically suspicious login attempts.
+
+Calculation:
+- Distance between last valid location and current location
+- Time elapsed between logins
+- Hypothetical travel velocity
+
+Threshold:
+- Compares calculated velocity against reasonable travel speed
+- Triggers when physically impossible to travel between locations
+- Accounts for VPN and proxy usage patterns
+
+### UntrustedIP
+
+Detection: Logins from IP addresses with suspicious activity history.
+
+Intelligence Sources:
+- Auth0 traffic intelligence
+- IP reputation databases
+- Historical attack association
+
+Assessment:
+- High-velocity attack association
+- Known malicious IP ranges
+- Tor exit nodes and proxies
+
+## Confidence Scoring
+
+The system combines all three risk factors to generate an overall confidence score:
+
+High Confidence (Low Risk):
+- Known device
+- Normal location
+- Trusted IP
+- MFA not required
+
+Low Confidence (High Risk):
+- New device
+- Impossible travel detected
+- Untrusted IP
+- MFA required
+
+Risk Combination:
+- Multiple risk factors compound
+- Single high-risk factor can trigger MFA
+- Weighted scoring based on signal strength
+
+## Supported Authentication Flows
+
+Fully Supported:
+- OIDC/OAuth2 Authorization Code Flow
+- SAML SP-initiated authentication
+- WS-Federation
+- AD/LDAP authentication
+
+Not Supported:
+- Resource Owner Password Grant (ROPG)
+- Device Authorization Flow
+- Refresh token flows
+
+## Configuration
+
+### Dashboard Settings
+
+1. Navigate to Dashboard > Security > Multi-factor Auth
+2. Set policy to Use Adaptive MFA
+3. Ensure at least one MFA factor is enabled
+
+### Customization with Actions
+
+Create post-login Actions to customize Adaptive MFA behavior:
+
+Custom Risk Logic:
+- Add custom risk signals
+- Integrate external risk services
+- Implement business-specific rules
+
+Conditional Challenges:
+- Challenge based on user attributes
+- Organization-specific policies
+- Transaction-based challenges
+
+Factor Selection:
+- Enforce specific factors for high-risk
+- Allow factor choice for medium-risk
+- Skip MFA for trusted scenarios
+
+## Integration with Custom Risk Assessment
+
+External Risk Services:
+- Pass transaction context to external API
+- Receive risk score
+- Combine with Auth0 Adaptive signals
+
+Custom Signals:
+- Geographic restrictions
+- Time-based policies
+- Device trust levels
+- User behavior analytics
+
+## User Experience
+
+Low-Risk Login:
+- Normal authentication flow
+- No MFA prompt
+- Seamless access
+
+High-Risk Login:
+- MFA challenge presented
+- User completes additional factor
+- Access granted after verification
+
+Transparent to Users:
+- No explanation of risk assessment
+- Consistent MFA experience
+- Standard factor enrollment
+
+## Monitoring
+
+### Adaptive MFA Logs
+
+Events logged include:
+- Risk assessment results
+- Individual signal evaluations
+- MFA challenge decisions
+- Authentication outcomes
+
+### Security Center
+
+View Adaptive MFA metrics:
+- Challenge rates over time
+- Risk signal distribution
+- Geographic patterns
+- Device type analysis
+
+## Best Practices
+
+Factor Configuration:
+- Enable multiple factors for user choice
+- Include recovery codes
+- Configure factors before enabling Adaptive
+
+Gradual Rollout:
+- Enable for subset of users first
+- Monitor challenge rates
+- Adjust based on feedback
+
+Threshold Tuning:
+- Review false positive rate
+- Adjust risk thresholds via Actions
+- Balance security with user friction
+
+User Communication:
+- Explain why MFA may be required
+- Provide factor enrollment guidance
+- Clear support procedures
+
+## Comparison with Always MFA
+
+Always MFA:
+- Every login requires MFA
+- Maximum security
+- Highest user friction
+- Simpler to understand
+
+Adaptive MFA:
+- Risk-based challenges
+- Good security with less friction
+- More sophisticated
+- Requires Enterprise plan
+
+Recommendation:
+- Use Adaptive for consumer applications
+- Consider Always for high-security admin access
+- Combine with step-up for sensitive operations
+
+## Troubleshooting
+
+Frequent False Positives:
+
+New Device Triggers:
+- Users clearing cookies
+- Private browsing mode
+- Multiple browsers
+- Solution: User education on device recognition
+
+Impossible Travel:
+- VPN usage
+- Multiple location employees
+- Solution: Custom Actions to handle known patterns
+
+Untrusted IP:
+- Corporate proxies
+- Cloud-based VPNs
+- Solution: IP AllowList or custom logic
+
+MFA Not Triggering When Expected:
+- Check if flow is supported
+- Verify policy is set to Adaptive
+- Review risk signal evaluations in logs
+- Ensure MFA factors are enabled

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/akamai-integration.md

@@ -0,0 +1,214 @@
+# Akamai Integration
+
+Module: moai-platform-auth0/modules/akamai-integration.md
+Version: 1.0.0
+Last Updated: 2025-12-24
+
+---
+
+## Overview
+
+Auth0 integrates with Akamai to provide supplemental security signals for enhanced attack protection. This integration allows organizations using Akamai's edge security services to leverage bot scores and risk signals within Auth0 Actions for more intelligent authentication decisions.
+
+---
+
+## Integration Purpose
+
+### Enhanced Bot Detection
+
+Combine Auth0's native bot detection with Akamai's comprehensive bot intelligence for more accurate threat identification.
+
+### Risk-Based Authentication
+
+Use Akamai's risk signals to trigger additional authentication steps or block suspicious requests.
+
+### Edge-to-Identity Security
+
+Create a unified security posture from the edge (Akamai) to identity management (Auth0).
+
+---
+
+## Configuration Prerequisites
+
+### Akamai Requirements
+
+Active Akamai Bot Manager or Enterprise Application Access subscription.
+
+Akamai API credentials with appropriate permissions.
+
+Understanding of Akamai's bot detection and risk scoring mechanisms.
+
+### Auth0 Requirements
+
+Auth0 tenant with attack protection features enabled.
+
+Appropriate plan level supporting custom Actions.
+
+Understanding of Auth0 Actions and post-login triggers.
+
+---
+
+## Configuration Steps
+
+### Step 1: Configure Akamai to Send Supplemental Signals
+
+Set up Akamai to forward security signals to Auth0.
+
+Configure the Akamai-Auth0 integration endpoint.
+
+Define which signals should be passed to Auth0.
+
+### Step 2: Create Auth0 Action for Signal Processing
+
+Navigate to Auth0 Dashboard, then Actions, then Library.
+
+Create a new custom Action for the post-login trigger.
+
+Implement logic to read and process Akamai supplemental signals.
+
+### Step 3: Configure Signal Processing Logic
+
+Define thresholds for different risk levels.
+
+Map Akamai bot scores to authentication decisions.
+
+Implement appropriate responses (allow, challenge, block).
+
+### Step 4: Test the Integration
+
+Verify signals are being received correctly.
+
+Test authentication flows with various risk levels.
+
+Validate that appropriate actions are taken based on signals.
+
+### Step 5: Deploy and Monitor
+
+Deploy the Action to production.
+
+Monitor signal processing and authentication outcomes.
+
+Adjust thresholds and logic based on observed behavior.
+
+---
+
+## Using Akamai Supplemental Signals in Actions
+
+### Accessing Signals
+
+Akamai supplemental signals are available in the Auth0 Action context through the event object.
+
+### Common Signal Types
+
+Bot Score: Numerical assessment of whether the request originates from a bot.
+
+Risk Level: Overall risk assessment from Akamai's analysis.
+
+Client Reputation: Historical behavior analysis of the client.
+
+Geographic Indicators: Location-based risk factors.
+
+### Decision Logic Patterns
+
+Low Risk (Allow): Bot score below threshold, no risk indicators.
+
+Medium Risk (Challenge): Elevated bot score or minor risk indicators. Trigger step-up authentication or CAPTCHA.
+
+High Risk (Block): High bot score or significant risk indicators. Deny authentication or require additional verification.
+
+---
+
+## Integration Patterns
+
+### Pattern 1: Bot Score Threshold
+
+Configure a simple threshold-based approach where requests with bot scores above a defined level trigger additional authentication or are blocked.
+
+When to Use: Organizations wanting straightforward bot mitigation without complex logic.
+
+### Pattern 2: Combined Risk Assessment
+
+Combine Akamai signals with Auth0's native risk assessment for comprehensive threat evaluation.
+
+When to Use: Organizations requiring layered security with multiple signal sources.
+
+### Pattern 3: Adaptive Response
+
+Implement dynamic responses that adjust based on the combination of multiple risk factors.
+
+When to Use: Organizations with sophisticated security requirements and the capability to manage complex rule sets.
+
+---
+
+## Best Practices
+
+### Signal Processing
+
+Establish clear thresholds for different risk levels.
+
+Document the logic for signal interpretation.
+
+Implement logging for signal values and decisions.
+
+Regularly review and adjust thresholds based on effectiveness.
+
+### Integration Maintenance
+
+Monitor the integration health regularly.
+
+Keep Akamai and Auth0 configurations synchronized.
+
+Test the integration after any changes to either platform.
+
+Maintain documentation of the integration configuration.
+
+### Security Considerations
+
+Protect API credentials used for the integration.
+
+Implement rate limiting on the integration endpoints.
+
+Monitor for unusual patterns in signal values.
+
+Have fallback procedures if the integration becomes unavailable.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+Signals Not Received: Verify Akamai configuration and network connectivity.
+
+Incorrect Signal Values: Check signal mapping and data transformation.
+
+Action Errors: Review Action logs for specific error messages.
+
+Performance Impact: Monitor latency and optimize signal processing logic.
+
+### Diagnostic Steps
+
+Step 1: Verify Akamai is sending signals correctly.
+
+Step 2: Check Auth0 Action logs for signal receipt.
+
+Step 3: Validate signal processing logic.
+
+Step 4: Test with known good and bad requests.
+
+---
+
+## Related Modules
+
+- attack-protection-overview.md: Overall attack protection strategy
+- bot-detection.md: Auth0 native bot detection
+- suspicious-ip-throttling.md: IP-based threat detection
+- security-center.md: Monitoring and alerting
+
+---
+
+## Resources
+
+Auth0 Documentation: Configure Akamai to Send Supplemental Signals
+Auth0 Documentation: Use Akamai Supplemental Signals in Actions
+Akamai Documentation: Bot Manager and Enterprise Application Access

moai_adk/templates/.claude/skills/moai-platform-auth0/modules/application-credentials.md

@@ -0,0 +1,280 @@
+# Application Credentials
+
+Auth0 supports multiple authentication methods for confidential applications to securely authenticate with authorization servers when requesting tokens.
+
+## Credential Types
+
+### Client Secret (Default)
+
+Symmetric key authentication.
+
+How It Works:
+- Auth0 generates high-entropy secret
+- Shared between application and Auth0
+- Included in token requests
+
+Transmission:
+- Secret sent over network
+- Included in request body or Basic auth header
+- HTTPS required for security
+
+Risks:
+- Man-in-the-middle vulnerability
+- Secret compromise = complete breach
+- Must protect on both ends
+
+Best For:
+- Simple implementations
+- Trusted environments
+- Initial development
+
+### Private Key JWT
+
+Asymmetric key authentication.
+
+How It Works:
+- Application generates key pair
+- Public key registered with Auth0
+- Private key creates signed assertions
+- Auth0 verifies with public key
+
+Transmission:
+- Private key never transmitted
+- Only signed JWT sent
+- Assertion has short expiry
+
+Benefits:
+- Private key stays private
+- Limited replay window
+- No shared secret
+
+Requirements: Enterprise plan
+
+### mTLS for OAuth
+
+Certificate-based mutual TLS authentication.
+
+How It Works:
+- Application obtains X.509 certificate
+- Certificate registered with Auth0
+- mTLS connection established
+- Certificate validates client identity
+
+Transmission:
+- Certificate private key never transmitted
+- TLS handshake authenticates client
+- Transport-layer security
+
+Benefits:
+- Strongest authentication
+- No application-layer credentials
+- Certificate-based identity
+
+Requirements: Enterprise plan with HRI add-on
+
+## Credential Comparison
+
+### Security Ranking
+
+Most Secure to Least:
+1. mTLS for OAuth (certificate-based)
+2. Private Key JWT (asymmetric)
+3. Client Secret (symmetric)
+
+### Complexity
+
+Simplest to Most Complex:
+1. Client Secret (minimal setup)
+2. Private Key JWT (key management)
+3. mTLS for OAuth (PKI infrastructure)
+
+### Recommendations
+
+Upgrade Path:
+1. Start with Client Secret for development
+2. Move to Private Key JWT for production
+3. Use mTLS for highest security needs
+
+## Private Key JWT Details
+
+### Key Generation
+
+Supported Algorithms:
+- RS256, RS384, RS512 (RSA)
+- PS256, PS384, PS512 (RSA-PSS)
+
+Key Requirements:
+- Minimum key size per algorithm
+- Secure key generation
+- Protected storage
+
+### Client Assertion
+
+JWT Structure:
+- iss: Client ID
+- sub: Client ID
+- aud: Token endpoint URL
+- iat: Issue time
+- exp: Expiration time
+- jti: Unique identifier
+
+Assertion Lifetime:
+- Short expiry recommended
+- Limits replay window
+- Typically seconds to minutes
+
+### Token Request
+
+Parameters:
+- client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
+- client_assertion: Signed JWT
+
+### Key Registration
+
+Dashboard Steps:
+1. Navigate to Applications
+2. Select application
+3. Go to Credentials tab
+4. Upload public key
+5. Save configuration
+
+API Registration:
+- Use Management API
+- Provide JWKS or JWK
+- Associate with application
+
+### Key Rotation
+
+Zero-Downtime:
+- Register up to two keys
+- Deploy new key to application
+- Remove old key after transition
+
+Process:
+1. Generate new key pair
+2. Register new public key
+3. Update application
+4. Verify new key works
+5. Remove old public key
+
+## mTLS for OAuth Details
+
+### Certificate Requirements
+
+Valid X.509 Certificate:
+- RSA or ECDSA key
+- Appropriate validity period
+- Proper extensions
+
+Certificate Chain:
+- Complete chain available
+- Trusted CA or registered self-signed
+- Proper intermediate certificates
+
+### Certificate Registration
+
+Dashboard Steps:
+1. Navigate to Applications
+2. Select application
+3. Go to Credentials tab
+4. Upload certificate
+5. Save configuration
+
+Multiple Certificates:
+- Up to two certificates
+- Enables rotation
+- Remove old before adding third
+
+### Token Request
+
+Connection:
+- Establish mTLS to token endpoint
+- Present registered certificate
+- Complete mutual authentication
+
+## JWT-Secured Authorization Requests (JAR)
+
+### Overview
+
+Protect authorization request parameters:
+- Sign request as JWT
+- Optionally encrypt
+- Ensure integrity and confidentiality
+
+### Benefits
+
+Integrity:
+- Detect parameter tampering
+- Verify request source
+- Prevent manipulation
+
+Confidentiality (with encryption):
+- Hide sensitive parameters
+- Protect from intermediaries
+- Enhanced privacy
+
+### Implementation
+
+Create Request JWT:
+- Include all authorization parameters
+- Sign with registered key
+- Send as request parameter
+
+## Best Practices
+
+### Secret Management
+
+For Client Secrets:
+- Secure storage
+- Environment variables
+- Secret management service
+- Regular rotation
+
+For Private Keys:
+- HSM when possible
+- Encrypted storage
+- Access controls
+- Regular rotation
+
+For Certificates:
+- Proper CA hierarchy
+- Lifecycle management
+- Rotation procedures
+- Revocation capability
+
+### Rotation
+
+Regular Rotation:
+- Schedule periodic rotation
+- Automate when possible
+- Test rotation procedures
+
+Emergency Rotation:
+- Immediate capability
+- Documented procedures
+- Tested regularly
+
+### Monitoring
+
+Track:
+- Credential usage
+- Failed authentications
+- Rotation events
+- Expiration dates
+
+Alert On:
+- Failed authentications
+- Approaching expiration
+- Unusual patterns
+
+### Security
+
+Principle of Least Privilege:
+- Minimum required scopes
+- Appropriate credential type
+- Regular review
+
+Audit:
+- Credential access
+- Configuration changes
+- Token requests