NestJS backend integration: clean handling of OAuth2 enrollment flow with Authentik

[AnthonyGhizzo]

Context

I’m working on an Authentik integration in a NestJS backend for a multi-tenant SaaS project.

I’ve configured two flows:
• A login flow (XXX-dev-authentication-flow) linked to an OAuth2 provider → everything works fine via /application/o/authorize.
• A custom enrollment flow (XXX-dev-enrollment-flow) not linked to any provider → I have to redirect users manually via /if/flow/... and pass a next parameter that points to /authorize.

Example of the enrollment URL I have to build manually:

GET /if/flow/hyspose-dev-enrollment-flow/?next=https://iam.XXX.tech/application/o/authorize/?client_id=...&redirect_uri=...&scope=...&response_type=code&state=enrollment

Problem

👉 Unlike login, nothing is automated on the Authentik side for the enrollment flow:
• I must manually construct the full URL,
• Authentik doesn’t allow linking an enrollment flow directly to a provider,
• This approach feels brittle (e.g., if the client_id or redirect_uri changes),
• And I couldn’t find any official documentation clearly explaining this use case.

My questions
1. Is this the recommended way to handle OAuth2 enrollment flow in a backend/API-oriented context (e.g., NestJS, Next.js)?
2. Is there any plan to allow linking an enrollment flow directly to an OAuth2 provider, just like login flows?
3. Are there any official best practices or documentation for this kind of integration (OAuth2 with a backend-first app)?

⸻

My goal

To ensure a reliable, secure, and scalable integration of Authentik into my SaaS backend — without relying on manually-crafted next URLs.

Thanks in advance for your help 🙏

---

---

@Get("login")
    @UseGuards(OAuthAuthentikAuthGuard)
    @ApiOperation({ summary: "Initiate login flow" })
    @ApiResponse({ status: 302, description: "Redirects to Authentik" })
    login() {
        this.logger.info("Redirecting to Authentik for login");
    }

    @Get("register")
    @ApiOperation({ summary: "Redirect to enrollment flow" })
    @ApiResponse({ status: 302, description: "Redirects to Authentik enrollment flow" })
    register(@Res() res: Response) {
        const enrollmentUrl = this.authentikService.getEnrollmentUrl();

        this.logger.info("Redirecting to Authentik enrollment", { enrollmentUrl });

        return res.redirect(enrollmentUrl);
    }

    @Get("callback")
    @UseGuards(OAuthAuthentikAuthGuard)
    @ApiOperation({ summary: "Handle OAuth2 callback" })
    @ApiResponse({ status: 302, description: "Redirects to frontend with tokens" })
    async callback(@Req() req, @Res() res: Response) {
        try {
            const { accessToken, refreshToken, ...user } = req.user;

            if (!accessToken || !refreshToken) {
                this.logger.error("Missing tokens after Authentik callback", {
                    userId: user?.id,
                    email: user?.email,
                });
                throw new Error("Tokens missing");
            }

            const redirectUrl = new URL(`${this.frontendUrl}/auth/callback`);
            redirectUrl.searchParams.append("accessToken", accessToken);
            redirectUrl.searchParams.append("refreshToken", refreshToken);
            redirectUrl.searchParams.append("user", encodeURIComponent(JSON.stringify(user)));

            if (req.query.state === "enrollment") {
                this.logger.info("User just enrolled via enrollment flow");
                redirectUrl.searchParams.append("from", "enrollment");
            }

            return res.redirect(redirectUrl.toString());
        } catch (error) {
            this.logger.error("Error handling Authentik callback", {
                error: error.message,
                userId: req.user?.id,
            });

            const errorUrl = new URL(`${this.frontendUrl}/login`);
            errorUrl.searchParams.append("error", "authentication_failed");
            return res.redirect(errorUrl.toString());
        }
    }

    public getEnrollmentUrl(): string {
        const enrollmentUrl = new URL(`${this.config.baseUrl}/if/flow/hyspose-dev-enrollment-flow/`);

        const nextUrl = new URL(`${this.config.baseUrl}/application/o/authorize/`);
        nextUrl.searchParams.set("response_type", "code");
        nextUrl.searchParams.set("client_id", this.config.clientId);
        nextUrl.searchParams.set("redirect_uri", this.config.callbackUrl);
        nextUrl.searchParams.set("scope", this.config.scopes.join(" "));
        nextUrl.searchParams.set("state", "enrollment"); // ?

        enrollmentUrl.searchParams.set("next", nextUrl.toString());

        return enrollmentUrl.toString();
    }