Phase 1: Foundations — Part 2 (Hands-On Setup)

Step 1: Create Your Free Okta Account

Okta's free developer offering used to be called "Developer Edition." That was retired in 2025 — if a tutorial mentions "Developer Edition," it's outdated. The current free offering is the Integrator Free Plan, which is what we use throughout this course, at no cost.

1. Go to developer.okta.com/signup/.
2. You'll be shown a choice of products — select the Okta Platform tile.
3. Click Sign up for Integrator Free Plan.
4. Enter your name, location, and an email address.
5. Check your email for a verification link. Clicking it will also reveal your unique Org domain — something like integrator-551224.okta.com. Write this down; it goes into .env.local shortly.
6. Set your password and set up Okta Verify (Okta's own authenticator app) or another authenticator on your phone — this protects your admin login, separate from the end-user login flow we build for TaskFlow.
7. You'll land on the Okta Admin Console — your control panel for everything: users, groups, applications, security policies. Keep it open.

Step 2: Register Your First Application

1. In the Admin Console, go to Applications → Applications.
2. Click Create App Integration.
3. Sign-in method: choose OIDC — OpenID Connect.
4. Application type: choose Web Application. This matters — Next.js has a real backend (Route Handlers), so it can safely hold a Client Secret, unlike a browser-only Single-Page App.
5. Click Next, then fill in:
   • App integration name: TaskFlow
   • Grant type: Leave Authorization Code checked.
   • Sign-in redirect URIs: http://localhost:3000/api/auth/callback
   • Sign-out redirect URIs: http://localhost:3000
   • Assignments: leave the default (Allow everyone in your organization to access) for now.
6. Click Save.

You'll land on the Application's page. Two values matter here:

• Client ID — visible directly on the page.
• Client Secret — click Show to reveal it. Treat this like a password; never commit it to Git or expose it in browser-side code.

Important — Verify Assignments Explicitly, Don't Just Trust the Default

Even with "Allow everyone" selected, it's worth actually confirming this for whatever account you'll test with. Go to the Assignments tab on this Application's page and check that the specific user you plan to log in with (whether that's your original admin account or a separate test user you create later under Directory → People) genuinely shows up in that list. If a test user was created after this setting was configured, or if "Everyone" isn't behaving as expected, you'll see a "User is not assigned to the client application" error the moment you try to log in — so checking this now saves a debugging detour later. If you ever do hit that exact error, come back here and click Assign → Assign to People, select the user, and save.

Step 3: Configure the Authorization Server's Access Policy — Do Not Skip This

This is the step that's easy to skip and causes a confusing failure later, so it gets its own careful walkthrough. Recall from Lecture 2: every Okta Org has a default Custom Authorization Server, literally named default, which is the one this entire course uses (you'll see /oauth2/default/ in every URL going forward). On Integrator Free Plan orgs, this server exists automatically — but it does not come with a working access policy out of the box, and without one, Okta will reject every single token request with "Policy evaluation failed for this request" — even if login itself (password + MFA) succeeds.

Here's exactly how to set it up correctly:

1. Go to Security → API → Authorization Servers.
2. Click on the server named default.
3. Click the Access Policies tab.
4. If the list is empty, click Add New Access Policy.
   • Name: anything descriptive, e.g. TaskFlow policy
   • Description: anything, e.g. Allows TaskFlow to request tokens
   • Assigned to clients: select All Clients
   • Click Create Policy.
5. Your new policy now exists, but — critically — it still has zero rules, and a policy with no rules approves nothing. You must add at least one rule:
   • Click Add rule.
   • Rule Name: something like Allow TaskFlow login
   • Grant type is: make sure Authorization Code is checked (this is the flow our entire app uses, from Lecture 2 onward). The other pre-checked options (Client Credentials, Device Authorization) can stay checked too — they just won't be used by our app, and having them checked doesn't cause any issue.
   • User is: select Any user assigned the app.
   • Scopes requested: select Any scopes — this is the simplest option and comfortably covers the openid profile email scopes our login route requests, plus offline_access when we add it in Phase 3.
   • Access token lifetime: the default of 1 Hour is fine and matches what Phase 3's silent renewal logic expects.
   • Refresh token lifetime: the default of 90 Days is fine.
   • Click Create rule.
6. Confirm the policy shows Active, and the rule inside it shows Enabled.

To be completely explicit about why this matters: the Access Policy you just built governs whether a token request itself — this specific app, these specific scopes, this specific grant type — is permitted at all. This is a separate concern from the Authentication Policy (which governs how a user proves their identity — password, MFA, etc., covered properly in Phase 4). Both have to independently allow the request for login to succeed. Skipping this step is the single most common reason a beginner gets through Okta's password and MFA screens successfully, only to land on a confusing "Bad Request" page immediately after.

Step 4: Create the Next.js Project

You need Node.js 20.9 or later — check with node -v first.

Run:

    npx create-next-app@latest taskflow --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

What each flag does:

• --typescript — scaffolds with TypeScript and a pre-configured tsconfig.json.
• --tailwind — installs Tailwind CSS. As of Tailwind CSS v4 (what create-next-app installs today), there's no tailwind.config.js for basic theming anymore — customization happens inside globals.css via an @theme block. We'll touch this when styling the login UI.
• --eslint — adds linting with Next.js's recommended rules.
• --app — uses the App Router (the app/ directory), not the older Pages Router. Route Handlers, Middleware, and Server Components — everything this course depends on — are App Router features.
• --src-dir — puts app code inside src/, separate from root config files.
• --import-alias "@/*" — enables import { x } from "@/components/x" instead of long relative paths.

Once scaffolding finishes:

    cd taskflow
    npm run dev

Visit http://localhost:3000 — you should see the default Next.js welcome page, styled with Tailwind.

Step 5: Store Your Okta Credentials Safely

In the root of taskflow, create .env.local:

    OKTA_ORG_URL=https://integrator-5454524.okta.com
    OKTA_CLIENT_ID=your_client_id_here
    OKTA_CLIENT_SECRET=your_client_secret_here

Replace the values with your actual Org domain, Client ID, and Client Secret from Step 2. create-next-app already adds .env*.local to .gitignore — open .gitignore once and confirm that line is genuinely there before going further.

---

A Quick Pre-Flight Checklist Before Moving to Phase 2

Before writing any login code, confirm all three of these are true — each one maps to an error you'd otherwise hit later:

• Application created as Web Application, redirect URIs exactly match http://localhost:3000/api/auth/callback and http://localhost:3000.
• The test user you intend to log in with is genuinely visible under the Application's Assignments tab.
• The default Authorization Server has an Active Access Policy containing at least one Enabled rule that allows the Authorization Code grant type.

If all three are true, you're correctly set up, and the login flow built in Phase 2 will work without the detours we just went through.