Flarum APOC OAuth Extension

A Flarum extension that adds APOC OAuth authentication support.

Installation

Use composer to install this extension:

composer require half-nothing/flarum-ext-oauth-apoc

Configuration

After installation:

1. Enable extension in Flarum Admin panel
2. Navigate to Extensions > Log In With APOC
3. Configure the following settings:
   • Client ID: Your APOC OAuth application client ID
   • Client Secret: Your APOC OAuth application client secret
   • Authorization URL: The OAuth2 authorization endpoint URL (e.g., https://api.apocfly.com/api/oauth/authorize)
   • Token URL: The OAuth2 token endpoint URL (e.g., https://api.apocfly.com/api/oauth/token)
   • User Info URL: The API endpoint to retrieve user information (e.g., https://api.apocfly.com/api/users/profiles/self)
4. Save your settings

Important: This extension uses PKCE (Proof Key for Code Exchange) with the S256 method for enhanced security. PKCE is automatically enabled and required for all OAuth authentication flows.

API Response Format

The APOC OAuth provider returns user information in the following format when accessed via OAuth token:

User Info Endpoint Response (OAuth Token Access)

{
  "code": "GET_CURRENT_PROFILE_SUCCESS",
  "message": "获取当前用户信息成功",
  "data": {
    "username": "Half_nothing",
    "email": "[email protected]",
    "cid": 2352,
    "avatar_url": "https://q2.qlogo.cn/headimg_dl?dst_uin=1483073537&spec=100",
    "qq": 1483073537,
    "register_time": "2024-01-01T00:00:00Z"
  }
}

The extension extracts the following fields from the data object:

• email (required): User's email address
• username: User's username (for suggestion)
• cid: User's numeric ID (fallback for username)
• avatar_url: User's avatar URL

Note: When accessing user information via OAuth token, only the following fields are returned: username, email, cid, qq, avatar_url, and register_time.

OAuth Endpoints

1. Authorization Request

• Endpoint: GET /api/oauth/authorize
• Parameters:
  • client_id: Your OAuth client ID
  • redirect_uri: The callback URL
  • response_type: Must be code
  • scope: Currently only profile is supported
  • state (optional): State parameter for CSRF protection
  • code_challenge (required): PKCE challenge using S256 method
  • code_challenge_method (required): Must be S256

Note: PKCE is required by the APOC OAuth server. The extension automatically generates and includes the code_challenge and code_verifier parameters using the S256 method.

2. Access Token Request

• Endpoint: POST /api/oauth/token
• Content-Type: application/json
• Request Body:

{
  "grant_type": "authorization_code",
  "code": "authorization_code_from_previous_step",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "code_verifier": "pkce_code_verifier"
}

Note: The code_verifier parameter is required for PKCE. The extension automatically generates the code_verifier and code_challenge pair and includes them in the OAuth flow.

• Response:

{
  "access_token": "your_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "your_refresh_token",
  "scope": "profile"
}

3. User Info Request

• Endpoint: GET /users/profiles/self
• Headers:
  • Authorization: Bearer {access_token}

PKCE Security

This extension implements PKCE (Proof Key for Code Exchange) using the S256 (SHA-256) method for enhanced security. PKCE provides protection against authorization code interception attacks, which is especially important for public clients.

How PKCE works:

1. The client generates a cryptographically random code_verifier
2. The client creates a code_challenge by hashing the code_verifier with SHA-256 and encoding it in base64url
3. The client includes the code_challenge in the authorization request
4. The client sends the code_verifier in the token exchange request
5. The server verifies that the code_challenge matches the hash of the code_verifier

All PKCE parameters are automatically generated and managed by the extension - no manual configuration is required.

Links

• Flarum
• Friends of Flarum OAuth
• APOC API Documentation

License

This extension is licensed under MIT.