imtauthgql Namespace Reference

Authentication GraphQL API Layer Module. More...

Detailed Description

Authentication GraphQL API Layer Module.

The imtauthgql module provides GraphQL API endpoints for authentication and authorization services, enabling remote user management, role administration, permission checking, and session handling through GraphQL queries and mutations.

Overview

This module acts as the GraphQL API layer for imtauth, providing:

• User registration, login, and management
• Role and permission administration
• Group membership operations
• Session and token management
• Personal access token generation
• Permission checking and validation
• Login status subscriptions (real-time)
• User settings synchronization

Architecture

Design Patterns

Adapter Pattern:

• Adapts imtauth domain model to GraphQL schema
• Controllers translate GraphQL requests to business logic
• Response payloads adapt business results to GraphQL format
• Clean separation between API and domain layers

Controller Pattern:

• Collection controllers for bulk operations (list, filter)
• Object controllers for single-object operations (get, update)
• Action controllers for specific operations (login, register)
• Clear responsibility separation

Provider Pattern:

• Info providers supply data for GraphQL resolvers
• Client request managers handle remote operations
• Token-based permission providers for authorization
• Abstraction over data sources

Observer Pattern:

• Login status subscriptions for real-time updates
• Subscriber controllers broadcast authentication events
• WebSocket-based real-time communication

Core Components

The module provides GraphQL controllers and providers:

User Management Controllers:

CRemoteUserControllerComp (imtauth::ISuperuserProvider)
├─ OnRegisterUser() - Create new user account
├─ OnChangePassword() - Update user password
├─ OnCheckEmail() - Validate email availability
├─ OnSendEmailCode() - Email verification code
├─ OnCheckEmailCode() - Verify email code
└─ Remote user operations via GraphQL
    │
    ├─ CUserCollectionControllerComp - List/filter users
    └─ CUserSettingsControllerComp - User preferences

Role Management Controllers:

CRoleRemoteCollectionControllerComp
├─ List roles with filtering
├─ Create and update roles
├─ Assign permissions to roles
└─ Role hierarchy management
    │
    └─ CClientRequestRoleManagerComp - Remote role operations

Permission Management:

CRemotePermissionCheckerComp (iauth::IPermissionChecker)
├─ CheckPermission() - Remote permission validation
├─ HasPermission() - Boolean permission check
└─ Integration with authorization system
    │
    └─ CTokenBasedPermissionsProviderComp (iauth::IRightsProvider)
        ├─ Token-based permission checking
        ├─ JWT or session token validation
        └─ Stateless authorization

Session and Token Management:

CPersonalAccessTokenControllerComp
├─ GenerateToken() - Create personal access token
├─ RevokeToken() - Invalidate token
├─ ListTokens() - Get user's active tokens
└─ Token expiration management
    │
    └─ CLoginStatusSubscriberControllerComp
        ├─ OnLogin subscription - Real-time login events
        ├─ OnLogout subscription - Real-time logout events
        └─ WebSocket-based event broadcasting

Group Management:

CClientRequestGroupManagerComp
├─ CreateGroup() - New group creation
├─ AddUserToGroup() - Group membership
├─ RemoveUserFromGroup() - Remove member
└─ Group hierarchy operations

Data Providers:

CClientRequestUserInfoProviderComp (imtauth::IUserInfoProvider)
├─ GetUserInfo() - Retrieve user details
├─ GetUsersByIds() - Bulk user lookup
└─ User data for GraphQL resolvers
    │
    ├─ CClientRequestRoleInfoProviderComp - Role information
    └─ CClientRequestGroupInfoProviderComp - Group information

User Representation:

CUserRepresentationController
├─ GetUserRepresentation() - User display info
├─ Avatar and profile data
└─ Public user information

User Actions:

CUserActionCollectionControllerComp
├─ LogAction() - Record user action
├─ GetActionHistory() - Query action log
└─ Audit trail for compliance

GraphQL Schema Overview

Queries

User Queries:**

type Query {
    # Get current user
    me: User
    
    # Get user by ID
    user(id: ID!): User
    
    # List users with filtering
    users(
        filter: UserFilter
        limit: Int
        offset: Int
    ): UserConnection
    
    # Check email availability
    checkEmail(email: String!): CheckEmailPayload
}

Role Queries:**

type Query {
    # Get role by ID
    role(id: ID!): Role
    
    # List all roles
    roles: [Role!]!
    
    # Check if user has permission
    hasPermission(permission: String!): Boolean!
}

Token Queries:**

type Query {
    # List user's personal access tokens
    personalAccessTokens: [PersonalAccessToken!]!
}

Mutations

User Mutations:**

type Mutation {
    # Register new user
    registerUser(
        email: String!
        password: String!
        name: String!
    ): RegisterUserPayload!
    
    # Change password
    changePassword(
        oldPassword: String!
        newPassword: String!
    ): ChangePasswordPayload!
    
    # Send email verification code
    sendEmailCode(email: String!): SendEmailCodePayload!
    
    # Verify email code
    checkEmailCode(
        email: String!
        code: String!
    ): CheckEmailCodePayload!
}

