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:

1. Authentication Provider: Handles user registration, login, token management, and related operations.
2. 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

[auth]
provider = "r2r"
access_token_minutes_lifetime = 60
access_token_days_lifetime = 7
require_authentication = true
require_email_verification = false
default_admin_email = "[e-mail]"
default_admin_password = "change_me_immediately"

Cryptography Configuration

[crypto]
provider = "bcrypt"
salt_rounds = 12

Secret Key Management

R2R uses a secret key for JWT signing. Generate a secure key using:

r2r generate-private-key

Set the key as an environment variable:

export R2R_SECRET_KEY=your_generated_key

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:

1. register: User registration
2. login: User authentication
3. refresh_access_token: Token refresh
4. logout: Session termination
5. user: Retrieve user data
6. change_password: Update user password
7. request_password_reset: Initiate password reset
8. confirm_password_reset: Complete password reset
9. verify_email: Email verification
10. get_user_profile: Fetch user profile
11. update_user: Modify user profile
12. delete_user_account: Account deletion

Implementation Guide

User Registration

from r2r import R2RClient, UserCreate

client = R2RClient("http://localhost:7272")

result = client.register([e-mail], secure_password123)
print(f"Registration Result: {result}")

User Authentication

login_result = client.login("[e-mail]", "secure_password123")
client.access_token = login_result['results']['access_token']['token']
client.refresh_token = login_result['results']['refresh_token']['token']

Making Authenticated Requests

user = client.user()
print(f"Authenticated User Info: {user}")

Token Refresh

refresh_result = client.refresh_access_token()
client.access_token = refresh_result['results']['access_token']['token']

Logout

logout_result = client.logout()
print(f"Logout Result: {logout_result}")

Security Best Practices

1. HTTPS: Always use HTTPS in production.
2. Authentication Requirement: Set require_authentication to true in production.
3. Email Verification: Enable require_email_verification for enhanced security.
4. Password Policy: Implement and enforce strong password policies.
5. Rate Limiting: Implement rate limiting on authentication endpoints.
6. Token Management: Implement secure token storage and transmission.
7. 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:

from r2r.base import AuthProvider, AuthConfig
from r2r.abstractions.user import User, UserCreate, Token, TokenData
from typing import Dict

class CustomAuthProvider(AuthProvider):
    def __init__(self, config: AuthConfig):
        super().__init__(config)
        # Initialize any custom attributes or connections here

    def create_access_token(self, data: dict) -> str:
        # Implement custom access token creation logic
        pass

    def create_refresh_token(self, data: dict) -> str:
        # Implement custom refresh token creation logic
        pass

    def decode_token(self, token: str) -> TokenData:
        # Implement custom token decoding logic
        pass

    def user(self, token: str) -> User:
        # Implement custom user info retrieval logic
        pass

    def get_current_active_user(self, current_user: User) -> User:
        # Implement custom active user validation logic
        pass

    def register(self, user: UserCreate) -> Dict[str, str]:
        # Implement custom user registration logic
        pass

    def verify_email(self, verification_code: str) -> Dict[str, str]:
        # Implement custom email verification logic
        pass

    def login(self, email: str, password: str) -> Dict[str, Token]:
        # Implement custom login logic
        pass

    def refresh_access_token(self, user_email: str, refresh_access_token: str) -> Dict[str, str]:
        # Implement custom token refresh logic
        pass

    async def auth_wrapper(self, auth: Optional[HTTPAuthorizationCredentials] = Security(security)) -> User:
        # You can override this method if you need custom authentication wrapper logic
        return await super().auth_wrapper(auth)

    # Add any additional custom methods as needed
    async def custom_auth_method(self, ...):
        # Implement custom authentication logic
        pass

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:

1. Create a new class that extends AuthProvider:

from r2r.base import AuthProvider, AuthConfig
from r2r.abstractions.user import User, UserCreate, Token, TokenData
import some_oauth_library  # Replace with actual OAuth library

class OAuthAuthProvider(AuthProvider):
    def __init__(self, config: AuthConfig):
        super().__init__(config)
        self.oauth_client = some_oauth_library.Client(
            client_id=config.oauth_client_id,
            client_secret=config.oauth_client_secret
        )

    async def login(self, email: str, password: str) -> Dict[str, Token]:
        # Instead of password-based login, initiate OAuth flow
        auth_url = self.oauth_client.get_authorization_url()
        # Return auth_url or handle redirect as appropriate for your app
        pass

    async def oauth_callback(self, code: str) -> Dict[str, Token]:
        # Handle OAuth callback
        token = await self.oauth_client.get_access_token(code)
        user_data = await self.oauth_client.get_user_info(token)

        # Map external user data to R2R's user model
        r2r_user = self._map_oauth_user_to_r2r_user(user_data)

        # Create and return R2R tokens
        access_token = self.create_access_token({"sub": r2r_user.email})
        refresh_token = self.create_refresh_token({"sub": r2r_user.email})
        return {
            "access_token": Token(token=access_token, token_type="access"),
            "refresh_token": Token(token=refresh_token, token_type="refresh"),
        }

    def _map_oauth_user_to_r2r_user(self, oauth_user_data: dict) -> User:
        # Map OAuth user data to R2R User model
        return User(
            email=oauth_user_data["email"],
            # ... map other fields as needed
        )

    # Implement other required methods...

2. Update your R2R configuration to use the new provider:

from r2r import R2R
from r2r.base import AuthConfig
from .custom_auth import OAuthAuthProvider

auth_config = AuthConfig(
    provider="custom_oauth",
    oauth_client_id="your_client_id",
    oauth_client_secret="your_client_secret",
    # ... other config options
)

r2r = R2R(
    auth_provider=OAuthAuthProvider(auth_config),
    # ... other R2R configuration
)

3. Implement necessary routes in your application to handle OAuth flow:

from fastapi import APIRouter, Depends
from r2r import R2R

router = APIRouter()

@router.get("/login")
async def login():
    return await r2r.auth_provider.login(None, None)  # Initiate OAuth flow

@router.get("/oauth_callback")
async def oauth_callback(code: str):
    return await r2r.auth_provider.oauth_callback(code)

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):

1. Implement a custom AuthProvider.
2. Handle token exchange and user profile retrieval.
3. Map external user data to R2R’s user model.

Scaling Authentication

For high-traffic applications:

1. Implement token caching (e.g., Redis).
2. Consider microservices architecture for auth services.
3. Use database replication for read-heavy operations.

Troubleshooting

Common issues and solutions:

1. Token Expiration: Ensure proper token refresh logic.
2. CORS Issues: Configure CORS settings for cross-origin requests.
3. Password Reset Failures: Check email configuration and token expiration settings.

Performance Considerations

1. BCrypt Rounds: Balance security and performance when setting salt_rounds.
2. Database Indexing: Ensure proper indexing on frequently queried user fields.
3. 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.