Okta

​

At a glance

npx @deploybaseline/cli start --service okta

import { createEmulator } from "@deploybaseline/cli";

const okta = await createEmulator({ service: "okta" });
// okta.url is http://localhost:4000

{
  "okta": {
    "users": [
      {
        "login": "[email protected]",
        "email": "[email protected]",
        "first_name": "Test",
        "last_name": "User"
      }
    ],
    "groups": [
      {
        "name": "Everyone",
        "description": "All users",
        "type": "BUILT_IN",
        "okta_id": "00g_everyone"
      }
    ],
    "authorization_servers": [
      {
        "id": "default",
        "name": "default",
        "audiences": ["api://default"]
      }
    ],
    "oauth_clients": [
      {
        "client_id": "okta-test-client",
        "client_secret": "okta-test-secret",
        "name": "Sample OIDC Client",
        "redirect_uris": ["http://localhost:3000/callback"],
        "auth_server_id": "default"
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service okta

import okta from "@okta/okta-sdk-nodejs";

const client = new okta.Client({ orgUrl: process.env.OKTA_EMULATOR_URL, token: "any-token" });

​

Auth

​

Management API conventions

​

OAuth and OIDC

• GET /.well-known/openid-configuration — Get OIDC discovery document: default server
• GET /oauth2/:authServerId/.well-known/openid-configuration — Get server discovery document: per authorization server
• GET /oauth2/v1/keys — Get JSON Web Key Set (JWKS)
• GET /oauth2/v1/authorize — Authorize
• POST /oauth2/v1/token — Exchange token
• GET /oauth2/v1/userinfo — Get user info
• POST /oauth2/v1/revoke — Revoke token
• POST /oauth2/v1/introspect — Introspect token
• GET /oauth2/v1/logout — End session

​

Signing key

​

Client registration

• POST /oauth2/v1/clients — Register client: RFC 7591. client_name (required), redirect_uris, application_type (web, native, browser, service), grant_types (authorization_code, refresh_token, client_credentials), response_types (code), token_endpoint_auth_method (client_secret_basic, client_secret_post, none). Returns 201 with client_id and, for confidential clients, client_secret (client_secret_expires_at: 0)
• GET /oauth2/v1/clients — List clients: q matches the start of the name, limit
• GET /oauth2/v1/clients/:clientId — Get client (without the secret)
• PUT /oauth2/v1/clients/:clientId — Replace client metadata
• DELETE /oauth2/v1/clients/:clientId — Delete client
• POST /oauth2/v1/clients/:clientId/lifecycle/newSecret — Rotate client secret

​

Users

• GET /api/v1/users — List users: search takes any attribute (id, status, created, activated, statusChanged, lastLogin, lastUpdated, passwordChanged, type.id, profile.*) with sortBy and sortOrder; filter takes id, status, lastUpdated, profile.login, profile.email, profile.firstName, and profile.lastName; q matches the start of the first name, last name, or email. Without search or filter, deprovisioned users are left out, as on Okta
• POST /api/v1/users — Create user: profile.login, profile.email, profile.firstName, and profile.lastName are required; login and email must look like email addresses and logins are unique (emails need not be). Other profile attributes (mobilePhone, custom attributes) are kept. Optional credentials.password.value and groupIds. ?activate=false creates a STAGED user, ?nextLogin=changePassword a PASSWORD_EXPIRED one. New users join the built-in Everyone group
• GET /api/v1/users/me — Get current user: the token’s user
• GET /api/v1/users/:userId — Get user: by ID, login, or email
• POST /api/v1/users/:userId — Update user: partial update, only the profile attributes sent change, and null clears one. credentials.password sets a password
• PUT /api/v1/users/:userId — Replace user: profile attributes left out are cleared, and the required ones must be sent
• DELETE /api/v1/users/:userId — Delete user: the first call deactivates, the second deletes
• GET /api/v1/users/:userId/groups — List user groups
• POST /api/v1/users/:userId/lifecycle/activate — Activate user: from STAGED, PROVISIONED, or DEPROVISIONED to ACTIVE; an active user is 403 E0000016. Answers {}, or { activationUrl, activationToken } with sendEmail=false (the URL is not served)
• POST /api/v1/users/:userId/lifecycle/reactivate — Reactivate user: only for PROVISIONED users; answers like activate
• POST /api/v1/users/:userId/lifecycle/deactivate — Deactivate user: to DEPROVISIONED, removing the user’s app assignments
• POST /api/v1/users/:userId/lifecycle/suspend — Suspend user: ACTIVE to SUSPENDED (400 E0000001 otherwise)
• POST /api/v1/users/:userId/lifecycle/unsuspend — Unsuspend user: SUSPENDED to ACTIVE (400 E0000001 otherwise)
• POST /api/v1/users/:userId/lifecycle/unlock — Unlock user: LOCKED_OUT to ACTIVE (403 E0000032 otherwise)
• POST /api/v1/users/:userId/lifecycle/expire_password — Expire password: to PASSWORD_EXPIRED; returns the user
• POST /api/v1/users/:userId/credentials/change_password — Change password: oldPassword and newPassword; a wrong old password is 403 E0000014

​

Groups

• GET /api/v1/groups — List groups: q, search on id, type, created, lastUpdated, lastMembershipUpdated, profile.name, profile.description; filter on id, type, lastUpdated, lastMembershipUpdated
• POST /api/v1/groups — Create group (profile.name required and unique)
• GET /api/v1/groups/:groupId — Get group
• PUT /api/v1/groups/:groupId — Replace group profile
• DELETE /api/v1/groups/:groupId — Delete group: with its memberships and app assignments
• GET /api/v1/groups/:groupId/users — List group members
• PUT /api/v1/groups/:groupId/users/:userId — Add group member (updates lastMembershipUpdated)
• DELETE /api/v1/groups/:groupId/users/:userId — Remove group member
• GET /api/v1/groups/:groupId/apps — List group apps: apps assigned to the group

​

Apps

• GET /api/v1/apps — List apps: q on name or label; filter on status, name, user.id, group.id
• POST /api/v1/apps — Create app (label and signOnMode required; ?activate=false creates it INACTIVE)
• GET /api/v1/apps/:appId — Get app
• PUT /api/v1/apps/:appId — Update app
• DELETE /api/v1/apps/:appId — Delete app: deletes an INACTIVE app
• POST /api/v1/apps/:appId/lifecycle/activate — Activate app (answers {})
• POST /api/v1/apps/:appId/lifecycle/deactivate — Deactivate app (answers {})
• GET /api/v1/apps/:appId/users — List app users: direct (scope: "USER") and through groups (scope: "GROUP")
• POST /api/v1/apps/:appId/users — Assign user to app (id, optional app profile)
• GET /api/v1/apps/:appId/users/:userId — Get app user
• POST /api/v1/apps/:appId/users/:userId — Update app user profile
• DELETE /api/v1/apps/:appId/users/:userId — Unassign user from app
• GET /api/v1/apps/:appId/groups — List app group assignments: by priority
• PUT /api/v1/apps/:appId/groups/:groupId — Assign group to app (priority, profile)
• GET /api/v1/apps/:appId/groups/:groupId — Get app group assignment
• DELETE /api/v1/apps/:appId/groups/:groupId — Remove app group assignment

​

Authorization servers

• GET /api/v1/authorizationServers — List authorization servers (q, limit, after)
• POST /api/v1/authorizationServers — Create authorization server (name, optional id and audiences; 201)
• GET /api/v1/authorizationServers/:authServerId — Get authorization server
• PUT /api/v1/authorizationServers/:authServerId — Update authorization server
• DELETE /api/v1/authorizationServers/:authServerId — Delete authorization server
• POST /api/v1/authorizationServers/:authServerId/lifecycle/activate — Activate authorization server (204)
• POST /api/v1/authorizationServers/:authServerId/lifecycle/deactivate — Deactivate authorization server (204)

​

Access policies

• GET|POST /api/v1/authorizationServers/:authServerId/policies, GET|PUT|DELETE .../policies/:policyId, POST .../policies/:policyId/lifecycle/activate|deactivate
• GET|POST .../policies/:policyId/rules, GET|PUT|DELETE .../rules/:ruleId, POST .../rules/:ruleId/lifecycle/activate|deactivate

​

Seed config

{
  "okta": {
    "users": [
      {
        "login": "[email protected]",
        "email": "[email protected]",
        "first_name": "Test",
        "last_name": "User"
      }
    ],
    "groups": [
      {
        "name": "Everyone",
        "description": "All users",
        "type": "BUILT_IN",
        "okta_id": "00g_everyone"
      }
    ],
    "apps": [
      {
        "name": "My App",
        "label": "My App"
      }
    ],
    "authorization_servers": [
      {
        "id": "default",
        "name": "default",
        "audiences": ["api://default"]
      }
    ],
    "oauth_clients": [
      {
        "client_id": "okta-test-client",
        "client_secret": "okta-test-secret",
        "name": "Sample OIDC Client",
        "redirect_uris": ["http://localhost:3000/callback"],
        "auth_server_id": "default"
      }
    ]
  }
}

​

Conformance