Token Mutations:**

type Mutation {
    # Generate personal access token
    generatePersonalAccessToken(
        name: String!
        expiresIn: Int
    ): GenerateTokenPayload!
    
    # Revoke token
    revokePersonalAccessToken(
        tokenId: ID!
    ): RevokeTokenPayload!
}

Subscriptions

Real-time Authentication Events:**

type Subscription {
    # Subscribe to login events
    onLogin: LoginEvent!
    
    # Subscribe to logout events
    onLogout: LogoutEvent!
    
    # Subscribe to user status changes
    onUserStatusChanged(userId: ID!): UserStatusEvent!
}

Usage Examples

Client Setup

Setting up GraphQL Client:**

// Create GraphQL client request manager
auto clientRequestManager = CClientRequestManagerComp::CreateInstance();
 
// Configure server connection
auto serverConnection = CServerConnectionInterfaceParamComp::CreateInstance();
serverConnection->SetHost("api.example.com");
serverConnection->SetHttpPort(443);
serverConnection->SetConnectionFlags(
    imtcom::IServerConnectionInterface::CF_SECURE);
 
clientRequestManager->SetAttribute("ServerConnection", serverConnection.get());
 
// Setup authentication token
QString authToken = GetAuthToken();
clientRequestManager->SetAuthenticationToken(authToken);
 
// Create user controller
auto userController = CRemoteUserControllerComp::CreateInstance();
userController->SetAttribute("ClientRequestManager", 
                            clientRequestManager.get());

User Registration

Register New User:**

// Prepare registration request
sdl::imtauth::Users::CRegisterUserGqlRequest request;
request.SetEmail("newuser@example.com");
request.SetPassword("SecurePassword123!");
request.SetName("John Doe");
 
// Execute mutation
QString errorMessage;
auto payload = userController->OnRegisterUser(
    request,
    gqlRequest,
    errorMessage);
 
if (errorMessage.isEmpty()) {
    qDebug() << "User registered successfully:" << payload.GetUserId();
} else {
    qCritical() << "Registration failed:" << errorMessage;
}

Password Change

Change User Password:**

// Prepare change password request
sdl::imtauth::Users::CChangePasswordGqlRequest request;
request.SetOldPassword("OldPassword123");
request.SetNewPassword("NewSecurePassword456!");
 
// Execute mutation
QString errorMessage;
auto payload = userController->OnChangePassword(
    request,
    gqlRequest,
    errorMessage);
 
if (errorMessage.isEmpty()) {
    qDebug() << "Password changed successfully";
} else {
    qCritical() << "Password change failed:" << errorMessage;
}

Permission Checking

Check User Permission:**

// Create remote permission checker
auto permissionChecker = CRemotePermissionCheckerComp::CreateInstance();
permissionChecker->SetAttribute("ClientRequestManager", 
                               clientRequestManager.get());
 
// Check permission
QString userId = GetCurrentUserId();
QString permission = "users.manage";
 
bool hasPermission = permissionChecker->CheckPermission(
    userId,
    permission);
 
if (hasPermission) {
    // User has permission - show admin UI
    ShowUserManagementInterface();
} else {
    // Permission denied
    ShowAccessDeniedMessage();
}

Personal Access Tokens

Generate Personal Access Token:**

// Create token controller
auto tokenController = CPersonalAccessTokenControllerComp::CreateInstance();
tokenController->SetAttribute("ClientRequestManager", 
                             clientRequestManager.get());
 
// Generate token
sdl::imtauth::Tokens::CGenerateTokenGqlRequest request;
request.SetName("API Access Token");
request.SetExpiresIn(2592000); // 30 days
 
QString errorMessage;
auto payload = tokenController->OnGenerateToken(
    request,
    gqlRequest,
    errorMessage);
 
if (errorMessage.isEmpty()) {
    QString token = payload.GetToken();
    qDebug() << "Generated token:" << token;
    
    // Store token securely for API access
    StoreToken(token);
} else {
    qCritical() << "Token generation failed:" << errorMessage;
}

Login Status Subscription

Subscribe to Login Events:**

// Create subscription controller
auto loginSubscriber = CLoginStatusSubscriberControllerComp::CreateInstance();
loginSubscriber->SetAttribute("ClientRequestManager", 
                             clientRequestManager.get());
 
// Connect to subscription signals
connect(loginSubscriber, &CLoginStatusSubscriberControllerComp::OnLogin,
        this, &MyApp::HandleUserLogin);
connect(loginSubscriber, &CLoginStatusSubscriberControllerComp::OnLogout,
        this, &MyApp::HandleUserLogout);
 
// Start subscription
loginSubscriber->SubscribeToLoginEvents();
 
