# `MishkaCmsCoreWeb.AuthController`
[🔗](https://github.com/mishka-group/mishka_cms_core/blob/v0.0.1/lib/mishka_cms_core_web/auth_controller.ex#L5)

Authentication controller for MishkaCms user authentication workflows.

Handles authentication success/failure scenarios and session management using
the AshAuthentication framework. Provides a seamless user experience with
intelligent redirects, contextual messaging, and secure session handling.

## Key Features

- **Multi-Activity Support**: Handles various authentication activities (sign-in, password reset, email confirmation)
- **Smart Redirects**: Returns users to their intended destination after authentication
- **Contextual Messaging**: Activity-specific success and error messages
- **Session Management**: Secure session storage and cleanup
- **Error Handling**: Comprehensive error categorization with user-friendly messages
- **Security-First**: Proper session invalidation and secure sign-out

## Authentication Activities

The controller handles multiple authentication scenarios:
- **Sign In**: Standard email/password authentication
- **Email Confirmation**: New user email verification
- **Password Reset**: Secure password reset workflow
- **Sign Out**: Session termination and cleanup

## Success Flow

Authentication success triggers:
1. **Return Path Resolution**: Verifies the signed `return_to` token, or defaults to home
2. **Session Management**: Stores user authentication state
3. **User Assignment**: Sets current user in connection assigns
4. **Activity Messaging**: Displays appropriate success message
5. **Redirect**: Returns user to intended destination

## Failure Flow

Authentication failures provide:
1. **Error Categorization**: Specific error type identification
2. **User-Friendly Messages**: Clear, actionable error descriptions
3. **Secure Redirects**: Returns to sign-in page for retry
4. **Context Preservation**: Maintains user workflow state

## Session Security

- **Secure Storage**: Uses AshAuthentication session management
- **Session Cleanup**: Proper session termination on sign-out
- **Live Sockets Named**: The session carries a `live_socket_id`, so every LiveView the browser
  goes on to open can be cut the moment this account's authentication or authorization changes —
  see `MishkaCmsCore.Accounts.LiveSockets`
- **Return Path Never Stored**: The destination travels as a `MishkaCmsCoreWeb.ReturnTo` token, so
  the session holds nothing to clean up and a sign-out always goes home
- **Second Factor**: An account with an authenticator gets a session only from the password
  sign-in, which asked for its code (`MishkaCmsCore.Accounts.SecondFactor`); any other way in
  ends on the sign-in page with its token revoked
- **XSS Prevention**: Secure session handling prevents cross-site attacks

## Error Message Examples

### Email Confirmation Required
```
"You have already signed in another way, but have not confirmed your account.
You can confirm your account using the link we sent to you, or by resetting your password."
```

### Invalid Credentials
```
"Incorrect email or password"
```

## Success Message Examples

- **Email Confirmation**: "Your email address has now been confirmed"
- **Password Reset**: "Your password has successfully been reset"
- **Sign In**: "You are now signed in"
- **Sign Out**: "You are now signed out"

## Security Considerations

- **Session Security**: Proper session invalidation prevents session hijacking
- **CSRF Protection**: Integration with Phoenix CSRF protection
- **Secure Redirects**: Only a path this application signed is redirected to, so a `return_to`
  anyone writes into the URL cannot open-redirect
- **Error Information**: Limited error details prevent user enumeration
- **Rate Limiting**: Signing in and the reset and sign-in link requests are limited per address and
  per account; a refused one is answered `429` with a page saying how long to wait — see
  `MishkaCmsCore.Accounts.AuthRateLimit`

## Integration with AshAuthentication

Leverages AshAuthentication.Phoenix.Controller for:
- **Automatic Route Generation**: Standard authentication routes
- **Session Management**: Secure session storage and retrieval
- **Error Handling**: Comprehensive error categorization
- **Activity Tracking**: Different authentication activity types

## User Experience Features

- **Seamless Flow**: Users return to intended destination after authentication
- **Clear Messaging**: Activity-specific success and error messages
- **Progressive Enhancement**: Works with and without JavaScript
- **Accessibility**: Screen reader friendly messaging

## Production Considerations

- **Monitoring**: Track authentication success/failure rates
- **Rate Limiting**: Implement authentication attempt rate limiting
- **Audit Logging**: Log authentication events for security analysis
- **Session Management**: Monitor session lifecycle and cleanup
- **Error Tracking**: Monitor authentication errors for security threats
- **Performance**: Optimize redirect performance for user experience

## Customization Points

- **Return Path Logic**: Customize redirect destination logic
- **Message Customization**: Modify success/error messages
- **Session Storage**: Customize session key names and storage
- **Error Handling**: Add additional error categorization
- **Analytics Integration**: Add authentication event tracking

## Multi-tenant Considerations

- **Site Context**: Authentication respects current site context
- **User Scoping**: Users may have different permissions per site
- **Session Isolation**: Sessions respect tenant boundaries
- **Redirect Handling**: Return paths respect site routing

# `sign_out`

---

*Consult [api-reference.md](api-reference.md) for complete listing*