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

Theory's done. Now we set up the two things everything else in this course depends on: your Okta account with a registered application, and the actual Next.js project we'll build on for the rest of the course.

Step 1: Create Your Free Okta Account

Okta's free developer offering used to be called "Developer Edition." That was retired in 2025 — if you see a tutorial mention "Developer Edition," it's outdated. The current free offering is called the Integrator Free Plan, and it's what we'll 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 a business/work-style email address (personal Gmail addresses may are usually accepted too, but a work-style email avoids friction).
5. Check your email for a verification link. Clicking it will also tell you your unique Org domain — something like dev-12345678.okta.com. Write this down; you'll paste it into your .env.local file soon.
6. Follow the prompt to set your password and set up Okta Verify (Okta's own authenticator app) on your phone — this protects your admin login, separate from the end-user login flow we're about to build for TaskFlow.
7. Once done, you'll land on the Okta Admin Console — this is your control panel for everything: users, groups, applications, security policies.

Keep this admin console open — we're about to use it.

Step 2: Register Your First Application

Remember from the last post: an "Application" in Okta is a registration representing one specific app that wants to use Okta for login. We're registering our TaskFlow Next.js app now.

1. In the Admin Console, go to Applications → Applications in the left sidebar.
2. Click Create App Integration.
3. You'll be asked for a Sign-in method. Choose OIDC — OpenID Connect. (SAML is a different, older protocol mostly used for enterprise SSO between big companies — not what we're using.)
4. You'll then be asked for an Application type. This is an important choice: select Web Application. This matters because Next.js has a real backend (Route Handlers running on the server), which means it can safely hold a Client Secret — unlike a pure browser-only Single-Page App, which can't. This choice unlocks a more secure version of the flow we covered last time.
5. Click Next. Now you'll fill in the app's settings:
   • App integration name: TaskFlow (or whatever you want to call your project)
   • Grant type: Leave Authorization Code checked — this is the flow we walked through in detail last lecture. Leave the others unchecked for now.
   • Sign-in redirect URIs: This is where Okta is allowed to send the user back to after login, per step 5 of the flow we covered. Enter: http://localhost:3000/api/auth/callback
   • Sign-out redirect URIs: Where the user lands after logging out. Enter: http://localhost:3000
   • Assignments: Leave the default (Allow everyone in your organization to access) — fine for development. In a real production app you'd scope this to specific Groups.
6. Click Save.

You'll land on your new Application's page. Two values here matter enormously and you'll paste them into your project shortly:

• Client ID — visible directly on the page.
• Client Secret — click the eye icon or Show button to reveal it.

Treat the Client Secret like a password. Never commit it to Git, never expose it in browser-side code. We'll store it in an untracked .env.local file in a moment.

One more thing to check while you're here, because it's a change specific to the Integrator Free Plan and will bite you in Phase 2 otherwise: go to Security → API → Authorization Servers, click on the one named default. This is the default Custom Authorization Server we discussed last time — the one we'll actually use, since it supports the custom claims we need later. On Integrator Free Plan orgs, this server is created for you, but without a basic access policy attached by default. Click the Access Policies tab on that page — if it's empty, click Add New Access Policy, give it any name and description, assign it to "All clients," then add a rule inside it (the default rule settings are fine) and make sure it's set to Active. Skipping this step is a common reason people get a confusing "access denied" error the first time they try to log in, so it's worth doing now.

That's Okta fully configured for local development. Everything else in this course happens by tweaking settings here or writing code — no more from-scratch app setup needed.

Step 3: Create the Next.js Project

Now the actual codebase. Requirements first: you need Node.js 20.9 or later installed. Check with node -v in your terminal; if it's older, update Node first.

Run:

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

Here's exactly what each flag does, so you're not just copy-pasting blindly:

• --typescript — scaffolds the project with TypeScript instead of plain JavaScript, including a pre-configured tsconfig.json.
• --tailwind — installs and wires up Tailwind CSS automatically. One important thing to know: as of Tailwind CSS v4 (what create-next-app installs today), configuration works differently than older tutorials show. There's no tailwind.config.js to edit anymore for basic theming — customization happens directly inside globals.css using an @theme block. We'll touch this when we get to styling our login UI in Phase 2, so don't worry about it yet.
• --eslint — adds linting with Next.js's recommended rules, catching mistakes as you code.
• --app — uses the App Router (the app/ directory), not the older Pages Router (pages/ directory). This matters a lot for us — Route Handlers, Middleware, and Server Components (all things we depend on throughout this course) are App Router features. If you ever find a tutorial using pages/api/..., it's using the older pattern and the code won't map directly to what we're doing.
• --src-dir — puts your app code inside a src/ folder, keeping it separate from config files at the project root. Purely organizational, but it's what we'll use for consistency.
• --import-alias "@/*" — lets you write import { something } from "@/components/x" instead of relative paths like ../../../components/x.

Once it finishes scaffolding, move into the project and start the dev server:

cd taskflow
npm run dev

Visit http://localhost:3000 — you should see the default Next.js welcome page, styled with Tailwind. If it loads, your project is working correctly.

Step 4: Store Your Okta Credentials Safely

Before we touch any auth code (that starts next lecture, in Phase 2), let's set up where your Okta credentials will live. In the root of your taskflow project, create a file named .env.local:

OKTA_ORG_URL=https://dev-12345678.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 by default, so this file won't accidentally get committed to version control — but it's worth opening .gitignore once and confirming that line is actually there before you go any further.

---

Where You Stand Now

You have: a working Okta Org with a registered Web Application and a properly policy-enabled authorization server, and a fresh Next.js + TypeScript + Tailwind project with your credentials safely stored. Nothing logs in yet — that's intentional, Phase 1 is entirely about having correct foundations before writing flow logic.

That completes Phase 1 in full.