Crypto & Auth
Learn how to configure and use the authentication provider in R2R
Introduction
R2R’s CryptoProvider
and AuthProvider
combine to handle user authentication and cryptographic operations in your applications. This guide offers an in-depth look at the system’s architecture, configuration options, and best practices for implementation.
For a practical, step-by-step guide on implementing authentication in R2R, including code examples and common use cases, see our User Auth Cookbook.
When authentication is not required (require_authentication is set to false, which is the default in r2r.toml
), unauthenticated requests will default to using the credentials of the default admin user.
This behavior ensures that operations can proceed smoothly in development or testing environments where authentication may not be enforced, but it should be used with caution in production settings.
Architecture Overview
R2R’s Crypto & Auth system is built on two primary components:
- Authentication Provider: Handles user registration, login, token management, and related operations.
- Cryptography Provider: Manages password hashing, verification, and generation of secure tokens.
These providers work in tandem to ensure secure user management and data protection.
Providers
Authentication Provider
The default R2RAuthProvider
offers a complete authentication solution.
Key features:
- JWT-based access and refresh tokens
- User registration and login
- Email verification (optional)
- Password reset functionality
- Superuser capabilities
Cryptography Provider
The default BCryptProvider
handles cryptographic operations.
Key features:
- Secure password hashing using bcrypt
- Password verification
- Generation of cryptographically secure verification codes
Configuration
Authentication Configuration
Cryptography Configuration
Secret Key Management
R2R uses a secret key for JWT signing. Generate a secure key using:
Set the key as an environment variable:
Never commit your secret key to version control. Use environment variables or secure key management solutions in production.
Auth Service Endpoints
The AuthProvider is responsible for providing functionality to support these core endpoints in R2R:
register
: User registrationlogin
: User authenticationrefresh_access_token
: Token refreshlogout
: Session terminationuser
: Retrieve user datachange_password
: Update user passwordrequest_password_reset
: Initiate password resetconfirm_password_reset
: Complete password resetverify_email
: Email verificationget_user_profile
: Fetch user profileupdate_user
: Modify user profiledelete_user_account
: Account deletion
Implementation Guide
User Registration
User Authentication
Making Authenticated Requests
Token Refresh
Logout
Security Best Practices
- HTTPS: Always use HTTPS in production.
- Authentication Requirement: Set
require_authentication
totrue
in production. - Email Verification: Enable
require_email_verification
for enhanced security. - Password Policy: Implement and enforce strong password policies.
- Rate Limiting: Implement rate limiting on authentication endpoints.
- Token Management: Implement secure token storage and transmission.
- Regular Audits: Conduct regular security audits of your authentication system.
Custom Authentication Flows and External Identity Providers in R2R
Custom Authentication Flows
To implement custom authentication flows in R2R, you can extend the AuthProvider
abstract base class. This allows you to create tailored authentication methods while maintaining compatibility with the R2R ecosystem.
Here’s an example of how to create a custom authentication provider:
Integrating External Identity Providers
To integrate external identity providers (e.g., OAuth, SAML) with R2R, you can create a custom AuthProvider
that interfaces with these external services. Here’s an outline of how you might approach this:
- Create a new class that extends
AuthProvider
:
- Update your R2R configuration to use the new provider:
- Implement necessary routes in your application to handle OAuth flow:
Remember to handle error cases, token storage, and user session management according to your application’s needs and the specifics of the external identity provider you’re integrating with.
This approach allows you to leverage R2R’s authentication abstractions while integrating with external identity providers, giving you flexibility in how you manage user authentication in your application.
Integrating External Identity Providers
To integrate with external identity providers (e.g., OAuth, SAML):
- Implement a custom
AuthProvider
. - Handle token exchange and user profile retrieval.
- Map external user data to R2R’s user model.
Scaling Authentication
For high-traffic applications:
- Implement token caching (e.g., Redis).
- Consider microservices architecture for auth services.
- Use database replication for read-heavy operations.
Troubleshooting
Common issues and solutions:
- Token Expiration: Ensure proper token refresh logic.
- CORS Issues: Configure CORS settings for cross-origin requests.
- Password Reset Failures: Check email configuration and token expiration settings.
Performance Considerations
- BCrypt Rounds: Balance security and performance when setting
salt_rounds
. - Database Indexing: Ensure proper indexing on frequently queried user fields.
- Caching: Implement caching for frequently accessed user data.
Conclusion
R2R’s Crypto & Auth system provides a solid foundation for building secure, scalable applications. By understanding its components, following best practices, and leveraging its flexibility, you can create robust authentication systems tailored to your specific needs.
For further customization and advanced use cases, refer to the R2R API Documentation and configuration guide.