docs(auth): add Matrix SSO integration documentation

- Document OIDC endpoints and authentication flow
- Add Synapse configuration examples
- Include troubleshooting guide
- Remove debug logging from OIDC handlers

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Till-JS 2026-01-29 12:57:48 +01:00
parent 1fcd5de8f3
commit b150a16497
3 changed files with 192 additions and 15 deletions

View file

@ -129,10 +129,8 @@ export class OidcController {
* Handle OIDC request by forwarding to Better Auth
*/
private async handleOidcRequest(req: Request, res: Response) {
console.log('[OIDC Controller] Handling request:', req.method, req.originalUrl);
try {
const response = await this.betterAuthService.handleOidcRequest(req);
console.log('[OIDC Controller] Better Auth response status:', response.status);
// Set status code
res.status(response.status || HttpStatus.OK);

View file

@ -1211,7 +1211,6 @@ export class BetterAuthService {
headers: Record<string, string>;
body: unknown;
}> {
console.log('[handleOidcRequest] Received request:', req.method, req.originalUrl);
try {
// Map incoming paths to Better Auth's expected paths
let mappedPath = req.originalUrl;
@ -1229,15 +1228,12 @@ export class BetterAuthService {
mappedPath = mappedPath.replace('/api/oidc/', '/api/auth/oauth2/');
}
console.log('[handleOidcRequest] Mapped path:', mappedPath);
// Convert Express request to Fetch Request
const url = new URL(
mappedPath,
this.configService.get<string>('BASE_URL') ||
`http://localhost:${this.configService.get<number>('PORT') || 3001}`
);
console.log('[handleOidcRequest] Constructed URL:', url.toString());
const headers = new Headers();
for (const [key, value] of Object.entries(req.headers)) {
@ -1255,11 +1251,6 @@ export class BetterAuthService {
// Call Better Auth's handler
const response = await this.auth.handler(fetchRequest);
console.log('[handleOidcRequest] Better Auth status:', response.status);
console.log(
'[handleOidcRequest] Better Auth headers:',
Object.fromEntries(response.headers.entries())
);
// Convert Response to our format
const responseHeaders: Record<string, string> = {};
@ -1267,18 +1258,15 @@ export class BetterAuthService {
responseHeaders[key] = value;
});
// Get body - handle empty responses
// Get body - handle empty responses gracefully
let body: unknown;
const contentType = response.headers.get('content-type');
const textBody = await response.text();
console.log('[handleOidcRequest] Response body length:', textBody.length);
console.log('[handleOidcRequest] Response body preview:', textBody.substring(0, 500));
if (contentType?.includes('application/json') && textBody.length > 0) {
try {
body = JSON.parse(textBody);
} catch {
console.warn('[handleOidcRequest] Failed to parse JSON, using text body');
body = textBody;
}
} else {