// Handler implementation
void MyApp::HandleUserLogin(const LoginEvent& event)
{
    qDebug() << "User logged in:" << event.GetUserId()
             << "from" << event.GetIpAddress();
    
    // Update UI to show online status
    UpdateUserStatus(event.GetUserId(), "online");
}

Integration Patterns

Integration with UI

Pattern: Login Form with GraphQL:**

class CLoginFormComp : public ACF_COMPONENT(ILoginForm)
{
    I_REFERENCE(CRemoteUserControllerComp, m_userController)
    
    QPushButton* m_loginButton;
    QLineEdit* m_emailEdit;
    QLineEdit* m_passwordEdit;
    
public:
    void OnLoginButtonClicked()
    {
        QString email = m_emailEdit->text();
        QString password = m_passwordEdit->text();
        
        // Validate input
        if (!ValidateEmail(email)) {
            ShowError("Invalid email address");
            return;
        }
        
        // Prepare GraphQL request
        sdl::imtauth::Users::CLoginGqlRequest request;
        request.SetEmail(email);
        request.SetPassword(password);
        
        // Show loading indicator
        SetUIEnabled(false);
        ShowLoadingSpinner();
        
        // Execute login mutation asynchronously
        QString errorMessage;
        auto future = QtConcurrent::run([this, request]() {
            return m_userController->OnLogin(request, 
                                             imtgql::CGqlRequest(), 
                                             errorMessage);
        });
        
        // Handle result
        auto watcher = new QFutureWatcher<LoginPayload>(this);
        connect(watcher, &QFutureWatcher::finished, [this, watcher]() {
            auto payload = watcher->result();
            
            HideLoadingSpinner();
            SetUIEnabled(true);
            
            if (payload.IsSuccess()) {
                // Store auth token
                QString token = payload.GetAuthToken();
                StoreAuthToken(token);
                
                // Navigate to main app
                emit LoginSuccessful();
            } else {
                ShowError(payload.GetErrorMessage());
            }
            
            watcher->deleteLater();
        });
        
        watcher->setFuture(future);
    }
};

Token-Based Authentication

Pattern: API Client with Token Auth:**

class CApiClientComp : public ACF_COMPONENT(IApiClient)
{
    I_REFERENCE(CClientRequestManagerComp, m_requestManager)
    I_REFERENCE(CTokenBasedPermissionsProviderComp, m_permissionsProvider)
    
    QString m_authToken;
    
public:
    void SetAuthToken(const QString& token)
    {
        m_authToken = token;
        m_requestManager->SetAuthenticationToken(token);
        
        // Load user permissions from token
        LoadPermissionsFromToken(token);
    }
    
    void LoadPermissionsFromToken(const QString& token)
    {
        // Token-based permissions provider validates JWT
        m_permissionsProvider->SetToken(token);
        
        // Permissions are now available for checking
        auto permissions = m_permissionsProvider->GetPermissions();
        qDebug() << "Loaded permissions:" << permissions;
    }
    
    bool CanAccessResource(const QString& resource)
    {
        // Check permission using token-based provider
        return m_permissionsProvider->HasPermission(resource);
    }
};

Best Practices

Security Considerations

• Always use HTTPS/WSS for GraphQL communication
• Implement rate limiting on authentication mutations
• Validate all input data before processing
• Use secure token generation (cryptographically random)
• Implement token expiration and refresh mechanisms
• Log all authentication attempts for security auditing
• Sanitize error messages (don't leak sensitive information)

Error Handling

• Return meaningful error messages in GraphQL responses
• Use consistent error code conventions
• Distinguish between client errors (400s) and server errors (500s)
• Implement retry logic for transient failures
• Log detailed error information server-side
• Handle network timeouts gracefully

Performance Optimization

• Batch user queries to reduce network round-trips
• Implement DataLoader pattern for N+1 query prevention
• Cache frequently accessed user/role data
• Use subscriptions judiciously (resource intensive)
• Implement pagination for large result sets
• Monitor GraphQL query complexity

Integration with Other Modules

With imtauth (Core Authentication):

• GraphQL API layer over authentication domain
• Remote access to authentication services
• Token-based authorization

With imtauthdb (Database Layer):

• Data persistence for GraphQL mutations
• Query resolution from database
• Transaction support

With imtclientgql (GraphQL Client):

• Client request management
• GraphQL query execution
• WebSocket subscription handling

With imtgql (GraphQL Infrastructure):

• GraphQL request/response handling
• Schema definition and validation
• Resolver infrastructure

References

Related Modules:

• imtauth - Core authentication domain
• imtauthdb - Database persistence
• imtclientgql - GraphQL client infrastructure
• imtgql - GraphQL core services

GraphQL Specifications:

• GraphQL Specification: https://spec.graphql.org/
• GraphQL Over WebSocket: https://github.com/apollographql/subscriptions-transport-ws

External Documentation:

• Qt Network Module: https://doc.qt.io/qt-6/qtnetwork-index.html
• JWT (JSON Web Tokens): https://jwt.io/