PeoplePicker

Create an MVP web app called "PeoplePicker" for searching Okta users by name.

Overview

PeoplePicker is a lightweight Next.js application that lets anyone search your organization’s Okta directory without signing in. The app debounces user input, proxies the request to Okta via a secure API route, and renders matching people with their name, email, and profile picture when available.

Features

• 🔍 Real-time search: Debounced client-side search requests the Okta Users API as you type.
• 🛡️ Secure proxy: A Next.js route keeps Okta credentials on the server and exposes a minimal response.
• 👤 Clean results: Shows each person’s name, email, and avatar or initials fallback.
• 🚀 Ready for Azure: Built on Node.js 20-ready Next.js 14 with Tailwind CSS for quick deployment to Azure App Service.

Getting Started

Prerequisites

• Node.js 20 (Azure App Service default, also used in local development)
• npm 10+
• An Okta tenant with API token access to the Users API

Installation

npm install

Environment variables

Create a .env.local file (or provide variables through your hosting provider) using the .env.example template:

cp .env.example .env.local

Variable	Description
OKTA_DOMAIN	Your Okta domain without protocol (e.g. dev-123456.okta.com).
OKTA_API_TOKEN	Service token with permissions to call the Okta Users API.
OKTA_USER_SEARCH_LIMIT	(Optional) Overrides the default of 10 results per request.

Local development

npm run dev

Visit http://localhost:3000 and begin typing a name to search.

Production build

npm run build
npm start

Deploying to Azure App Service

1. Configure the app with Node 20 and install dependencies using npm install during deployment.
2. Set the required environment variables (OKTA_DOMAIN, OKTA_API_TOKEN, and optionally OKTA_USER_SEARCH_LIMIT).
3. Build and start the app with npm run build followed by npm start.

API Reference

GET /api/okta/search?name=<query>

• Query Parameters
  • name (string, required): Name fragment to search.
• Response

{
  "users": [
    {
      "id": "00u1abcd123",
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "avatar": "https://..."
    }
  ]
}

Errors are returned with an error field and appropriate HTTP status code when configuration is missing or Okta is unreachable.

Next steps

• Add authentication and authorization controls once requirements evolve.
• Implement pagination or infinite scroll for larger directories.
• Extend filters beyond simple name matches when more metadata is available.
• ..