Introduction

#

If you work with Okta Privileged Access (OPA), you know that session recording is one of the most powerful features of the platform. It gives you a full audit trail of every SSH terminal session and every RDP desktop connection performed by your privileged users.

The problem? Out of the box, there is no simple way to browse and replay those recordings without digging into raw files stored in the Okta Privileged Access Access Gateway. This is one of the most common pain points I hear from Okta PAM customers in the field.

Today I’m releasing Opaflix: an open-source web application that lets you browse and replay converted OPA session recordings stored in AWS S3, protected by Okta OIDC authentication. Like Netflix 🍿 but for your PAM recordings playback.

GitHub Repository

#

Sample Video

#

Why Opaflix?

#

Reviewing session recordings is a critical workflow for security teams, auditors, and PAM administrators. Whether you’re investigating a security incident, validating compliance, or simply verifying that a change was performed correctly, you need a fast and intuitive way to find the right session and play it back.

The inspiration for Opaflix came from opa-utils, a similar project by my former colleague Daniel Harris. Since that project is no longer maintained, I decided to build a new one from scratch with a more modern tech stack.

Key Features

#

Here is what Opaflix offers out of the box:

Dashboard and Sessions List

#

The dashboard provides an overview of session activity, including total sessions, sessions by team, and sessions by project. This gives you quick insights into usage patterns and helps identify anomalies.

Dashboard with Statistics	Sessions List

SSH & RDP Session Playback

#

SSH terminal sessions are replayed using the Asciinema player, with support for play/pause, speed control, and seeking. RDP desktop sessions are played back through an HTML5 video player. Both support direct download from S3 for offline access.

SSH Playback	RDP Playback

Single-Tenant and Multi-Tenant Modes

#

Opaflix supports two deployment modes.

• In single-tenant mode (default), everything is configured via environment variables with no database required: you can be up and running in under five minutes.
• In multi-tenant mode, a PostgreSQL database backs an isolated configuration per team, with a web UI for managing settings. This makes it suitable for centralized deployments serving multiple OPA teams.

A configuration UI help managing settings in multi-tenant mode.

Advanced Search and Filtering:

#

Sessions can be searched and filtered by server, username, project, team, and date range. Filter dropdowns are populated with real-time data from the OPA API. Sortable and resizable columns make it easy to navigate large session archives.

Simple Search	Advanced Search	Sorting

Infrastructure Graph

#

A visual topology view shows the relationships between Gateways, Projects, and Servers, populated with live data from the OPA API. This helps you understand your PAM infrastructure at a glance and quickly navigate to relevant sessions.

Graph Page	Graph Details

Okta OIDC Authentication

#

All routes are protected by Okta OIDC. Session cookies are httpOnly, secure, and sameSite. Rate limiting, input validation, and security headers via Helmet.js are included by default.

IAM Roles Anywhere Support

#

For deployments outside AWS (e.g., Vercel, on-premises), Opaflix supports certificate-based authentication via IAM Roles Anywhere, so you don’t need to rely on static access keys. Static Access Keys are supported as well for simplicity, but using IAM Roles Anywhere is the recommended approach for AWS security best practice.

How it works

#

High-Level Data Flow

#

The following is an high-level overview of the Opaflix data flow:

---
config:
  layout: dagre
---
flowchart LR
 subgraph User["1️⃣   Privileged Access"]
        Admin["👤   Administrator"]
  end
 subgraph Gateway["2️⃣   OPA Gateway"]
        Broker["SFT Broker"]
        Session["Session Recording
/var/log/sft/sessions/*.asa"]
  end
 subgraph Target["3️⃣   Target"]
        Server["🖥️   Server"]
  end
 subgraph SyncService["4️⃣   opaflix-sync"]
        Convert["Session Conversion
.asa → .cast / .mkv"]
  end
 subgraph Storage["5️⃣   AWS S3"]
        S3["Converted Sessions
.cast / .mkv"]
  end
 subgraph Playback["6️⃣   Opaflix"]
        Web["Web Application"]
        Browser["🌐   Browser"]
  end
    Broker --> Session & Server
    Session --> Convert
    Convert -- Upload --> S3
    S3 --> Web
    Web --> Browser
    Admin -.-> Server
    Admin --> Broker

    S3@{ shape: disk}
    Session@{ shape: disk}
    style Admin fill:#ffffff
    style Broker fill:#ffffff
    style Session fill:#ffffff
    style Server fill:#ffffff
    style Convert fill:#ffffff
    style S3 fill:#ffffff
    style Web fill:#ffffff
    style Browser fill:#ffffff
    style User fill:#BBDEFB
    style Gateway fill:#C8E6C9
    style Storage fill:#FFF9C4
    style Playback fill:#FFCDD2
    style SyncService fill:#E1BEE7

Application Architecture

#

The application is built with Node.js, Express, and Handlebars for the backend. Session recordings are served directly from S3 via presigned URLs: no server bandwidth is consumed for playback. Presigned URLs are short-lived (1 hour by default) for security, ensuring recordings cannot be accessed via stale links.

The following diagram illustrates the architecture of the Opaflix application, including its interactions with Okta for authentication, AWS S3 for storage, and the OPA API for real-time data:

---
config:
  layout: dagre
---
flowchart LR
 subgraph Client["Client"]
        Browser["🌐 Browser"]
  end
 subgraph Opaflix["Opaflix"]
        App["Express.js App"]
        Auth["Okta OIDC"]
  end
 subgraph AWS["AWS"]
        S3[("AWS S3")]
  end
  subgraph OktaCloud["Okta Cloud"]
        OPA["OPA API"]
        Okta["Okta IdP"]
  end
  subgraph Database["Database"]
        PG[("PostgreSQL")]
  end
    Browser --> App
    App --> Auth & S3 & OPA
    App -.-> PG
    Auth --> Okta

Quick Start

#

Get Opaflix running in single-tenant mode in a few steps:

1. Create an Okta Web App (OIDC) and configure the redirect URIs

2. Create an AWS S3 bucket and upload converted session recordings

3. Clone the Opaflix repository and set up the environment variables

   # Clone the repository
   git clone https://github.com/fabiograsso/okta-opaflix.git
   cd okta-opaflix
   
   # Create and edit the environment file
   cp .env.example .env

4. Fill in the required values in .env. The minimum required configuration in .env for single-tenant mode:

   # Application
   BASE_URI=http://localhost:3000
   SESSION_SECRET=your-secure-secret-minimum-32-characters-long
   
   # Okta Authentication
   OKTA_ISSUER=https://your-tenant.okta.com
   OKTA_CLIENT_ID=your-client-id
   OKTA_CLIENT_SECRET=your-client-secret
   
   # AWS S3
   AWS_REGION=us-east-1
   AWS_S3_BUCKET=your-bucket
   
   # Option 1: Static Access Keys
   AWS_ACCESS_KEY_ID=your-access-key
   AWS_SECRET_ACCESS_KEY=your-secret-key
   
   # Option 2: IAM Roles Anywhere
   # AWS_ROLES_ANYWHERE_TRUST_ANCHOR_ARN=arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/abc123
   # AWS_ROLES_ANYWHERE_PROFILE_ARN=arn:aws:rolesanywhere:us-east-1:123456789012:profile/def456
   # AWS_ROLES_ANYWHERE_ROLE_ARN=arn:aws:iam::123456789012:role/OpaflixS3Access
   # AWS_ROLES_ANYWHERE_CERTIFICATE="-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
   # AWS_ROLES_ANYWHERE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"

5. Then start the application:

   # Option 1: Local Node.js
   npm install && npm start
   
   # Option 2: Docker Compose
   make start

   Open http://localhost:3000 and authenticate with Okta.

Prerequisites and Setup

#

Before deploying Opaflix, you need:

Okta OIDC Setup

#

1. Create a new Web Application in your Okta Admin Console
2. Set the Sign-in redirect URI to http://localhost:3000/authorization-code/callback (or your custom domain)
3. Set the Sign-out redirect URI to http://localhost:3000/login
4. Copy the Client ID and Client Secret to your .env file

OPA Gateway Configuration

#

For Opaflix to correctly parse session metadata, recordings must follow a specific filename format. Edit /etc/sft/sft-gatewayd.yaml on your OPA Gateway:

LogFileNameFormats:
  SSHRecording: "{{.Protocol}}~{{.StartTime}}~{{.TeamName}}~{{.ProjectName}}~{{.ServerName}}~{{.Username}}~"
  RDPRecording: "{{.Protocol}}~{{.StartTime}}~{{.TeamName}}~{{.ProjectName}}~{{.ServerName}}~{{.Username}}~"

Restart the gateway with sudo systemctl restart sft-gatewayd.

This produces filenames like:

ssh~2024-01-15T10:30:00Z~acme-team~production~web-server-01~admin~.asa

Session Conversion

#

OPA session recordings (.asa files) must be converted before uploading to S3:

# SSH: .asa → .cast (Asciinema format)
sft session-logs export --insecure --format asciinema /path/source.asa --output /path/output.cast

# RDP: .asa → .mkv
sft session-logs export --insecure --format mkv --output /path/ /path/source.asa

Two conversion utilities are provided in scripts/convert-sessions/:

Bash Script (convert-sessions.sh): A straightforward batch converter. Point it at a directory of .asa files, and it will convert them to the appropriate format (.cast for SSH, .mkv for RDP). Ideal for one-off conversions and tests. You have then to manually upload the converted files to S3 (e.g. using aws s3 cp or manually uploading the files in the AWS Management Console).

Python Service (opaflix-sync.py): A more sophisticated option that runs as a background service. It uses file system monitoring (via watchdog) to detect new .asa files as they arrive, converts them automatically, and uploads them to the S3 bucket. It includes duplicate detection, configurable cleanup of old source files, and a systemd service file for production deployments. This is the recommended approach for production environments where you want near real-time availability of session recordings in Opaflix.

You can read more details in scripts/convert-sessions/README.md on GitHub.

AWS S3 Bucket Setup

#

Opaflix requires an S3 bucket to store converted session recordings. The bucket needs appropriate IAM policies to allow Opaflix to generate presigned URLs for playback.

You can find the full S3 setup documentation on the GitHub repository:

• docs/AWS.md for general AWS configuration
• scripts/aws/README.md for AWS CLI and CloudFormation commands

A CloudFormation template is provided to automate the entire AWS setup, including:

• S3 bucket with proper CORS configuration for browser-based playback
• IAM policy with least-privilege permissions for Opaflix
• Optional IAM Roles Anywhere trust anchor and profile (for deployments outside AWS)

Known Limitations

#

Opaflix is a v1 release. There are a few intentional constraints worth knowing:

• No permission management. All authenticated users can access all recordings. The primary audience is PAM Admins and Auditors, adding granular permission management is on the long-term roadmap, but keeping things simple was the priority for this release.
• S3 only. Other storage backends may be evaluated in the future based on feedback.
• Vibe Coded. As mentioned above, this project was built with heavy AI assistance. It’s been tested, but if you find a bug, please open an issue.

What’s Next

#

The project is live and open for contributions. The immediate roadmap includes:

• Improve the initial tenant creation process in multi-tenant mode with a dedicated UI
• Evaluate granular permission management based on community feedback
• Evaluate additional storage backends beyond S3

Documentation Links

#

The complete documentation is available in the GitHub Repository, here are some quick links to get you started:

• README.md - Main Documentation
• docs/AWS.md - General AWS Configuration
• scripts/aws/README.md - AWS CLI and CloudFormation Commands
• scripts/convert-sessions/README.md - Session Conversion Scripts

Conclusion

#

Opaflix fills a practical gap for anyone running Okta Privileged Access at scale. If your security team needs to review session recordings regularly, having a searchable, authenticated, browser-based player dramatically reduces friction, whether you’re responding to an incident or running a quarterly compliance review.

The project is available now at github.com/fabiograsso/okta-opaflix under the Apache 2.0 license.

Questions or feedback? If you try it, feel free to open issues, submit PRs, or leave a comment below. Feedback from the field is always welcome.

Special Thanks

#

• Pascale Kik - For her invaluable feedback and testing efforts during the early stages of development. Her insights helped shape the user experience and identify critical issues.
• Okta Community - For their support and engagement, which inspired the creation of Opaflix as a tool to benefit PAM administrators and auditors.

Introduction

#

You’ve deployed the Okta Generic Database Connector and configured provisioning workflows, but have you ever wondered what happens behind the scenes? How does the SCIM Server translate those high-level provisioning requests from Okta into actual database operations? What REST endpoints does it expose, and how does the authentication actually work?

This article provides a technical deep dive into the Okta On-Prem SCIM Server—the critical component that sits between the Okta Provisioning Agent and your database, translating SCIM protocol calls into JDBC operations. Through reverse engineering and analysis of the SCIM Server JAR file, we’ll explore its internal architecture, REST controllers, authentication mechanisms, and the mysterious X-OKTA-ONPREM-DATA header that makes multi-tenancy possible.

Why This Matters:

Understanding the SCIM Server’s internals helps you:

• Troubleshoot issues more effectively by knowing exactly where requests flow
• Optimize performance by understanding connection pooling and configuration
• Debug provisioning failures by interpreting log patterns and error messages
• Appreciate the architecture of Okta’s on-premises provisioning solution

Overview

#

The Okta On-Prem SCIM Server is a Spring Boot 3.5.0 application that implements the SCIM 2.0 protocol for provisioning users, groups, and entitlements to on-premises databases. It acts as a bridge between Okta’s cloud, the On-Premise Provisioning (OPP) Agent, and your local database infrastructure.

Key Characteristics

#

• Application Type: Spring Boot 3.5.0 JAR (executable with embedded Tomcat)
• Main Class: com.okta.server.scim.ScimServerApplication
• Launcher: org.springframework.boot.loader.launch.JarLauncher (Spring Boot fat JAR)
• JAR Location: data/okta-scim/conf/OktaOnPremScimServer-<version>.jar
• Default Port: 1443 (HTTPS)
• Base Context Path: /ws/rest
• Protocol: HTTPS only (TLS 1.2, TLS 1.3)

Architecture

#

Application Stack

#

The SCIM Server is built on a modern Spring Boot stack with embedded Tomcat, JDBC connectivity, and REST controllers that implement the SCIM 2.0 specification.

flowchart TB
 subgraph SCIM["Okta On-Prem SCIM Server"]
    direction TB
        E["Spring Boot 3.5.0"]
        F["Embedded Tomcat 10.x
- HTTPS/TLS
- Port 1443"]
        H["JDBC Connector:
- HikariCP Pool
- Stored Proc Executor"]
        G["REST Controllers:
- UserController
- GroupController
- EntitlementController
- StatusController"]
  end
 subgraph DB["Database"]
    direction TB
        I["Table USERS
Table ENTITLEMENTS
Table USERENTITLEMENTS
Stored Procedures"]
  end
    E -.->|manages| F & H & G
    OC["Okta Cloud"] -- HTTPS --> OPP["Okta Provisioning Agent"]
    SCIM -- JDBC Connection --> DB
    OPP -- "HTTPS + Bearer Token +
X-OKTA-ONPREM-DATA header" --> SCIM

    style OC fill:#e1f5ff
    style OPP fill:#fff4e6
    style SCIM fill:#e8f5e9
    style DB fill:#fce4ec

Core Components

#

1. Embedded Tomcat Server

#

• Version: Apache Tomcat 10.x
• Protocol: HTTPS with NIO connector
• Bundled with: Spring Boot 3.5.0
• Port: 1443 (configurable)
• TLS Support: TLS 1.2 and TLS 1.3

The embedded Tomcat server handles all HTTPS connections, TLS handshakes, and HTTP request processing. Since it uses self-signed certificates by default, you’ll see TLS handshake warnings in logs—this is expected behavior.

2. REST Controllers

#

Located in BOOT-INF/classes/com/okta/server/scim/controller/:

These controllers implement the SCIM 2.0 REST API specification, handling JSON payloads and translating them into database operations.

3. JDBC Connector

#

Located in BOOT-INF/classes/com/okta/server/scim/connector/jdbc/:

• DataSource Management: HikariCP connection pooling
• Executor: Stored procedure and SQL queries execution engine
• Service Layer: Workflow orchestration for SCIM operations
• Configuration: Dynamic connector configuration via properties

The JDBC connector is responsible for all database interactions, managing connection pools, executing stored procedures, and handling transaction boundaries.

4. Security Layer

#

Located in BOOT-INF/classes/com/okta/server/scim/security/:

• Bearer Token Authentication: Simple token-based auth
• SSL/TLS: Server-side certificate authentication
• No mTLS: Client certificate authentication disabled (server.ssl.client-auth=NONE)

The security layer validates the Authorization header on every request and enforces HTTPS-only communication.

Authentication

#

Bearer Token Authentication

#

The SCIM server uses Bearer token authentication for all SCIM API requests. This is a simple but effective authentication mechanism that requires each request to include a valid bearer token in the Authorization header.

Configuration of the Token

#

Bearer token is configured in the properties file:

File: data/okta-scim/conf/config-{CUSTOMER_ID}.properties

scim.security.bearer.token=d5307740c879491cedecf70c2225776b

This token is auto-generated during first startup by the RPM installer (or in the Docker Compose lab, the Docker entrypoint script).

Usage

#

Header Format:

Authorization: Bearer <token>

Example:

curl -k -H "Authorization: Bearer d5307740c879491cedecf70c2225776b" \
  https://localhost:1443/ws/rest/jdbc_on_prem/scim/v2/Status

Important Notes

#

1. Case Sensitive: The word Bearer must be capitalized
2. Space Required: There must be exactly one space between Bearer and the token
3. Length: 32 characters (hex string)
4. Rotation: To change the token, modify the properties file and restart the SCIM server. You will also need to update the configuration of the Generic Database Connector Application in Okta

SCIM Endpoints

#

Endpoint URL Pattern

#

All SCIM endpoints follow this pattern:

https://{host}:{port}/ws/rest/{app}/scim/v2/{resource}

Where:

• {host}: SCIM server hostname (e.g., okta-scim or localhost)
• {port}: SCIM server port (default: 1443)
• {app}: Application/connector name (e.g., jdbc_on_prem)
• {resource}: SCIM resource type (Users, Entitlements, etc.)

User Operations

#

Base Path: {app}/scim/v2/Users

List Users

#

GET /{app}/scim/v2/Users?startIndex=1&count=100
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}

Query Parameters:

• startIndex (optional): Starting index for pagination (1-based)
• count (optional): Number of results to return
• filter (optional): SCIM filter expression

Response: SCIM ListResponse with user resources

Get User by ID

#

GET /{app}/scim/v2/Users/{userId}
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}

Path Parameters:

• {userId}: User identifier (typically email or username)

Response: SCIM User resource

Create User

#

POST /{app}/scim/v2/Users
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "john.doe",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "john.doe@example.com",
      "primary": true
    }
  ],
  "active": true
}

Response: 201 Created with SCIM User resource

Update User

#

PUT /{app}/scim/v2/Users/{userId}
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "{userId}",
  "userName": "john.doe",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "active": false
}

Response: 200 OK with updated SCIM User resource

Entitlement Operations

#

Base Path: {app}/scim/v2/Entitlements

List Entitlements

#

GET /{app}/scim/v2/Entitlements
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}

Response: SCIM ListResponse with entitlement resources

Get Entitlement by ID

#

GET /{app}/scim/v2/Entitlements/{id}
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}

Response: SCIM Entitlement resource

SCIM Metadata Endpoints

#

These endpoints provide metadata about the SCIM server’s capabilities, schemas, and supported resource types.

Service Provider Configuration

#

GET /{app}/scim/v2/ServiceProviderConfig
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}

Returns SCIM server capabilities (supported operations, bulk operations, filtering, etc.)

Schemas

#

GET /{app}/scim/v2/Schemas
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}

Returns SCIM schema definitions for User, Group, and custom resources.

Resource Types

#

GET /{app}/scim/v2/ResourceTypes
Authorization: Bearer {token}
X-OKTA-ONPREM-DATA: {base64_encoded_config}

Returns available SCIM resource types (User, Group, Entitlement).

Health Check

#

Status Endpoint

#

The Status endpoint is the only endpoint that does NOT require the X-OKTA-ONPREM-DATA header. It’s designed for health checks and monitoring systems.

Endpoint: {app}/scim/v2/Status

Method: GET

Authentication: Bearer token only

Example:

curl -k -H "Authorization: Bearer d5307740c879491cedecf70c2225776b" \
  https://localhost:1443/ws/rest/jdbc_on_prem/scim/v2/Status

Success Response:

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 27

✅ Scim Server is running.

Use Cases:

• Docker health checks (HEALTHCHECK directive)
• Monitoring systems (Nagios, Prometheus, Zabbix, etc.)
• Load balancer health checks
• Startup validation scripts

This simple endpoint confirms the SCIM server is running and accepting HTTPS connections. It doesn’t validate database connectivity—it only confirms the web server is operational.

X-OKTA-ONPREM-DATA Header

#

Purpose

#

The X-OKTA-ONPREM-DATA header is a custom HTTP header that contains the connector configuration required for SCIM operations. It’s automatically added by the Okta Provisioning Agent when forwarding requests to the SCIM server.

This header is what enables a single SCIM Server to manage multiple database systems simultaneously—each request carries its own configuration payload.

Contents

#

The header contains a Base64-encoded JSON payload with:

• Database connection details: JDBC URL, username, password
• Stored procedure mappings: Which stored procedures to call for each SCIM operation
• Attribute mappings: How SCIM attributes map to database columns/parameters
• Connector metadata: Connector type, version, configuration version

Why It’s Required

#

1. Multi-tenancy: The SCIM server can serve multiple connectors simultaneously
2. Dynamic Configuration: Each request includes its own configuration, allowing runtime changes
3. Security: Configuration is passed per-request rather than stored on the SCIM server
4. Flexibility: Different Okta apps can use different database configurations

This architecture means you can have one SCIM server managing up to 8 different databases, each with its own connection details, stored procedures, and attribute mappings—all determined dynamically by the header content.

Flow Diagram

#

The following diagram illustrates how the X-OKTA-ONPREM-DATA header flows through the provisioning request lifecycle:

sequenceDiagram
    participant OC as Okta Cloud
    participant OPP as Okta Provisioning Agent
    participant SCIM as Okta On-Prem
SCIM Server
    participant DB as On-prem
Database

    Note over OC: 1. User creates
provisioning request

    OC->>OPP: 2. Send request to Agent

    Note over OPP: 3. Retrieves
DB config and Bearer Token
from Okta
    Note over OPP: 4. Encodes config
as Base64
    Note over OPP: 5. Adds headers:
'X-OKTA-ONPREM-DATA'
and 'Authorization'

    OPP->>SCIM: 6. Forward to SCIM Server
(HTTPS + headers)

    Note over SCIM: 7. Check Authorization Token
    Note over SCIM: 8. Decode headers
    Note over SCIM: 9. Extract from DB config:
- JDBC URL
- Credentials
- Stored procs
    Note over SCIM: 10. Execute operation

    SCIM->>DB: 11. JDBC call

    Note over DB: 12. Execute Stored Procedure

    DB-->>SCIM: Result
    SCIM-->>OPP: SCIM Response
    OPP-->>OC: Provisioning Result

Error Response

#

If the header is missing, the SCIM server returns:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "scimType": "MISSING_ATTRIBUTE",
  "detail": "Missing X-OKTA-ONPREM-DATA header",
  "status": 400
}

HTTP Status: 400 Bad Request

Testing Without Agent

#

For development and debugging, you can manually construct the header:

# Example connector config (JSON)
CONFIG='{
  "jdbcUrl": "jdbc:mysql://db:3306/oktademo",
  "username": "oktademo",
  "password": "oktademo",
  "procedures": {
    "listUsers": "GET_ACTIVEUSERS",
    "getUser": "GET_USER_BY_ID",
    "createUser": "CREATE_USER",
    "updateUser": "UPDATE_USER"
  }
}'

# Base64 encode
ENCODED=$(echo -n "$CONFIG" | base64)

# Make request with header
curl -k \
  -H "Authorization: Bearer d5307740c879491cedecf70c2225776b" \
  -H "X-OKTA-ONPREM-DATA: $ENCODED" \
  https://localhost:1443/ws/rest/jdbc_on_prem/scim/v2/Users

Configuration

#

Configuration Files

#

All configuration is stored in: data/okta-scim/conf/

1. Application Properties

#

File: config-{CUSTOMER_ID}.properties

# HTTPS Configuration
server.port=1443
server.servlet.context-path=/ws/rest
server.ssl.enabled=true

# SSL/TLS Certificate
server.ssl.key-store-type=PKCS12
server.ssl.key-store=/etc/pki/tls/private/OktaOnPremScimServer-{CUSTOMER_ID}.p12
server.ssl.key-store-password={auto_generated}
server.ssl.key-alias=okscimservercert

# TLS Protocols
server.ssl.enabled-protocols=TLSv1.2,TLSv1.3

# Client Authentication (disabled)
server.ssl.client-auth=NONE

# Request Size
server.max-http-request-header-size=10KB

# Bearer Token Authentication
scim.security.bearer.token={auto_generated}

# HikariCP Database Connection Pool
app.datasource.hikari.maximumPoolSize=10
app.datasource.hikari.minimumIdle=0
app.datasource.hikari.connectionTimeout=30000
app.datasource.hikari.validationTimeout=3000
app.datasource.hikari.idleTimeout=90000
app.datasource.hikari.keepaliveTime=60000
app.datasource.hikari.maxLifetime=180000
app.datasource.hikari.initializationFailTimeout=0

# Logging Configuration
logging.level.root=INFO
logging.level.org.springframework.web=WARN
logging.level.org.apache.catalina=WARN
logging.level.com.okta.server.scim=INFO
logging.level.org.springframework.jdbc=INFO

logging.pattern.file=%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}  [pid:${PID:-unknown}] [%thread] %class{36}:%line - %msg%n
logging.pattern.console=1

2. Customer ID Configuration

#

File: customer-id.conf

CUSTOMER_ID=myorg

Used to namespace configuration and certificates for multi-instance deployments.

3. JVM Configuration

#

File: jvm.conf

JAVA_OPTS="-Xmx2048m -Xms1024m -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

Java memory and garbage collection settings.

Certificate Files

#

Stored in: data/okta-scim/certs/

Auto-Generated Certificates

#

The entrypoint script automatically generates:

1. Public Certificate: OktaOnPremScimServer-{CUSTOMER_ID}.crt

   • 4096-bit RSA
   • 10-year validity
   • Self-signed
   • Format: PEM (X.509)

2. Private Key: OktaOnPremScimServer-{CUSTOMER_ID}.key

   • RSA private key
   • Format: PEM (PKCS#8)

3. PKCS12 Keystore: OktaOnPremScimServer-{CUSTOMER_ID}.p12

   • Contains certificate + private key
   • Password: Auto-generated (stored in properties file)
   • Alias: okscimservercert

Logging and Debugging

#

Log Files

#

Location: /var/log/OktaOnPremScimServer/ (mapped to data/okta-scim/logs/ on host in Docker Compose setup)

Files:

• application.log - Main application log

Log Levels

#

Configured in config-{CUSTOMER_ID}.properties:

logging.level.root=INFO
logging.level.org.springframework.web=WARN           # HTTP requests/responses
logging.level.org.apache.catalina=WARN               # Tomcat server
logging.level.org.apache.coyote=WARN                 # HTTP connector
logging.level.org.apache.tomcat=WARN                 # Tomcat internals
logging.level.com.zaxxer.hikari=WARN                 # Connection pool
logging.level.com.okta.server.scim=INFO              # SCIM operations
logging.level.org.springframework.jdbc=INFO          # JDBC operations

Available Levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF

Log Format

#

File Pattern:

%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}  [pid:${PID:-unknown}] [%thread] %class{36}:%line - %msg%n

Example:

2026-02-17T11:54:32.123+00:00  [pid:42] [https-jsse-nio-1443-exec-1] c.o.s.s.controller.UserController:87 - Creating user: john.doe@example.com

Debugging SCIM Operations

#

Enable detailed JDBC logging to see SQL queries:

logging.level.org.springframework.jdbc.core=TRACE

This logs:

• SQL statements before execution
• Parameter values
• Result sets
• Transaction boundaries

Common Log Patterns

#

TLS Handshake Failures:

Handshake failed for client connection from IP address [192.168.65.1]

Cause: Client doesn’t trust the self-signed certificate (expected behavior)

Missing Header:

Missing X-OKTA-ONPREM-DATA header

Cause: Direct API call without Okta Provisioning Agent

JDBC Connection Issues:

HikariPool - Exception during pool initialization

Cause: Database not reachable or credentials incorrect

Stored Procedure Errors:

CallableStatementCallback; ERROR 1305 (42000): PROCEDURE oktademo.CREATE_USER does not exist

Cause: Stored procedure not created in database

Database Connectivity

#

Connection Pooling

#

The SCIM server uses HikariCP for database connection pooling:

app.datasource.hikari.maximumPoolSize=10              # Max connections
app.datasource.hikari.minimumIdle=0                   # Min idle connections
app.datasource.hikari.connectionTimeout=30000         # 30 seconds
app.datasource.hikari.validationTimeout=3000          # 3 seconds
app.datasource.hikari.idleTimeout=90000               # 90 seconds
app.datasource.hikari.keepaliveTime=60000             # 60 seconds
app.datasource.hikari.maxLifetime=180000              # 180 seconds
app.datasource.hikari.initializationFailTimeout=0     # Fail immediately

HikariCP is known for being the fastest, most reliable connection pool for JDBC. The SCIM Server leverages it to maintain a pool of database connections that can be reused across requests, significantly improving performance.

JDBC Drivers

#

Location: /opt/OktaOnPremScimServer/userlib/

Copied from: docker/okta-scim/packages/*.jar (in Docker Compose setup)

Supported Drivers:

• MySQL Connector/J: mysql-connector-j-9.6.0.jar
• PostgreSQL: postgresql-*.jar
• Oracle JDBC: ojdbc*.jar
• SQL Server: mssql-jdbc-*.jar

Connection Configuration

#

Database connection details are provided in the X-OKTA-ONPREM-DATA header on each request:

{
  "jdbcUrl": "jdbc:mysql://db:3306/oktademo",
  "username": "oktademo",
  "password": "oktademo",
  "driverClassName": "com.mysql.cj.jdbc.Driver"
}

This per-request configuration approach enables the multi-database capability—each request can target a different database by including different connection details in its header.

Conclusion

#

Understanding the Okta On-Prem SCIM Server’s architecture and internals provides valuable insight into how modern provisioning solutions bridge cloud identity platforms with on-premises infrastructure. Through this reverse-engineered analysis, you now understand:

• The application stack: Spring Boot 3.5.0 with embedded Tomcat handling HTTPS on port 1443
• REST Controllers: How SCIM 2.0 operations map to Java controllers and ultimately database operations
• Authentication mechanisms: Bearer token validation and the role of the X-OKTA-ONPREM-DATA header
• Connection pooling: HikariCP managing database connections efficiently
• Logging patterns: How to interpret logs for troubleshooting
• Multi-tenancy architecture: How one SCIM server handles multiple databases

While this knowledge is powerful for debugging, troubleshooting, and understanding your provisioning infrastructure, remember that the only supported way to interact with the SCIM Server in production is through the Okta Provisioning Agent and Admin Console. Direct API access should remain in the lab environment for educational exploration.

Next Steps

#

• Implement the full lab environment: Follow the main Generic Database Connector guide to deploy your own test environment
• Monitor your SCIM Server: Set up logging and health checks based on the patterns discussed
• Optimize performance: Tune HikariCP connection pool settings for your workload
• Explore the JAR: Extract and examine the Spring Boot JAR structure yourself for deeper learning

Questions or want to explore more? Check out the GitHub repository for the complete lab environment and additional technical documentation.

Additional Resources

#

Official Okta Documentation

#

• Install the Okta On-prem SCIM Server
• On-premises Connector for Generic Databases
• Okta Lifecycle Management

SCIM Protocol Resources

#

• SCIM 2.0 RFC 7644 - Official SCIM specification
• SCIM 2.0 Core Schema - User and Group schemas
• Okta SCIM Documentation - Okta’s SCIM implementation guide

Related Articles

#

• On-premises Connector for Generic Databases with Docker Compose: A Complete Guide - Full deployment and configuration guide

Project Resources

#

• GitHub Repository - Complete Docker Compose lab environment
• Okta SCIM Server Technical Documentation - Original reverse-engineered documentation
• Okta Provisioning Configuration Guide - Detailed Admin Console setup

Disclaimer

#

This article contains technical information obtained through reverse engineering for educational purposes only. The content is provided “as is” without warranty of any kind. Always use official Okta documentation and support channels for production deployments.

Remember: Use the Okta On-Prem SCIM Server only through officially supported methods—the Okta Provisioning Agent and Okta Admin Console—in production environments.

Introduction

#

Your organization likely runs critical business applications backed by custom databases—systems that have been reliable workhorses for years but don’t speak the language of modern identity protocols. While integrating cloud applications with Okta using SAML, OIDC (OpenID Connect), and SCIM 2.0 is straightforward, bringing these legacy database-driven applications into your unified identity fabric has historically required complex custom scripting or middleware solutions.

Okta recently released the On-premises Connector for Generic Databases, a powerful Early Access feature that changes the game. This connector enables direct provisioning and lifecycle management to on-premises databases via JDBC, bringing automated joiner/mover/leaver (JML) workflows and entitlement management to applications that were previously difficult to integrate. No more custom scripts, no more manual account management—just standards-based automation using the SCIM protocol.

This guide provides a complete deep dive into deploying and configuring the Generic Database Connector. You’ll build a fully functional test environment using Docker Compose with MariaDB (MySQL-compatible), configure every aspect of the integration—from user provisioning to entitlement management—and test real-world scenarios including user creation, attribute updates, entitlement assignments, and deactivation workflows.

Why Docker for This Lab?

Docker Compose provides the fastest path to a working environment, letting you spin up the entire stack—Okta Provisioning Agent, SCIM Server, MariaDB database, and a web-based management interface—in minutes. While Okta doesn’t officially support Docker for production deployments, it’s ideal for demonstrations, proof-of-concepts, and learning the integration workflow.

Importantly, every configuration step in this guide applies equally to manual installations on production systems. Whether you’re testing in Docker or deploying on dedicated Linux servers, the Okta configuration, stored procedures, and integration patterns remain identical. Think of the Docker environment as an accelerator for understanding—once you’ve mastered the concepts here, translating them to a production deployment is straightforward.

Quick Instructions

#

1. Clone the repository: https://github.com/fabiograsso/okta-lab-onprem-jdbc
2. Download the required RPM files from Okta Help Center:
   • Okta Provisioning Agent: OktaProvisioningAgent-*.rpm → copy to ./docker/okta-opp/packages/
   • Okta SCIM Server: OktaOnPremScimServer-*.rpm → copy to ./docker/okta-scim/packages/
3. Configure the environment: cp .env-sample .env (edit if needed)
4. Build and start: make build && make start-logs
5. Configure the OPP Agent: make configure (once you see “Waiting for configuration files” message)
6. Retrieve SCIM credentials from ./data/okta-scim/conf/config-*.properties
7. Configure the Generic Database Connector application in Okta Admin Console

Prerequisites

#

System Requirements

#

• Docker and Docker Compose (v2+) are installed
  • If you are using Ubuntu 24.04 Linux server: apt-get install -y docker docker-compose
  • You can also use Docker Desktop
• Okta Organization with administrative access
• Git (to clone the repository)

Okta Early Access Feature

#

Since the Okta Generic Database Connector is currently an Early Access feature, you need to enable it in the Okta Admin Panel:

1. Navigate to Settings → Features
2. Enable “OPP Agent with SCIM 2.0 support”
3. Enable “On-prem Connector for Generic Databases”

Required Files from Okta

#

You’ll need to download installer packages from the Okta Admin Console.

For OPP Agent - Place in ./docker/okta-opp/packages/:

For SCIM Server - Place in ./docker/okta-scim/packages/:

Understanding the Architecture

#

Before diving into the setup, it’s essential to understand how the components work together.

What is the Okta Generic Database Connector (JDBC)?

#

The Okta Generic Database Connector allows Okta to connect to on-premises databases using JDBC drivers. It enables comprehensive user lifecycle management and entitlement operations by executing SQL queries or stored procedures against the database. This is particularly valuable for organizations with legacy applications or custom databases that don’t support modern provisioning protocols but can be accessed via JDBC.

What is the Okta On-Premises Provisioning Agent?

#

The Okta On-Premises Provisioning (OPP) Agent acts as a secure bridge between Okta’s cloud identity platform and your on-premises applications. Key capabilities include:

• Automated User Provisioning: Create, update, and deactivate user accounts in on-premises databases
• SCIM Protocol Support: Industry-standard protocol for user identity management
• Secure Communication: Outbound-only HTTPS connections from your network to Okta (no inbound firewall rules required)
• Real-time Synchronization: Push user changes from Okta to on-premises systems instantly

What is the Okta On-Prem SCIM Server?

#

The Okta On-prem SCIM Server is a Java application that translates SCIM API calls from the OPP Agent into database operations using JDBC. It serves as the intermediary layer that allows Okta to manage user accounts in your on-premises database through the SCIM protocol.

How They Work Together

#

The complete provisioning flow involves four key stages:

1. Okta Cloud → OPP Agent: The Provisioning Agent maintains a secure, outbound HTTPS connection from your network to Okta using long polling. Since the connection originates from within your network perimeter, no inbound firewall rules are required.

2. OPP Agent → SCIM Server: When lifecycle management or provisioning requests arrive from Okta, the Agent relays them to the SCIM Server for processing.

3. SCIM Server → Database: The SCIM Server interprets incoming SCIM requests and executes the corresponding database operations—creating users, modifying attributes, deactivating accounts, or managing entitlements—directly against your on-premises database.

4. Response Flow: Data and operation results return through the same path in reverse: from the database to the SCIM Server, then to the Provisioning Agent, which securely transmits the results back to Okta.

---
config:
 layout: dagre
---
flowchart TB
 subgraph subGraph0["**Okta Cloud**"]
 A["Okta Org"]
 end
 subgraph subGraph1["**Docker Environment**"]
 B["OPP Agent"]
 C["SCIM Server"]
 D["MariaDB Database"]
 E["DBGate UI"]
 end
 B -- Outbound HTTPS --> A
 B -- SCIM Protocol --> C
 C -- JDBC Connection --> D
 E -- Management --> D

 style B fill:#FFE0B2
 style C fill:#FFE0B2
 style D fill:#FFCDD2
 style E fill:#FFF9C4
 style subGraph0 stroke:#757575,fill:#C8E6C9
 style subGraph1 fill:#BBDEFB,stroke:#2962FF

Lab Components

#

This Docker Compose environment includes four separate containers:

1. Okta Provisioning Agent (okta-opp): CentOS based container running the OPP Agent
2. Okta On-Prem SCIM Server (okta-scim): CentOS 9-based container running the SCIM Server
3. MariaDB (db): Database server pre-populated with test data and stored procedures
4. DBGate: Web-based database management interface for easy data inspection

Multi-Database Support

#

A powerful feature of this solution is that a single OPP Agent and SCIM Server deployment can manage up to 8 databases simultaneously. This enables:

• Management of users across multiple applications
• Support for different database types (MySQL, PostgreSQL, Oracle, SQL Server)
• Separation of production and staging environments
• Organizational unit isolation

Each database requires a separate Generic Database Connector application instance in Okta, but all share the same on-premises infrastructure. This means you only need one OPP Agent and one SCIM Server installation to provision to multiple databases—just ensure all required JDBC drivers are available in the SCIM Server before building the container.

Docker Compose Setup

#

Docker provides the fastest path to a working environment. This section covers the complete setup process using Docker Compose.

Initial Setup

#

1. Clone the Repository

   git clone https://github.com/fabiograsso/okta-lab-onprem-jdbc
   cd okta-lab-onprem-jdbc

2. Prepare Required Files

   Download the RPM packages from the Okta Help Center and organize them:

   # Copy OPP Agent RPM
   cp /path/to/OktaProvisioningAgent-*.rpm ./docker/okta-opp/packages/
   
   # Copy SCIM Server RPM
   cp /path/to/OktaOnPremScimServer-*.rpm ./docker/okta-scim/packages/

3. Configure Environment Variables

   The .env file contains all configuration parameters:

   cp .env-sample .env

   You can customize the database settings if needed (default values work for testing):

   # Database Configuration
   MARIADB_PORT=3306
   MARIADB_DATABASE=oktademo
   MARIADB_USER=oktademo
   MARIADB_PASSWORD=oktademo
   MARIADB_ROOT_PASSWORD=oktademo
   
   # SCIM Server Logging (for troubleshooting)
   LOG_LEVEL_ROOT=INFO
   LOG_LEVEL_OKTA_SCIM=INFO
   LOG_LEVEL_SPRING_JDBC=INFO

Build and Start Services

#

The project includes a Makefile with convenient commands for managing the Docker environment:

# Build Docker images (includes prerequisite checks)
make build

# Start all services (detached mode with log following)
make start-logs

# Alternative: Start in detached mode without logs
# make start

The make start command will:

• Run prerequisite checks to verify RPM files are present
• Start all four containers (db, dbgate, okta-scim, okta-opp)
• Initialize the database with schema and test data
• Generate SCIM Server certificates and configuration

You’ll see output similar to this:

[+] Running 4/4
 ✔ Container lab-db-1          Started
 ✔ Container lab-dbgate-1      Started
 ✔ Container lab-okta-scim-1   Started
 ✔ Container lab-okta-opp-1    Started

Configure the OPP Agent

#

After the containers start, the OPP Agent will wait for configuration. You’ll see this message in the logs:

⏳ Waiting for configuration files. Please configure the Agent...

Now run the interactive configuration script:

make configure

Follow the prompts:

1. Okta Subdomain: Enter your Okta org URL (e.g., https://myorg.okta.com)
2. Proxy Server: Press Enter to skip (unless you’re behind a proxy)
3. LDAP Server: Not applicable for database connector - press Enter to skip
4. SCIM Server: Not applicable - configuration is automatic via Docker networking

The script will display an activation URL and code:

Please visit the URL: https://myorg.okta.com/activate
and enter the following code: MSJPKGRP
before Fri Mar 02 15:30:00 UTC 2026 to authenticate and continue agent registration.

Open the provided URL in your browser, enter the activation code, and click “Allow” to complete the registration.

You’ll see a success message:

[INFO] - Register Mode successfully finished

Configuration successful.

Service can now be started by typing
systemctl start OktaProvisioningAgent.service
as root.

Retrieve SCIM Server Credentials

#

The SCIM Server automatically generates a bearer token and self-signed certificate on first startup. These credentials are needed to configure the Okta application.

Option 1 - From Host Filesystem:

# Get the bearer token (look for scim.security.bearer.token property)
cat ./data/okta-scim/conf/config-*.properties | grep bearer.token

# Output example:
# scim.security.bearer.token=da655feabd8ec0c3f89c1fb6e9f0ad39

# Get the public certificate
cat ./data/okta-scim/certs/OktaOnPremScimServer-*.crt

Option 2 - From Container:

# Display all credentials
docker compose exec okta-scim /opt/OktaOnPremScimServer/bin/Get-OktaOnPremScimServer-Credentials.sh

# Get just the certificate
docker compose exec okta-scim bash -c 'cat /opt/OktaOnPremScimServer/certs/OktaOnPremScimServer-*.crt'

Save these credentials - you’ll need them when configuring the Okta application:

• SCIM Hostname: okta-scim (container name for internal Docker networking)
• Bearer Token: The value from scim.security.bearer.token (will be prefixed with Bearer in Okta)
• Certificate: The .crt file contents

Verify the Setup

#

Check that all containers are running properly:

# Check container status
docker compose ps

# Expected output:
# NAME               STATUS        PORTS
# lab-db-1           Up (healthy)  33060/tcp
# lab-dbgate-1       Up            0.0.0.0:8090->3000/tcp
# lab-okta-scim-1    Up (healthy)  0.0.0.0:1443->1443/tcp
# lab-okta-opp-1     Up

You can also access the DBGate web interface to inspect the database:

• Open http://localhost:8090 in your browser
• Username: oktademo
• Password: oktademo

Other Useful Commands

#

The Makefile provides additional commands for managing the environment:

Database Schema and Test Data

#

The MariaDB database is automatically initialized with a comprehensive schema designed for realistic user provisioning scenarios.

Database Tables

#

The database includes three core tables:

USERS Table:

• Identity: USER_ID (PRIMARY KEY), USERNAME (UNIQUE), EMAIL
• Personal: FIRSTNAME, LASTNAME, MIDDLENAME, DISPLAYNAME, NICKNAME
• Contact: MOBILEPHONE, STREETADDRESS, CITY, STATE, ZIPCODE, COUNTRYCODE, TIMEZONE
• Work: TITLE, ORGANIZATION, DEPARTMENT, EMPLOYEENUMBER, MANAGER, MANAGERID
• Dates: HIREDATE, TERMINATIONDATE
• Security: PASSWORD_HASH, IS_ACTIVE (BOOLEAN, default TRUE)

ENTITLEMENTS Table

• ENT_ID (INT PRIMARY KEY, values 1-10)
• ENT_NAME (VARCHAR 100, UNIQUE)
• ENT_DESCRIPTION (VARCHAR 255)

USERENTITLEMENTS Table (Junction Table):

• USERENTITLEMENT_ID (INT PRIMARY KEY, AUTO_INCREMENT)
• USER_ID (FOREIGN KEY to USERS)
• ENT_ID (FOREIGN KEY to ENTITLEMENTS)
• ASSIGNEDDATE (DATETIME, auto-populated)
• Unique constraint on (USER_ID, ENT_ID) combination

erDiagram
    USERS ||--o{ USERENTITLEMENTS : "has"
    ENTITLEMENTS ||--o{ USERENTITLEMENTS : "assigned_to"

    USERS {
        VARCHAR(100) *USER_ID PK "User identifier (email format) - REQUIRED"
        VARCHAR(100) USERNAME UK "Login username (unique) - REQUIRED"
        VARCHAR(100) EMAIL "Email address - REQUIRED"
        VARCHAR(100) FIRSTNAME "First name - REQUIRED"
        VARCHAR(100) LASTNAME "Last name - REQUIRED"
        VARCHAR(100) OTHERFIELDS "...Other Fields..."
        DATE HIREDATE "Date of hire"
        DATE TERMINATIONDATE "Date of termination"
        VARCHAR(255) PASSWORD_HASH "Password hash"
        BOOLEAN IS_ACTIVE "Account status (default TRUE)"
    }

    ENTITLEMENTS {
        INT ENT_ID PK "Entitlement identifier"
        VARCHAR(100) ENT_NAME UK "Entitlement name (unique)"
        TEXT ENT_DESCRIPTION "Description of entitlement"
    }

    USERENTITLEMENTS {
        INT USERENTITLEMENT_ID PK "Auto-increment ID"
        VARCHAR(100) USER_ID FK "Foreign key to USERS"
        INT ENT_ID FK "Foreign key to ENTITLEMENTS"
        DATETIME ASSIGNEDDATE "When entitlement was assigned"
    }

Test Data

#

The database comes pre-populated with 15 Star Wars characters as test users:

10 Pre-configured Entitlements:

1. VPN Access
2. GitHub Admin
3. AWS Console
4. Jira Admin
5. Confluence Edit
6. Database Read
7. Database Write
8. Slack Admin
9. Office 365
10. Salesforce

You can inspect the test data using DBGate or command-line queries:

# View all users
docker compose exec db mariadb -u oktademo -poktademo oktademo \
  -e "SELECT USER_ID, FIRSTNAME, LASTNAME, TITLE, ORGANIZATION FROM USERS LIMIT 10;"

# View all entitlements
docker compose exec db mariadb -u oktademo -poktademo oktademo \
  -e "SELECT * FROM ENTITLEMENTS;"

# View user-entitlement assignments
docker compose exec db mariadb -u oktademo -poktademo oktademo \
  -e "SELECT * FROM USERENTITLEMENTS LIMIT 10;"

Operational Views

#

The database also includes 6 operational views for convenient monitoring and reporting queries:

• V_USERENTITLEMENTS - Comprehensive view joining users with their entitlements
• V_ACTIVE_USERS - Quick access to active users only
• V_INACTIVE_USERS - Quick access to inactive/deactivated users
• V_ENTITLEMENT_USAGE - Statistics on entitlement assignments
• V_USER_HIERARCHY - User reporting structure and management chains
• V_INACTIVE_USERENTITLEMENTS - Entitlements assigned to inactive users (for cleanup)

These views provide simplified access to common queries without writing complex joins, making it easier to monitor your identity data.

Stored Procedures

#

The database includes stored procedures that provide a clean abstraction layer for SCIM operations:

Import Operations (To Okta):

1. GET_ACTIVEUSERS() - Retrieve all active users (WHERE IS_ACTIVE = 1)
2. GET_USER_BY_ID(p_user_id) - Get specific user by USER_ID
3. GET_ALL_ENTITLEMENTS() - List all available entitlements
4. GET_USER_ENTITLEMENT(p_user_id) - Get user’s assigned entitlements

Provisioning Operations (To App):

5. CREATE_USER(...) - Create new user with 24 parameters (5 mandatory, 19 optional)
6. UPDATE_USER(...) - Update user attributes with 24 parameters (5 mandatory, 19 optional)
7. ACTIVATE_USER(p_user_id) - Set IS_ACTIVE = TRUE
8. DEACTIVATE_USER(p_user_id) - Set IS_ACTIVE = FALSE
9. ADD_ENTITLEMENT_TO_USER(p_user_id, p_ent_id) - Assign entitlement
10. REMOVE_ENTITLEMENT_FROM_USER(p_user_id, p_ent_id) - Revoke entitlement

You can test stored procedures directly:

# Test GET_ACTIVEUSERS
docker compose exec db mariadb -u oktademo -poktademo oktademo \
  -e "CALL GET_ACTIVEUSERS();"

# Test GET_USER_ENTITLEMENT
docker compose exec db mariadb -u oktademo -poktademo oktademo \
  -e "CALL GET_USER_ENTITLEMENT('yoda@galaxy.local');"

SQL Queries vs Stored Procedures

#

The Generic Database Connector supports two approaches for configuring database operations:

1. SQL Statements: Direct SQL queries (e.g. SELECT, INSERT, UPDATE, DELETE)
2. Stored Procedures: Pre-compiled database procedures that encapsulate business logic

This guide provides both options for each operation, allowing you to choose the approach that best fits your requirements and database architecture. Stored procedures are pre-configured in sql/stored_proc.sql and are the recommended approach.

The following diagram illustrates how all stored procedures interact with the database tables:

---
config:
  layout: elk
---
flowchart TB
 subgraph s1["Database Tables"]
        USERENTITLEMENTS[("USERENTITLEMENTS
Junction Table")]
        ENTITLEMENTS[("ENTITLEMENTS
ENT_ID, ENT_NAME, ENT_DESCRIPTION")]
        USERS[("USERS")]
  end
 subgraph s2["Read Operations"]
        GET_USER_ENTITLEMENT["GET_USER_ENTITLEMENT
Input: p_user_id"]
        GET_ALL_ENTITLEMENTS["GET_ALL_ENTITLEMENTS
Returns all entitlements"]
        GET_USER_BY_ID["GET_USER_BY_ID
Input: p_user_id"]
        GET_ACTIVEUSERS["GET_ACTIVEUSERS
Returns all active users"]
  end
 subgraph s3["User Lifecycle Operations"]
        DEACTIVATE_USER["DEACTIVATE_USER
Input: p_user_id"]
        ACTIVATE_USER["ACTIVATE_USER
Input: p_user_id"]
        UPDATE_USER["UPDATE_USER
29 Parameters
5 mandatory + 24 optional"]
        CREATE_USER["CREATE_USER
29 Parameters
5 mandatory + 24 optional"]
  end
 subgraph s4["Entitlement Management"]
        REMOVE_ENTITLEMENT["REMOVE_ENTITLEMENT_FROM_USER
Inputs: p_user_id, p_ent_id"]
        ADD_ENTITLEMENT["ADD_ENTITLEMENT_TO_USER
Inputs: p_user_id, p_ent_id"]
  end
    GET_ACTIVEUSERS -- "SELECT WHERE IS_ACTIVE=1" --> USERS
    GET_USER_BY_ID -- "SELECT WHERE USER_ID=?" --> USERS
    GET_ALL_ENTITLEMENTS -- SELECT * --> ENTITLEMENTS
    GET_USER_ENTITLEMENT -- JOIN --> USERENTITLEMENTS & USERS & ENTITLEMENTS
    CREATE_USER -- INSERT --> USERS
    UPDATE_USER -- "UPDATE WHERE USER_ID=?" --> USERS
    ACTIVATE_USER -- "UPDATE IS_ACTIVE=1" --> USERS
    DEACTIVATE_USER -- "UPDATE IS_ACTIVE=0" --> USERS
    ADD_ENTITLEMENT -- INSERT --> USERENTITLEMENTS
    ADD_ENTITLEMENT -. Validates .-> USERS & ENTITLEMENTS
    REMOVE_ENTITLEMENT -- DELETE --> USERENTITLEMENTS

     USERS:::tableStyle
     ENTITLEMENTS:::tableStyle
     USERENTITLEMENTS:::tableStyle
     GET_ACTIVEUSERS:::readStyle
     GET_USER_BY_ID:::readStyle
     GET_ALL_ENTITLEMENTS:::readStyle
     GET_USER_ENTITLEMENT:::readStyle
     CREATE_USER:::lifecycleStyle
     UPDATE_USER:::lifecycleStyle
     ACTIVATE_USER:::lifecycleStyle
     DEACTIVATE_USER:::lifecycleStyle
     ADD_ENTITLEMENT:::entitlementStyle
     REMOVE_ENTITLEMENT:::entitlementStyle
    classDef tableStyle fill:#e1f5ff,stroke:#0066cc,stroke-width:2px
    classDef readStyle fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef lifecycleStyle fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    classDef entitlementStyle fill:#f8d7da,stroke:#dc3545,stroke-width:2px

Configuring Okta Integration

#

Now that the infrastructure is running, it’s time to configure the Okta side of the integration. This section covers the complete setup process in the Okta Admin Console.

Create the Generic Database Connector Application

#

1. Navigate to Applications

   • Log on to Okta Admin Console
   • Navigate to Applications → Browse App Catalog

2. Search for Generic Database Connector

   • In the search box, type “Generic Database”
   • Select “On-prem connector for Generic Databases” from the results

3. Add the Integration

   • Click Add Integration

   

4. Configure Application Label

   • Provide a name for the application in the Application Label field (Default name: “Generic Database Connector”)
   • Check “Do not display application icon to users”
   • Click Next

   

5. Complete Application Setup

   • Leave all the other fields as default and click Done

6. Enable Entitlement Management

   • In the General tab, scroll down to the Entitlement Management section
   • Click Edit
   • From the dropdown menu, select Enable
   • Click Save

   

   Once entitlement management is enabled, you’ll notice that the Governance tab now shows additional sub-tabs such as Entitlements, Bundles, etc.

Enable and Configure Provisioning

#

1. Enable Provisioning

   • Navigate to the Provisioning tab
   • Click Enable Provisioning

   

2. Select OPP Agent

   • This page displays all available Okta Provisioning Agents (both active and inactive) in your Okta org
   • Select your registered Okta Provisioning Agent okta-opp from the list
   • Click Next

   

3. Configure SCIM Server Connection

   • Enter the SCIM Hostname: okta-scim (must match the container name for internal connectivity)

   • Enter the API Token with the Bearer prefix (from SCIM Server credentials)

     • Example: Bearer d5307740c879491cedecf70c2225776b
       IMPORTANT: When configuring the Okta application, you MUST add the Bearer prefix before the token value, with a space between Bearer and the token.

   • Click Add Files under Public Key

   • Upload the certificate file (.crt) from the host system ./data/okta-scim/certs/OktaOnPremScimServer-*.crt

     • Or save in a .crt or .pem file the certificate extacted with the command:

       docker compose exec okta-scim bash -c 'cat /opt/OktaOnPremScimServer/certs/OktaOnPremScimServer-*.crt'

   • Click Next

   

4. Configure Database Connection

   • Provide the database connection details (change them if you are not using the default values in your .env file):
     • Username: oktademo
     • Password: oktademo
     • Type of Database: Select MySQL
     • IP/Domain Name: db (must match the container name for internal connectivity)
     • Port: 3306
     • Database Name: oktademo
     • Add the following additional key/value pair in the Database Property: Configuration of Key-Value Pairs section:
       • Key: allowMultiQueries
       • Value: true
   • Click Setup Complete

   

5. You will see a Connecting agents… pop-up for a few seconds.

   

6. Connection Success: Once the connection is successful, you’ll be directed to the Integration tab of the Provisioning section. From here, you can proceed to configure Schema Discovery & Import and Provisioning operations.

Configure Import Operations (To Okta)

#

Import operations retrieve data from the database and bring it into Okta.

Navigate to Import Settings

#

1. Go to Okta Admin Console → Applications → Generic Database Connector
2. Navigate to the Provisioning tab
3. Go to Integration → To Okta
4. Click Edit next to Schema discovery & Import

1. Get Users

#

Import all active users from the database.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  SELECT USER_ID, USERNAME, FIRSTNAME, LASTNAME, MIDDLENAME, EMAIL, DISPLAYNAME, NICKNAME, MOBILEPHONE, STREETADDRESS, CITY, STATE, ZIPCODE, COUNTRYCODE, TIMEZONE, ORGANIZATION, DEPARTMENT, MANAGERID, MANAGER, TITLE, EMPLOYEENUMBER, HIREDATE, TERMINATIONDATE, PASSWORD_HASH, IS_ACTIVE FROM USERS WHERE IS_ACTIVE = 1

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL GET_ACTIVEUSERS()

• User ID Column: USER_ID

2. Get All Entitlements

#

Import all available entitlements from the database.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  SELECT ENT_ID, ENT_NAME, ENT_DESCRIPTION FROM ENTITLEMENTS

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL GET_ALL_ENTITLEMENTS()

• Entitlement ID Column: ENT_ID

• Entitlement Display Column: ENT_NAME

3. Get User by ID

#

Retrieve specific user details by their USER_ID.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  SELECT USER_ID, USERNAME, FIRSTNAME, LASTNAME, MIDDLENAME, EMAIL, DISPLAYNAME, NICKNAME, MOBILEPHONE, STREETADDRESS, CITY, STATE, ZIPCODE, COUNTRYCODE, TIMEZONE, ORGANIZATION, DEPARTMENT, MANAGERID, MANAGER, TITLE, EMPLOYEENUMBER, HIREDATE, TERMINATIONDATE, PASSWORD_HASH, IS_ACTIVE FROM USERS WHERE USER_ID = ?

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL GET_USER_BY_ID(?)

• Map Parameters to Fields:

  • Parameter 1: DATABASE_FIELD → USER_ID

4. Get User Entitlements

#

Retrieve all entitlements assigned to a specific user.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  SELECT UE.USERENTITLEMENT_ID, UE.USER_ID, U.USERNAME, U.EMAIL, UE.ENT_ID, E.ENT_NAME, E.ENT_DESCRIPTION, UE.ASSIGNEDDATE
  FROM USERENTITLEMENTS UE
  JOIN USERS U ON UE.USER_ID = U.USER_ID
  JOIN ENTITLEMENTS E ON UE.ENT_ID = E.ENT_ID
  WHERE UE.USER_ID = ?

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL GET_USER_ENTITLEMENT(?)

• Map Parameters to Fields:

  • Parameter 1: DATABASE_FIELD → USER_ID

Configure Provisioning Operations (To App)

#

Provisioning operations push changes from Okta to the database.

Navigate to Provisioning Settings

#

1. Stay in the Provisioning tab
2. Go to Integration → To App
3. Click Edit next to Provisioning

5. Create User

#

Create a new user in the database when assigned in Okta.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  INSERT INTO USERS (USER_ID, USERNAME, FIRSTNAME, LASTNAME, EMAIL, MIDDLENAME, DISPLAYNAME, NICKNAME, MOBILEPHONE, STREETADDRESS, CITY, STATE, ZIPCODE, COUNTRYCODE, TIMEZONE, ORGANIZATION, DEPARTMENT, MANAGERID, MANAGER, TITLE, EMPLOYEENUMBER, HIREDATE, TERMINATIONDATE, PASSWORD_HASH)
  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL CREATE_USER(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)

• Map Parameters to Fields:

  • Parameter 1: DATABASE_FIELD → USER_ID (required)
  • Parameter 2: DATABASE_FIELD → USERNAME (required)
  • Parameter 3: DATABASE_FIELD → FIRSTNAME (required)
  • Parameter 4: DATABASE_FIELD → LASTNAME (required)
  • Parameter 5: DATABASE_FIELD → EMAIL (required)
  • Parameter 6: DATABASE_FIELD → MIDDLENAME
  • Parameter 7: DATABASE_FIELD → DISPLAYNAME
  • Parameter 8: DATABASE_FIELD → NICKNAME
  • Parameter 9: DATABASE_FIELD → MOBILEPHONE
  • Parameter 10: DATABASE_FIELD → STREETADDRESS
  • Parameter 11: DATABASE_FIELD → CITY
  • Parameter 12: DATABASE_FIELD → STATE
  • Parameter 13: DATABASE_FIELD → ZIPCODE
  • Parameter 14: DATABASE_FIELD → COUNTRYCODE
  • Parameter 15: DATABASE_FIELD → TIMEZONE
  • Parameter 16: DATABASE_FIELD → ORGANIZATION
  • Parameter 17: DATABASE_FIELD → DEPARTMENT
  • Parameter 18: DATABASE_FIELD → MANAGERID
  • Parameter 19: DATABASE_FIELD → MANAGER
  • Parameter 20: DATABASE_FIELD → TITLE
  • Parameter 21: DATABASE_FIELD → EMPLOYEENUMBER
  • Parameter 22: DATABASE_FIELD → HIREDATE
  • Parameter 23: DATABASE_FIELD → TERMINATIONDATE
  • Parameter 24: DATABASE_FIELD → PASSWORD_HASH

6. Update User

#

Update existing user attributes in the database.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  UPDATE USERS
  SET USERNAME = ?, FIRSTNAME = ?, LASTNAME = ?, EMAIL = ?, MIDDLENAME = ?, DISPLAYNAME = ?, NICKNAME = ?, MOBILEPHONE = ?, STREETADDRESS = ?, CITY = ?, STATE = ?, ZIPCODE = ?, COUNTRYCODE = ?, TIMEZONE = ?, ORGANIZATION = ?, DEPARTMENT = ?, MANAGERID = ?, MANAGER = ?, TITLE = ?, EMPLOYEENUMBER = ?, HIREDATE = ?, TERMINATIONDATE = ?, PASSWORD_HASH = ?
  WHERE USER_ID = ?

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL UPDATE_USER(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)

• Map Parameters to Fields:

  • Parameter 1: DATABASE_FIELD → USER_ID (required)
  • Parameter 2: DATABASE_FIELD → USERNAME (required)
  • Parameter 3: DATABASE_FIELD → FIRSTNAME (required)
  • Parameter 4: DATABASE_FIELD → LASTNAME (required)
  • Parameter 5: DATABASE_FIELD → EMAIL (required)
  • Parameter 6: DATABASE_FIELD → MIDDLENAME
  • Parameter 7: DATABASE_FIELD → DISPLAYNAME
  • Parameter 8: DATABASE_FIELD → NICKNAME
  • Parameter 9: DATABASE_FIELD → MOBILEPHONE
  • Parameter 10: DATABASE_FIELD → STREETADDRESS
  • Parameter 11: DATABASE_FIELD → CITY
  • Parameter 12: DATABASE_FIELD → STATE
  • Parameter 13: DATABASE_FIELD → ZIPCODE
  • Parameter 14: DATABASE_FIELD → COUNTRYCODE
  • Parameter 15: DATABASE_FIELD → TIMEZONE
  • Parameter 16: DATABASE_FIELD → ORGANIZATION
  • Parameter 17: DATABASE_FIELD → DEPARTMENT
  • Parameter 18: DATABASE_FIELD → MANAGERID
  • Parameter 19: DATABASE_FIELD → MANAGER
  • Parameter 20: DATABASE_FIELD → TITLE
  • Parameter 21: DATABASE_FIELD → EMPLOYEENUMBER
  • Parameter 22: DATABASE_FIELD → HIREDATE
  • Parameter 23: DATABASE_FIELD → TERMINATIONDATE
  • Parameter 24: DATABASE_FIELD → PASSWORD_HASH

7. Activate User

#

Activate a user account.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  UPDATE USERS SET IS_ACTIVE = 1 WHERE USER_ID = ?

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL ACTIVATE_USER(?)

• Map Parameters to Fields:

  • Parameter 1: DATABASE_FIELD → USER_ID

8. Deactivate User

#

Deactivate a user account.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  UPDATE USERS SET IS_ACTIVE = 0 WHERE USER_ID = ?

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL DEACTIVATE_USER(?)

• Map Parameters to Fields:

  • Parameter 1: DATABASE_FIELD → USER_ID

9. Add Entitlement to User

#

Assign an entitlement to a user.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  INSERT INTO USERENTITLEMENTS (USER_ID, ENT_ID) VALUES (?, ?)

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL ADD_ENTITLEMENT_TO_USER(?, ?)

• Map Parameters to Fields:

  • Parameter 1: DATABASE_FIELD → USER_ID
  • Parameter 2: DATABASE_FIELD → ENT_ID

10. Remove Entitlement from User

#

Revoke an entitlement from a user.

Configuration:

• ✅ Check Enabled

• Option 1 - Select SQL Statement, and enter the SQL query:

  DELETE FROM USERENTITLEMENTS WHERE USER_ID = ? AND ENT_ID = ?

• Option 2 - Select Stored Procedure (Recommended), and enter the stored procedure call:

  CALL REMOVE_ENTITLEMENT_FROM_USER(?, ?)

• Map Parameters to Fields:

  • Parameter 1: DATABASE_FIELD → USER_ID
  • Parameter 2: DATABASE_FIELD → ENT_ID

Configure User Profile Attributes

#

Before enabling provisioning features, you need to configure attribute mappings between Okta and the database.

1. Navigate to Profile Editor

   • In Okta Admin Console, go to Directory → Profile Editor

2. Select Generic Database Connector User Profile

   • Search for “Generic Database Connector”
   • Individuate the profile named “Generic Database Connector User” and click Mappings.

   

3. Add Attributes from Database

   • Under Attributes, you’ll see that only the Username attribute is present
   • Click + Add Attribute

   

4. Import Database Attributes

   • The next page displays all attributes imported from the database
   • Check all the required attributes:
     • ext_USER_ID
     • ext_FIRSTNAME
     • ext_LASTNAME
     • ext_EMAIL
     • ext_MANAGER
     • ext_TITLE
     • And any other custom attributes (you can click the first checkbox to select all)
     • You can click the first box at the top to select all
   • Click Save

   

5. Verify Attributes

   • The Generic Database Connector user profile now contains all attributes needed for provisioning operations

Generic Database Connector User to Okta User

#

This mapping governs how user accounts from the database are imported into Okta.

Configuration Steps:

1. Navigate to Mappings

   • Within the Generic Database Connector User profile, click Mappings

     

2. Configure Import Mappings

   • By default, Generic Database Connector User to Okta User is selected
   • You’ll see that mapping for login is present, but others are empty
   • Set up mappings for additional attributes as needed

3. Map Attributes

   • Under Okta User Profile, click the dropdown in Choose an attribute or enter an expression
   • Select the corresponding attribute from Generic Database Connector User Profile

   Example mappings:

   • appuser.ext_FIRSTNAME → firstName
   • appuser.ext_LASTNAME → lastName
   • appuser.ext_EMAIL → email
   • appuser.ext_TITLE → title
   • appuser.ext_MANAGER → managerId

   

4. Save Mappings

   • Click Save
   • Click Apply updates

Okta User to Generic Database Connector User

#

This mapping dictates how user attributes in Okta correlate with the database user profile, facilitating user creation or modification in the database.

Configuration Steps:

1. Navigate to Mappings

   • Within the Generic Database Connector User profile, click Mappings

2. Select Okta User to Generic Database Connector User

   • Click Okta User to Generic Database Connector User

   

3. Map Attributes

   • Click the dropdown under Choose an attribute or enter an expression
   • Select the appropriate attributes from Okta User Profile

   Example mappings:

   • login → ext_USER_ID
   • login → ext_USERNAME
   • firstName → ext_FIRSTNAME
   • lastName → ext_LASTNAME
   • email → ext_EMAIL
   • managerId → ext_MANAGER
   • title → ext_TITLE

   

4. Save Mappings

   • Click Save Mappings

Enable Provisioning Features

#

1. Navigate to Provisioning Settings

   • In Okta Admin Console, go to Applications → Generic Database Connector
   • Click the Provisioning tab
   • Navigate to Settings → To App

2. Edit Provisioning Settings

   • Click Edit in the Provisioning to App section

3. Enable Provisioning Features

   • ✅ Create Users: Enable to create users in the database when assigned in Okta
   • ✅ Update User Attributes: Enable to sync attribute changes from Okta to database
   • ✅ Deactivate Users: Enable to deactivate users in database when unassigned from Okta

4. Save Configuration

   • Click Save

Configure Import Schedule

#

1. Navigate to Import Settings

   • Go to Applications → Generic Database Connector
   • Click Provisioning tab
   • Navigate to Settings → To Okta
   • Click Edit next to General

2. Configure Import Schedule

   • Under Full Import Schedule, select the desired frequency for importing users (e.g., every 6 hours)
   • Do not configure Incremental Import Schedule as the database does not have a timestamp field to track changes

3. Configure Okta Username Format

   • Under Okta username format, select Custom from the dropdown
   • Enter: appuser.ext_EMAIL in the textbox
   • This ensures usernames are in email format using the appuser.ext_USERNAME attribute

4. Save Configuration

   • Click Save

Testing the Integration

#

With configuration complete, it’s time to test the full integration workflow.

Test #1: Import Users from Database

#

This test imports existing database users into Okta.

1. Navigate to Import Tab

   • Go to Applications → Generic Database Connector
   • Click the Import tab

2. Start Import

   • Click Import Now
   • Select Full Import
   • Click Import

   

3. Review Import Results

   • Once import completes, you’ll see an Import Success message
   • Review the list of users imported from the database

   

4. Confirm User Assignments

   • By default, imported users require manual confirmation (configurable in Provisioning → To Okta → User Creation & Matching)
   • Select the users you want to import into Okta
   • Click Confirm Assignments
   • Select Auto-activate users after confirmation
   • Click Confirm when prompted

   

5. Verify Imported Users

   • Navigate to the Assignments tab
   • Verify that imported users are now visible

   

6. Check Entitlements

   • Click the Governance tab
   • Click Entitlements
   • Verify that the entitlements from the database are listed in Okta

   

   • Notes:
     • At the moment only the Display Name and Value Name of the entitlement are supported. The Description is not yet included in the list
     • To define the Governance Label refer to the Okta documentation for Resource labels
     • Despite other application integrated with the Okta Governance, at the moment the Database Connector support only one entitlement type per each application instance.

7. Check user entitlements

   • Click on the three dots next to the user you just imported in the Assignments tab

   • Click View access details

     

   • Verify that the entitlements assigned to the user in the database are reflected in Okta

     

Test #2: Manual User Assignment and Provisioning

#

Test creating a new user in the database from Okta.

Steps:

1. Assign User to Application

   • Log on to Okta Admin Console
   • Navigate to Applications → Generic Database Connector
   • Click the Assignments tab
   • Click Assign → Assign to People

2. Select User

   • Search for a user (e.g., testuser@example.com)
   • Click Assign next to the user

3. Review User Details

   • The application auto-populates custom attribute values based on your mappings
   • Review and adjust values as needed - Empty fields can be manually entered
   • Click Assign and Continue

   

4. Assign Entitlements

   • In the Select Assignment section, select Custom Values from the Entitlement assignment method dropdown
   • Under Entitlements, select desired entitlements (e.g., “VPN Access”, “GitHub Admin”)
   • Click Save

   

5. Verify in Okta

   • The user should now appear under the Assignments tab
   • Click the menu button (three vertical dots) next to the user
   • Select View access details to see assigned entitlements

6. Verify in Database

   • Check that the user was created in the database:

     docker compose exec db mariadb -u oktademo -poktademo oktademo -e "SELECT USER_ID,USERNAME,FIRSTNAME,LASTNAME,EMAIL FROM USERS WHERE EMAIL='testuser@example.com';"
     
     # SAMPLE OUTPUT
     #  +----------------------+-----------+-----------+----------+----------------------+
     # | USER_ID              | USERNAME  | FIRSTNAME | LASTNAME | EMAIL                |
     # +----------------------+-----------+-----------+----------+----------------------+
     # | testuser@example.com | test.user | Test      | User     | testuser@example.com |
     # +----------------------+-----------+-----------+----------+----------------------+

     You can also verify with DBGate UI, by opening the USERS table.

     

7. Verify Entitlements in Database

   • Check that entitlements were assigned:

     docker compose exec db mariadb -u oktademo -poktademo oktademo -e "CALL GET_USER_ENTITLEMENT('testuser@example.com');"

     You can also verify with DBGate UI, by opening the USERENTITLEMENTS table or the v_userentitlements view.

     

Test #3: User Attribute Update

#

Test that attribute changes in Okta are synchronized to the database.

Steps:

1. Update User in Okta

   • Navigate to Directory → People
   • Find and select a user (e.g., testuser@example.com)
   • Click Profile → Edit
   • Change an attribute (e.g., title, department)
   • Click Save

2. Verify in Database

   • Check that changes were synced:

     docker compose exec db mariadb -u oktademo -poktademo oktademo \
       -e "SELECT USER_ID, TITLE, DEPARTMENT, EMAIL FROM USERS WHERE EMAIL='testuser@example.com';"

     You can also verify with DBGate UI, by opening the USERS table.

Test #4: User Deactivation

#

Test that unassigning a user from the application deactivates them in the database.

Steps:

1. Unassign User

   • Navigate to Applications → Generic Database Connector → Assignments
   • Find the user and click the menu button
   • Select Unassign
   • Confirm the action

2. Verify Deactivation in Database

   • Check that the user’s IS_ACTIVE flag is set to 0:

     docker compose exec db mariadb -u oktademo -poktademo oktademo \
       -e "SELECT USER_ID, EMAIL, IS_ACTIVE FROM USERS WHERE EMAIL='testuser@example.com';"

     You can also verify with DBGate UI, by opening the USERS table or the v_inactive_users view.

Test #5: Check Okta and Local Logs

#

To better understand the process and the link between all the components, you can also check the Okta and local logs.

Okta Logs

#

You can check the Okta System Logs to see the events related to user provisioning and entitlement management. Look for events such as:

1. User’s entitlements updated successfully (resource.user_entitlements.update): This event indicates that a user’s entitlements were updated in Okta, which should trigger the provisioning flow to sync changes to the database.
2. Push new user to external application (application.provision.user.push): This event indicates that Okta is attempting to provision a new user to the database via the OPP Agent.
3. Successfully pushed new user account to app" (app.user_management.push_new_user_success): This event confirms that the user account was successfully created in the database, and the entitlements were assigned.
4. Sync user in external application (application.provision.user.sync): This event indicates that Okta is attempting to sync user changes to the database, which can be triggered by attribute updates or entitlement changes.

Even if they aren’t verbose, these logs can help you understand when provisioning actions are triggered and if they succeed or fail. And you can use them to get the timestamp of an event and correlate it with the OPP Agent and SCIM server logs.

OPP Agent Logs

#

You will find the OPP Agent logs mounted in the local folder ./data/okta-opp/logs/*.log

SCIM Server Logs

#

You will find the SCIM server logs mounted in the local folder ./data/okta-scim/logs/*.log

Beyond Basic Provisioning: Identity Governance

#

Once you have the Generic Database Connector operational, you can explore advanced identity governance use cases:

• Entitlements Policies: Define policies in Okta to govern how entitlements are assigned based on user attributes (e.g., department, location). Documentation: Okta Help - Create an Entitlement Policy.

• Access Requests: Use Okta’s Access Request feature to allow users to request entitlements, with approval workflows and automated provisioning. Documentation: Okta Help - Access Requests.

• Access Certification Campaigns: Implement one time or periodic access reviews for entitlements to ensure compliance and recertification. Documentation: Okta Help - Access Certification.

These governance features transform the Generic Database Connector from a simple provisioning tool into a comprehensive identity governance solution.

Production Considerations

#

Deployment Architecture Options

#

When deploying to production, you have flexibility in how to architect your environment:

Single Server Deployment

#

• Install both OPP Agent and SCIM Server on the same host
• Simpler infrastructure and management
• Lower operational costs
• Adequate security for most use cases
• The OPP Agent communicates with SCIM Server via localhost
• This is the most common production deployment model

Multi-Server Deployment

#

• Install OPP Agent and SCIM Server on separate hosts
• Enhanced security through physical/virtual separation
• Ability to scale components independently
• Useful for high-availability configurations
• May be required for specific compliance requirements

Using Different Databases

#

To use PostgreSQL instead of MariaDB:

1. Update docker-compose.yml:

   db:
     image: postgres:16 # Use official PostgreSQL image
     # Update environment variables accordingly

2. Change sql mountpoint to load appropriate initialization scripts for PostgreSQL

3. Place appropriate JDBC driver in ./docker/okta-scim/packages/:

Other JDBC Drivers

#

For other databases (Oracle, SQL Server, etc.):

1. Download appropriate JDBC driver
2. Place .jar file in ./docker/okta-scim/packages/
3. Rebuild the container: make rebuild
4. Configure SCIM Server with database-specific connection string

Note: MySQL Connector/J 9.6.0 is automatically downloaded from Maven Central during build. All .jar files in ./docker/okta-scim/packages/ are copied to /opt/OktaOnPremScimServer/userlib/ during container build.

Connecting to Multiple Databases

#

A single OPP Agent and SCIM Server deployment can manage up to 8 databases simultaneously:

• Each database requires a separate Generic Database Connector application instance in Okta
• All databases can be different types (e.g., MySQL, PostgreSQL, Oracle, SQL Server)
• Useful for managing users across multiple applications, environments (prod/staging), or organizational units
• All JDBC drivers must be present in ./docker/okta-scim/packages/ before building the container or in /opt/OktaOnPremScimServer/userlib/ if you are not using this Docker setup.

For detailed configuration instructions, see doc/Okta_Provisioning_Configuration.md.

Production Best Practices

#

When moving from lab to production:

Security:

• Use strong, unique passwords (never use defaults like oktademo)
• Implement proper SSL/TLS certificates (not self-signed)
• Create dedicated service accounts with minimal permissions
• Use firewall rules to restrict database access
• Regularly rotate bearer tokens and credentials

High Availability (when it will be available):

• Deploy at least two OPP Agents for redundancy and failover
• Enable automatic agent updates (requires multiple agents)
• Implement database replication/clustering
• Configure health monitoring and alerting

Performance:

• Tune SCIM Server connection pool settings
• Optimize stored procedures and add appropriate indexes
• Configure OPP Agent threading parameters (pollingThreadCount, maxConnectionsPerHost)
• Monitor query performance and connection pool usage

Monitoring:

• Enable appropriate logging levels (i.e., INFO for production, DEBUG for troubleshooting)
• Set up centralized log aggregation
• Monitor Okta System Logs for provisioning events
• Create alerts for authentication failures and errors
• Track provisioning success/failure rates

Troubleshooting Common Issues

#

Here are the most common issues you might encounter:

ValidationException: executeCall not allowed / execute not allowed

#

If you see this error:

Error code: 400, error: . Errors received from SCIM server by the connector :
{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"scimType":"INVALID_SYNTAX",
"detail":"statement=CALL ACTIVATE_USER(?), errors=[ValidationException: executeCall not allowed.,
ValidationException: execute not allowed.]","status":400}

The operation is configured as “SQL Statement” instead of “Execute Stored Procedure”.

1. Go to Okta Admin Console → Applications → Generic Database Connector
2. Navigate to the Provisioning tab → To App / To Okta → Edit
3. For each operation that calls a stored procedure, ensure Operation Type is set to “Execute Stored Procedure” (NOT “SQL Statement”)

Stored Procedure Not Found

#

• Verify procedures are installed: docker compose exec db mariadb -u oktademo -poktademo oktademo -e "SHOW PROCEDURE STATUS WHERE Db='oktademo';"
• Reinitialize database if needed (see README.md)

Parameter Mismatch

#

• Ensure parameter count matches the stored procedure definition
• Check parameter types (DATABASE_FIELD, CURSOR, etc.)
• Review sql/stored_proc.sql for exact signatures

Connection Timeout

#

• Verify SCIM server is running: docker compose ps okta-scim
• Check database connectivity: docker compose exec okta-scim mysql -h db -u oktademo -poktademo oktademo -e "SELECT 1;"

Entitlement Operations Failing

#

• Verify ENT_ID exists: SELECT * FROM ENTITLEMENTS;
• Check foreign key constraints
• Review USERENTITLEMENTS table structure

Advanced Troubleshooting

#

The GitHub repository README contains comprehensive troubleshooting documentation including:

• Build errors with SSL certificate issues
• Database query logging (enable/disable/monitor)
• Agent and SCIM server log analysis
• Certificate warnings and VPN configurations
• Performance monitoring and optimization

For detailed troubleshooting steps, debug mode configuration, and performance tuning, refer to the complete troubleshooting guide in the repository.

For deep technical insights into the SCIM Server’s internal architecture and API endpoints, see the SCIM Server Technical Deep Dive article.

Conclusion

#

This comprehensive guide has walked you through deploying a complete Okta database provisioning solution, from initial Docker setup to advanced testing workflows. You now have a fully functional environment that demonstrates:

• Secure Bridge Architecture: How the OPP Agent and SCIM Server connect Okta cloud to on-premises databases without inbound firewall rules
• User Lifecycle Management: Automated create, update, activate, and deactivate operations
• Entitlement Management: Sophisticated role and permission assignment through database-backed entitlements
• Stored Procedure Abstraction: Clean, secure, and maintainable provisioning logic
• Real-time Synchronization: Bidirectional data flow between Okta and your database

Whether you’re evaluating Okta for a database provisioning use case, building a proof of concept, or learning the integration workflow, this lab environment provides a solid foundation. The Docker-based approach accelerates setup and experimentation, while the configuration steps apply equally to manual installations on production systems.

Remember that while Docker simplifies the learning process, production deployments should follow official Okta documentation and best practices for supported operating systems, security hardening, and high availability.

Next Steps

#

• Explore Advanced Features: Test access requests, entitlement policies, and certification campaigns
• Customize for Your Use Case: Adapt the stored procedures and schema to match your application’s data model
• Scale the Environment: Add multiple databases or integrate with other on-premises applications
• Plan Production Deployment: Review the architecture options and production considerations for your organization

Questions or feedback?

#

• Leave a comment to this article
• Contribute to the GitHub repository
• Follow me on LinkedIn for updates on Okta and identity management topics
• Explore the additional documentation:

Technical Documentation

#

• Okta Provisioning Configuration Guide - Step-by-step Okta Admin Console setup instructions
• Okta SCIM Server Technical Documentation - Advanced technical reference for the SCIM Server’s internal architecture, API endpoints, and troubleshooting (reverse-engineered, educational purposes only)
• Okta On-Prem SCIM Server: Technical Deep Dive and Architecture - Comprehensive exploration of SCIM Server internals, REST endpoints, authentication mechanisms, and multi-tenancy support

Official Documentation

#

• On-premises Connector for Generic Databases
• Install the Okta Provisioning Agent
• Install the Okta On-prem SCIM Server

SCIM Protocol

#

• SCIM 2.0 RFC 7644
• Okta SCIM Documentation

Okta Community

#

• Okta Developer Forums
• Okta Community

Disclaimer

#

This is a demonstration laboratory environment designed for testing, learning, and demonstration purposes. It is not officially supported by Okta for production use.

Securing Your Business-Critical Platforms

#

Recently, while working with a prospect, a common but critical challenge came up: how to integrate their IBM i (AS/400) platform with Okta. Their top priority was to enforce modern Multi-Factor Authentication (MFA) to protect all access points, especially the 5250 “green screen” terminals that are central to their operations. This inquiry inspired me to do a deep-dive and outline the available strategies, which I’ll share in this post.

For decades, IBM i systems have been the silent workhorses powering core business operations for companies worldwide. While these platforms are renowned for their reliability and security, the broader security landscape has evolved dramatically. Today, protecting the invaluable data on these systems requires a modern, identity-first security approach.

Integrating a centralized Identity Provider (IdP) like Okta is crucial. It allows you to enforce consistent security policies, streamline user access, and gain visibility across your entire technology stack—from the newest cloud applications to your foundational IBM i platforms. This article explores how you can extend Okta’s powerful MFA and Lifecycle Management (LCM) capabilities to your IBM i environment.

Protecting the Terminal with MFA

#

Protecting access to modern web-based applications with Okta is straightforward using standard protocols like SAML and OIDC. However, securing terminal access to IBM i systems, which rely on protocols like 5250, FTP, and Telnet, presents a unique challenge. These protocols lack the browser-based interaction needed for many modern MFA flows.

While web-based terminal emulators like Flynet Viewer™ or z/Scope Anywhere can be protected at the web application layer, securing native “green screen” terminal access requires a different approach.

The Precisely Assure Security Solution

#

This is where a third-party solution like Precisely’s Assure Security comes into play. It acts as a bridge between the IBM i sign-on process and Okta. The integration works by intercepting the user login attempt on the IBM i system and using the Okta RADIUS Server Agent to trigger an MFA challenge.

The flow is as follows:

1. A user attempts to log in to the IBM i system via a 5250 terminal.
2. Precisely Assure Security, installed on the IBM i, intercepts the login.
3. It sends a RADIUS authentication request to the Okta RADIUS Agent.
4. The Okta RADIUS Agent communicates with the Okta cloud service to evaluate sign-on policies.
5. Okta pushes an MFA challenge (e.g., Okta Verify Push, OTP) to the user’s device.
6. The user approves the challenge.
7. Okta sends an “Access-Accept” response back through the RADIUS agent to the Precisely solution.
8. The user is granted access to the IBM i terminal.

sequenceDiagram
    actor User
    participant Terminal as 5250 Terminal
    participant IBMi as IBM i / Precisely
    participant RadiusAgent as Okta RADIUS Agent
    participant Okta as Okta Cloud

    User->>Terminal: 1. Enter Credentials
    Terminal->>IBMi: 2. Submit Login Request
    IBMi->>IBMi: 3. Precisely Intercepts Login
    IBMi->>RadiusAgent: 4. RADIUS Access-Request
    RadiusAgent->>Okta: 5. Forward Auth Request
    Okta-->>User: 6. Push MFA Challenge
    User-->>Okta: 7. Approve MFA
    Okta-->>RadiusAgent: 8. RADIUS Access-Accept
    RadiusAgent-->>IBMi: 9. Forward Access-Accept
    IBMi-->>Terminal: 10. Grant Access

How Precisely Intercepts the Login Process

#

A key strength of the Precisely solution is its ability to integrate without requiring any changes to your existing IBM i applications or the operating system’s core sign-on programs.

• Non-Invasive Interception: Precisely Assure Security uses IBM i’s native “Exit Point” architecture. Exit points are essentially hooks provided by the operating system that allow a third-party program to be called before or after a specific system event—in this case, the sign-on event. When a user attempts to log in, the exit point program intercepts the request and redirects it to the Assure Security engine for MFA validation before the operating system processes the password. This is seamless to the end-user and requires no modification of legacy code.

• Rules-Based Step-Up MFA: Security shouldn’t be all-or-nothing. Precisely’s official documentation highlights its ability to “invoke rules-based multi-factor authentication only for users or specific situations that require it”. This granular control ensures that you can strengthen security where it matters most without adding unnecessary friction to all user logins. This means you can implement intelligent, risk-based MFA. For example, you can configure rules to:

  • Always require MFA for powerful “privileged user” profiles.
  • Only trigger an MFA challenge when a standard user attempts to access a highly sensitive application or execute a specific, powerful command.
  • Bypass MFA for low-risk users or during certain times of the day.

Configuration Example

#

Configuring the Precisely solution involves registering the Okta RADIUS server within the Assure MFA administration menu on the IBM i. This screen requires key details to establish a secure connection.

The key fields for configuration are:

• Priority: Determines the order of servers for high availability.
• Server: The hostname or IP address of your Okta RADIUS Agent.
• Port: The UDP port for RADIUS communication, typically 1812.
• Description: A friendly name for the server entry.
• Held: Must be set to N (No) for the server to be active.
• Server Secret: The shared secret key configured in the Okta RADIUS App.
• Dead Time: A timeout value before considering a server non-responsive.

Following are some screenshots illustrating the configuration process:

Limitations of the RADIUS Protocol

#

While RADIUS is a powerful and universal protocol, it has limitations in the context of modern authentication:

• No Browser-Based Flows: Since terminal access is not browser-based, you cannot leverage phishing-resistant authenticators like FIDO2/WebAuthn or experience frictionless authentication like Okta FastPass.
• Limited User Experience: The MFA interaction is typically limited to push notifications or entering a one-time passcode. Richer interactions, like number challenges in Okta Verify, are not supported.

Despite these limitations, using RADIUS is a highly effective and widely adopted method for adding a critical layer of security to non-web systems.

Alternatives

#

Precisely Assure Security is not the only solution available for integrating Okta MFA with IBM i systems. While during my test with Precisely I found the setup straightforward and well-documented, other vendors can be considered. For example:

• Raz-Lee iSecurity Multi Factor Authentication
• Midland IBM i Security Access Controls

While I have not personally tested these alternatives, they may offer similar capabilities for integrating Okta MFA via RADIUS or other methods. When evaluating options, consider factors such as ease of integration, support for your specific IBM i version, and the ability to implement rules-based MFA.

Lifecycle Management (LCM)

#

Beyond authentication, managing the JML (Joiner, Mover, Leaver) user lifecycle on IBM i systems is critical for security and operational efficiency. Automating provisioning and de-provisioning ensures that access is granted promptly and, more importantly, revoked immediately when a user leaves the organization.

Okta’s standard for automation is the System for Cross-domain Identity Management (SCIM) protocol. However, IBM i does not natively support SCIM. To bridge this gap, there are two primary approaches.

Option 1: Okta On-Premises Provisioning (OPP) Agent with Custom Scripts

#

For organizations willing to handle this completely autonomously, the Okta On-Premises Provisioning (OPP) Agent offers a flexible, custom-tailored solution.

How it works:

1. You install the lightweight OPP agent on a Linux or Windows server in your network.
2. You build a custom SCIM connector, which consists of a set of PowerShell scripts that the agent executes.
3. These scripts are responsible for translating Okta’s SCIM commands (like CreateUser, UpdateUser, DeactivateUser) into native IBM i commands. This could involve using scripts (such as PowerShell, Bash, Python, etc.) to make SSH connections to the IBM i and run CL (Control Language) commands, or calling specific APIs if available.

Option 2: A SaaS-Based SCIM Gateway like Aquera

#

For a faster, out-of-the-box solution, you can use a third-party SCIM gateway like Aquera.

How it works: Aquera is a SaaS platform that specializes in connecting IdPs like Okta to applications and systems that don’t support modern protocols. It acts as a managed SCIM translator:

1. Okta communicates with the Aquera platform via a standard SCIM connection.
2. Aquera translates Okta’s SCIM commands into the native APIs and commands that the IBM i system understands.
3. The result is a seamless, pre-built integration that enables full lifecycle management without the need for custom development.

This approach significantly reduces implementation time and effort, making it ideal for organizations that prefer a managed solution.

Entitlements and Governance

#

Regardless of the approach you choose, a robust LCM integration extends to managing entitlements. By mapping Okta groups to specific roles or profiles on the IBM i, you can automate access to necessary libraries, objects, and functions.

This integration is a cornerstone of modern identity governance. With a solution like Okta Identity Governance (OIG), you can run access certification campaigns where reviewers can approve or revoke access to IBM i resources directly from the Okta interface, creating a complete and auditable governance trail.

Aquera support automatically the entitlements management as part of their SCIM gateway offering. While with OPP, you need to build the logic to handle entitlements in your custom scripts.

Option 3: Provisioning via the Okta LDAP Agent

#

For organizations that want to leverage existing LDAP infrastructure, there is a third, more theoretical path for provisioning: using the Okta LDAP Agent. This approach is possible because IBM i includes a built-in Directory Server that can be configured to expose its native user database (*USRPRF) as an LDAP directory.

However, this method comes with significant caveats and complexities that make it less common in practice.

How it Works

#

The conceptual flow is as follows:

1. Okta Trigger: A user is assigned the IBM i group in Okta.
2. LDAP Agent: The Okta LDAP Agent, installed on a server in your network, receives the provisioning command from the Okta cloud service.
3. LDAP Provisioning: The agent sends standard LDAP commands (e.g., add, modify) to the IBM i Directory Server endpoint.
4. IBM i Backend: The IBM i system, through its directory server, interprets the LDAP command and creates a corresponding user profile on the system.

The Challenge: Rich Profiles vs. Basic LDAP

#

You might think that since Okta allows for custom LDAP attribute mapping, you could simply extend the schema to manage all the necessary IBM i settings. However, the limitations are not about mapping attributes, but about the fundamental nature of the operations required to manage a true IBM i User Profile.

The Okta LDAP Agent is designed to manage standard LDAP attributes like uid, cn, and userPassword. While it can successfully create a basic user on the IBM i, a native User Profile (*USRPRF) requires a rich set of specific security parameters that have no equivalent in a standard LDAP schema.

These critical attributes, which the LDAP agent cannot manage out-of-the-box, include:

• Special Authorities: Permissions like *ALLOBJ (all object access) or *SECADM (security administrator)
• Initial Program/Menu: The first screen a user sees after logging in
• Library List: The specific libraries and data a user can access
• Job Description: Defines how batch jobs are run under the user’s profile
• Object Ownership and countless other security-relevant settings

To bridge this gap, you would need to supplement the LDAP provisioning with custom Control Language (CL) scripts on the IBM i host. These scripts would need to be triggered after the user is created via LDAP to apply the necessary security settings, turning this into a complex, hybrid solution that requires significant custom development and maintenance, much like the custom scripting required for the OPP agent in Option 1.

In essence, while the LDAP agent can create a basic user “shell,” it cannot safely manage the rich security context of a true IBM i User Profile. The extensive custom scripting and backend logic required to overcome these limitations ultimately make this approach as complex as using the Okta OPP Agent (Option 1), but with significantly higher risk and no official support.

Conclusions

#

Your IBM i systems are too critical to be left out of your modern identity security strategy. While they may not speak the same language as your cloud applications, proven solutions exist to bridge the gap.

By leveraging Precisely Assure Security with the Okta RADIUS Agent, you can extend strong Multi-Factor Authentication to every corner of your IBM i environment. For lifecycle management, you have the flexibility to either build a custom solution with the Okta OPP Agent or accelerate your deployment with a pre-built SCIM gateway like Aquera.

Integrating these foundational platforms with Okta not only modernizes their security but also provides a unified, consistent, and auditable identity fabric across your entire organization.

What’s your experience with IBM i security and identity management? Have you integrated your legacy systems with modern IAM platforms? Share your thoughts, questions, or feedback in the comments below! 👇

Intro

#

GLPI is an open-source service management software made in France and is used by a lot of companies in EMEA.

I worked with a customer for the integration with Okta. Here are some notes and the instructions for running a test environment with docker.

Note: since it’s very easy to run GLPI with docker-compose and configure it with LDAP and/or SAML, it can be a good solution for a demo environment when you have to demonstrate the typical user experience with an LDAP (or SAML) integration.

Run a test environment with Docker Compose

#

There is an official docker image that permits running GLPI very quickly in docker or docker-compose.

I used it as a base, and builded a custom Docker Compose file to run it along with MariaDB, Mailpit (for email testing) and DBGate (a web-based database management tool).

The source code is available on the following GitHub repository: fabiograsso/okta-lab-glpi11.

To run it, just clone the repo, edit the .env file, and execute make start:

git clone https://github.com/fabiograsso/okta-lab-glpi11
cd okta-lab-glpi11
cp .env.example .env
# (edit .env if needed)
make start

It exposes GLPI on port 80 in localhost, so you can open it using http://localhost

Once started, here are the default users for login in GLPI:

You will find two new folders:

./data/mysql contains the database, in order to make it persistent when you restart the docker image ./data/glpi contains the GLPI web application

Authentication and SSO with Okta

#

To federate it with Okta, there are three options:

1. LDAP Interface
2. SAML using an open-source plugin called ‘phpsaml’
3. OAuth/OIDC using an official plugin provided by GLPI Network

LDAP Interface

#

1. Go to Home → Setup → Authentication → LDAP directories → Add

   

2. Use the following configuration for Okta LDAP Interface:

   • Server: your_okta_domain.ldap.okta.com
   • Port: 389 (or 636 for LDAPS)
   • Connection Filter: (objectClass=person)
   • BaseDN: dc=your_okta_domain,dc=okta,dc=com (replace with your Okta LDAP Base DN)
   • Use bind: Yes
   • Root DN: cn=your_bind_user,dc=your_okta_domain,dc=okta,dc=com (replace with your Okta LDAP Bind DN)
   • Password: your_bind_user_password
   • Login field: uid

     

3. In the Users tab you can define which user attributes to sync. Additional attributes can be added - based on you needs.

   

4. For the Groups tab the configuration is very simple:

   • Search type: “In Groups”
   • Filter: (objectClass=groupOfUniqueNames)
   • Group attribute: uniquemember
   • Use DN in search: No

     

5. In the Advanced information tab, you can set the following parameters:

   • Use TLS: Yes
   • LDAP Directory time zone: GMT
   • Timeout: 30 - I suggest keeping the timeout as long as possible (the maximum is 30) in order to give to users the time to accept the push notification on the phone (if push MFA is used)

   

6. Once the LDAP is configured, you can import users from the Administration → Users → LDAP directory link.

   

   

   The same can also be done for groups.

7. Then, the LDAP users can log in by selecting the proper login source on the login page (or by keeping the default one if “Default Server: Yes” is configured on the LDAP setting)

   

SAML

#

The LDAP interface is limited in terms of features and user experience. Another option is to use SAML. There is an open-source plugin called samlSSO. The installation is very easy:

1. Download the zip file from Releases · DonutsNL/samlsso
2. Extract and copy in the folder <GLPI_ROOT>/marketplace/samlsso (if using my docker-compose, that’s the folder .data/glpi/marketplace/samlsso)
3. Enable and configure it from the web interface of GLPI (Home → Setup → Plugins)

Alternatively, you can also install it from the GLPI Marketplace, in this case you’ll need to register for a free account.

Configuration - Okta Side

#

On Okta, the configuration is very easy, just a custom SAML application.

• Single sign on URL: http://localhost/plugins/samlsso/front/acs/1
• Audience URI (SP Entity ID): http://localhost/

Configuration - GLPI Side

#

1. Go to Home → Setup → samlSSO → Add

2. In the General tab, use the following configuration:

   • FRIENDLY NAME : Okta
   • LOGIN ICON : fa-solid fa-key (you can choose any icon you want from FontAwesome)
   • USERDOMAIN: leave empty (optionally you can set a domain to force the users on that domain to use SSO)
   • IS ACTIVE: Yes
   • DEBUG: No

     

3. In the Transit tab just keep the default value

   

4. In the Service Provider tab, set the following parameters:

   • NAMEID FORMAT: Unspecified
   • SP CERTIFICATE and PRIVATE KEY: leave empty - optionally you can generate a certificate and use it use Single Logout or to encrypt/sign the SAML requests

     

     You will find also the Entity ID and ACS URL that you have to use in Okta configuration.

   For a simple demo perspective and to make the configuration easier, do not enable Strict and Single logout, so there is no need to generate an SP certificate.

5. In the Identity Provider tab, set the following parameters:

   • ENTITY ID: http://www.okta.com/your_okta_org_id (replace with your Okta Org ID)
   • SSO URL: https://your_okta_domain.okta.com/app/your_app_id/sso/saml (replace with your Okta SAML SSO URL)
   • IDP CERTIFICATE: copy/paste the Okta X.509 certificate here
   • SLO URL: leave empty (unless you want to configure Single Logout)

     

6. Finally, the Security tab permit to change some security options:

   

   For example:

   • JIT USER CREATION : Yes - to create the users on the fly at first login
   • STRICT: Yes - to enforce SAML response validation
   • ENFORCED: No - Unless you want to force all users to use SSO. Otherwise, there is an option “Sign In with SSO” on the login page.

   

OAuth / OIDC / SCIM

#

The last option for federate GLPI is to use OAuth.

There is a plugin Oauth SSO client for GLPI included in the GLPI Network subscription (BASIC or higher).

In this case, is not included in the Open Source project and can be used only by customers with an active (paid) subscription.

I have not tested it, but they explicitly mention Okta in their documentation.

With the GLPI Network subscription you can also leverage on the SCIM connector for GLPI.

Workflows Integration with Okta

#

Another interesting aspect of GLPI is the possibility to integrate it with Okta Workflows, using the GLPI API and the GLPI WebHook.

I will update this post soon with some examples of integration.

Introduction

#

This guide provides a step-by-step walkthrough for deploying the OpenLDAP directory service, and integrate it with Okta, using Docker and Docker Compose.

You will find also step by step instructions for install in a clean Ubuntu 24.04 LTS server, in case you don’t want (or can’t) use Docker.

We will cover everything from the initial server setup to populating the directory with data for a fictional company, “The Galaxy” (galaxy.universe), using management tools, and integrating with Okta using the LDAP Agent.

Navigation Guide

#

This guide offers multiple setup approaches to match your needs:

• Containerized Deployment with Docker Compose (Recommended) - The fastest and easiest way to get started
• Manual Installation - Step-by-step native installation (based on Ubuntu 24.04 LTS) for learning and production
• Fully Automated One-click Installation Script - Automated native installation for quick deployment on Ubuntu 24.04 LTS
• Using Management Interfaces - Two different approach for manage the LDAP Server: a web interface and a Desktop Client
• Managing the Okta-LDAP Integration - Configure Okta integration after any setup method

The LDIF Files

#

We will define our entries using the LDAP Data Interchange Format (LDIF).

Once cloned the GitHub repository fabiograsso/okta-lab-ldap you will find the ready to use LDIF files in the ./src/ldifs-base/ folder. Additional files that will be used in the Okta-LDAP Integration are available in the ./src/ldifs/ folder.

Let’s take a look at our files:

1. root.ldif - Root Domain, create the root of our LDAP server (dc=galaxy,dc=universe):

   dn: dc=galaxy,dc=universe
   objectClass: top
   objectClass: domain
   dc: galaxy

2. ou.ldif - Organizational Units, which creates the top-level containers (OU - Organizational Units) for our users and groups:

   dn: ou=People,dc=galaxy,dc=universe
   objectClass: organizationalUnit
   ou: People
   
   dn: ou=Groups,dc=galaxy,dc=universe
   objectClass: organizationalUnit
   ou: Groups

3. users.ldif - Sample Users, which defines 12 users with various attributes, for example:

   dn: uid=luke.skywalker@galaxy.local,ou=People,dc=galaxy,dc=universe
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: person
   cn: Luke Skywalker
   givenName: Luke
   sn: Skywalker
   uid: luke.skywalker@galaxy.local
   mail: luke.skywalker@galaxy.local
   userPassword: {SSHA}P@ssword2024!
   title: Jedi Knight
   departmentNumber: JEDI-COUNCIL
   manager: uid=obiwan.kenobi@galaxy.local,ou=People,dc=galaxy,dc=universe
   o: Jedi
   postalAddress: Lars Moisture Farm, Anchorhead, Tatooine
   displayName: Luke Skywalker
   employeeNumber: 10021

4. groups.ldif - Sample Groups, which defines groups using the groupOfUniqueNames object class, and the uniqueMember attribute. Example:

   dn: cn=Droids,ou=Groups,dc=galaxy,dc=universe
   objectClass: top
   objectClass: groupOfUniqueNames
   cn: Droids
   description: Intelligent mechanical droid characters
   uniqueMember: uid=c-3po@galaxy.local,ou=People,dc=galaxy,dc=universe
   uniqueMember: uid=r2-d2@galaxy.local,ou=People,dc=galaxy,dc=universe

5. photos.ldif - While it is not actually supported in Okta, we can load profile pictures in the LDAP Directory. It’s one of the most requested features in Okta Ideas, so the hope is that, sooner or later, Okta will support it, and our directory will be ready 😉 Photos are Base64 encoded JPEG files, and are defined in the jpegPhoto attribute of inetOrgPerson Object Class. For example:

   dn: uid=padme.amidala@galaxy.local,ou=People,dc=galaxy,dc=universe
   changetype: modify
   add: jpegPhoto
   jpegPhoto:: /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAYEBQYFBAY[...]

The following table summarizes the users who will be loaded in our example:

#!/bin/bash

DOMAIN="custom-domain.com"  
find ./src/ldifs-base ./src/ldifs -type f -name "*.ldif" | \  
while read file; do  
  sed -i '' -E "s/^(mail: )([a-zA-Z0-9._-]+)@galaxy\.local/\1\2@${DOMAIN}/g" "$file"  
done  

#!/bin/bash

GMAIL_USER="your.name"  
GMAIL_DOMAIN="gmail.com"  
find ./src/ldifs-base ./src/ldifs -type f -name "*.ldif" | \  
while read file; do  
  sed -i '' -E "s/^(mail: )([a-zA-Z0-9._-]+)@galaxy\.local/\1${GMAIL_USER}+\2@${GMAIL_DOMAIN}/g" "$file"  
done  

TCP Ports

#

This guide uses ports 1389 (LDAP) and 1636 (LDAPS) instead of the standard 389/636 for several reasons:

1. Non-privileged access: Ports below 1024 require root privileges to bind. Using higher ports allows the Docker containers to run with reduced privileges, improving security.
2. Avoid conflicts: If your system already has an LDAP service or Active Directory domain controller running, it would be using the standard ports. The alternate ports prevent conflicts.
3. Development flexibility: In development environments, you can run multiple LDAP instances simultaneously on the same host using different port ranges.
4. Security through obscurity: While not a primary security measure, using non-standard ports can reduce automated scanning attempts in exposed environments.

If you need to use standard ports, you can modify the port mappings in docker-compose.yml, or in the file /etc/default/slapd.

The Okta LDAP Agent

#

The Okta LDAP Agent is a lightweight software component that acts as a secure bridge between your on-premises LDAP directory and Okta’s cloud-based identity platform. It enables organizations to integrate existing LDAP directories (such as OpenLDAP, Oracle Directory Server, or IBM Security Directory Server) with Okta without requiring direct network connectivity or exposing LDAP ports to the internet.

Key capabilities:

• Delegated Authentication: Allows users to authenticate against your LDAP directory while accessing Okta-protected applications, maintaining your existing password policies and authentication logic
• User Provisioning: Synchronizes user profiles and groups from LDAP to Okta, or vice versa, based on your configuration
• Password Management: Supports password changes and resets initiated from Okta, propagating them back to your LDAP directory
• Secure Communication: Establishes an outbound HTTPS connection from your network to Okta, eliminating the need for inbound firewall rules
• High Availability: Supports multiple agents for redundancy and load balancing
• Automatic Updates: Agents can update themselves automatically when multiple instances are deployed

The agent runs as a service on Windows or Linux servers within your network, polling your LDAP directory at regular intervals and communicating changes to Okta via secure REST API calls.

Containerized Deployment with Docker Compose

#

Docker is the ideal solution for a fast, reproducible, portable, and isolated setup. This section provides a complete docker-compose.yml configuration to deploy the entire stack.

Prerequisites

#

• Docker and Docker Compose are installed.
  • If you are using a Ubuntu 24.04 Linux server: apt-get install -y docker docker-compose
  • In a macOS or Windows environment, you can install Docker Desktop
• Git clone the following repository:

  git clone https://github.com/fabiograsso/okta-lab-ldap/
  cd okta-lab-ldap

• Download the .deb file of the Okta LDAP Agent and copy it into the ./docker/okta-ldap-agent/package folder.
  1. Log in to your Okta Admin Console.
  2. Navigate to Directory → Directory Integrations.
  3. Click Add Directory → Add LDAP Directory.
  4. Follow the setup steps. On the “Install Agent” step, right-click the Download Agent button and copy the link.
  5. Download the .deb file on your LDAP server:

     curl -o ./docker/okta-ldap-agent/package/OktaLDAPAgent.deb \
     https://xxx.okta.com/artifacts/JAVA_LDAP/05.24.00/OktaLDAPAgent-05.24.00-27823a892f7b.x86_64.deb

• Alternatively, populate the DEB_URL environment variable with the download URL

Configuration File

#

The .env file contains all the configuration. You can customize it, or you can keep the default value and change only the OKTA_ORG value to your Okta tenant name.

OKTA_ORG=myorg.okta.com
LDAP_ORGANISATION=The Galaxy
LDAP_DOMAIN=galaxy.universe
LDAP_BASE_DN=dc=galaxy,dc=universe
LDAP_ADMIN_PASSWORD=adminpassword
LDAP_CONFIG_PASSWORD=configpassword

The src/ldifs-base folder contains the LDIF files for OU, Users, and Groups. It will load the sample data described before.

Execution

#

There is a Makefile that contains some shortcuts in order to make it easier to execute the needed Docker Compose commands.

1. Build the Stack

   Since there is a custom image used for the Okta LDAP agent, the first step is to build it. From the okta-lab-ldap root directory, run:

   make build

2. Start the Stack

   make start

3. Configure the Okta Agent

   This is a one-time manual step. You don’t need to run it again when you restart the service.

   make configure

   Follow the prompts:

   1. Okta Subdomain: Enter your Okta org URL (e.g., https://myorg.okta.com).
   2. Proxy Server: Press Enter to skip.
   3. LDAP Server: ldaps://openldap:1636
   4. LDAP Admin DN for Agent: For testing, you can use the main admin account: cn=admin,dc=galaxy,dc=universe. For production, see the considerations in the Appendix.
   5. LDAP Admin Password: Enter the password for the account above.
   6. Register Agent in Okta:
      • You will see a prompt like this: To continue, navigate to the following website: [https://xxx.okta.com/activate] and enter the following code: [MSJPKGRP]
      • Follow the instructions and open the /activate URL in your Okta tenant
      • Enter the Activation code
      • Click on “Allow”

   You can ignore the final error: /opt/Okta/OktaLDAPAgent/scripts/configure_agent.sh: line 302: systemctl: command not found - This is due to the fact that the Docker image doesn’t support systemctl. The startup of the agent will be in any case handled by the docker image script.

ssh -f -N -L 1389:localhost:1389 ubuntu@myserverIP  
ssh -f -N -L 1636:localhost:1636 ubuntu@myserverIP  
ssh -f -N -L 5000:localhost:5000 ubuntu@myserverIP  

Other commands

#

Other Makefile commands:

Using Management Interfaces

#

While command-line tools are powerful, graphical interfaces are more comfortable for daily administration.

This section will cover two approaches: the first with a light Web UI (ldap-ui) and the second with a powerful fat client.

Web-Based Management with ldap-ui

#

There are many web management tools for LDAP, but the choice of using ldap-ui is due to:

• phpLDAPadmin, a classic choice, is largely unmaintained and has significant compatibility issues with the modern PHP versions included in Ubuntu 24.04.
• LDAP Account Manager (LAM) is a powerful and feature-rich tool, but many of its advanced features are restricted to the paid “Pro” version.
• ldap-ui provides a clean and simple interface for daily administrative tasks, is open-source, and well-maintained.

Access the ldap-ui interface

#

• If you’re running you Docker Compose stack locally, you can simply open http://localhost:5000 in a web browser, and log in using admin as username and the cn=admin password.
• If you’re running it in a remote server, since there is no specific security, I warmly suggest:
  • Publish it using a reverse proxy (i.e., nginx), or
  • Create an SSH tunnel and then open the web portal from your PC instead of exposing port 5000 of the server

    ssh -f -N -L 5000:localhost:5000 ubuntu@myopenldapserver

    Once opened the tunnel open http://localhost:5000 in a web browser

More information about ldap-ui can be found in dnknth/ldap-ui Github repository.

Desktop Management with Apache Directory Studio

#

Apache Directory Studio is the industry standard as a native desktop client (Eclipse-based) for heavy-duty LDAP work. It supports many types of directories, along with an LDIF editor, a Schema browser, and many advanced features.

1. Download - Visit the Apache Directory Studio downloads page and download the appropriate version for your operating system (e.g., macOS, Windows, Linux).

2. Install - Follow the standard installation procedure for your OS.

   Install on Silicon MacOS (M1/M2/M3/M4 - ARM CPU)

   #

   New MacBooks have a Silicon (ARM-based) CPU, while Apache Directory Studio is compiled for x86. In order to run it properly, you need to follow some additional steps:

   1. Rosetta 2, which enables the use of apps that were built for a Mac with an Intel processor:

      /usr/sbin/softwareupdate --install-rosetta \  
                              --agree-to-license  

   2. Homebrew, a powerful package manager for macOS:

      /bin/bash -c "$(curl -fsSL \  
      https://raw.githubusercontent.com/Homebrew/\  
      install/HEAD/install.sh)"  

   3. An x86 Java SDK:

      arch -x86_64 brew install oracle-jdk  

   4. You can then install Apache Directory Studio directly with brew:

      brew install apache-directory-studio  

3. Create a New Connection

   1. Launch Apache Directory Studio.
   2. Go to File → New… → LDAP Connection.
   3. Hostname: localhost
   4. Port: 1389. (or 1636 for LDAPS)
   5. Click “Check Network Parameter” to verify connectivity.
   6. On the next screen, enter the Bind DN (cn=admin,dc=galaxy,dc=universe) and your Admin password.
   7. Click Finish.

You can now use the LDAP Browser to explore, edit, and manage the directory.

Managing the Okta-LDAP Integration

#

Once the agent is connected, you can configure the integration from your Okta Admin Console.

Complete the LDAP configuration in Okta

#

1. Open the Okta Admin Console and go to Directory → Directory Integrations
2. You will find a “Not yet configured” LDAP in the list. Click on the “LDAP” link:

   

3. Configure using the following parameters:
   1. LDAP Version: OpenLDAP
   2. Objects
      • Unique Identifier Attribute: entryuuid
      • DN Attribute: entrydn
   3. User
      • User Search Base: ou=People,dc=galaxy,dc=universe
      • Object Class: inetorgperson
      • User Object Filter: (objectclass=inetorgperson)
      • Account Disabled Attribute: fax
        To simplify things with a simple demo, we are not implementing any password/lockout policy at the LDAP Server level. Despite this, Okta needs to define an attribute to enable/disable users. So we are configuring an unused attribute (the fax). In a real environment, this attribute will be the one defined by the lockout and password policy.
      • Account Disabled Value: TRUE
      • Account Enabled Value: FALSE
      • Password Attribute: userpassword
   4. Group
      • Group Search Base: ou=Groups,dc=galaxy,dc=universe
      • Group Object Class: groupofuniquenames
      • Group Object Filter: (objectclass=groupofuniquenames)
      • Member Attribute: uniqueMember
   5. Role
      • Object Class: leave blank
      • Membership Attribute: leave blank
   6. Validate Configuration
      • Okta username format: User Id (UID)
      • Example username: yoda@galaxy.local
   7. Click on “Test Configuration”. You will see the user details:

      

   8. Click “Next”
   9. Click “Done”

      

Importing Users and Groups

#

1. Configure Import Settings

   1. In your Okta Admin Console, go to the settings for your newly configured LDAP directory.
   2. Navigate to the Provisioning → To Okta tab.
   3. Configure the settings:
      • Schedule import: every hour (or choose another timeframe)
      • Okta Username Format: Email
      • flag “Don't send new user activation emails for this domain” and “Create and update users on login”
      • Enable “Auto-confirm new users” and “Auto-activate new users”

        

2. Run a manual Import

   1. Navigate to the Import tab.
   2. Click Import Now. Okta will scan your LDAP directory and import the users and groups

      

   3. You will see the LDAP Users and Groups in your Okta Directory

      

      

Delegated Authentication

#

Enable Delegated Authentication and allow users to authenticate against your OpenLDAP directory.

1. Navigate to Security → Delegated Authentication.
2. Enable LDAP Authentication.
3. Test with an existing user and their password

Attribute Mapping and Custom Schema

#

You can map attributes between Okta and LDAP, including custom ones.

1. Extend the Schema You can load the ready-to-use file 5.schema.ldif, and run:

   ldapmodify -Y EXTERNAL -H ldapi:/// -f ./src/ldifs/5.schema.ldif

   The file contains the following:

   1. Extend the OpenLDAP Schema - To add a custom attribute (e.g., species), you must first define it in your OpenLDAP schema.

      # Add the new attribute type 'species'
      dn: cn=LucasfilmPerson,cn=schema,cn=config
      objectClass: olcSchemaConfig
      cn: LucasfilmPerson
      olcAttributeTypes: ( 1.3.6.1.4.1.55555.1.2
      NAME 'species'
      DESC 'The species of the person'
      EQUALITY caseIgnoreMatch
      SUBSTR caseIgnoreSubstringsMatch
      SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
      SINGLE-VALUE )
      olcObjectClasses: ( 1.3.6.1.4.1.55555.2.2
      NAME 'LucasfilmPerson'
      DESC 'Lucasfilm person attributes'
      SUP top
      AUXILIARY
      MAY ( species ) )

   2. (Optional) Load the constraint module and create a constraint rule in order to accept only some type of data in the new attribute (in this case, for example, we will accept only one from Wookiee, Human, Droid, Gungan, Ewok, Yoda, or Clone):

      # Load the constraint module
      dn: cn=module,cn=config
      changetype: add
      cn: module
      objectClass: olcModuleList
      olcModuleLoad: constraint.so
      
      # Load the constraint overlay on your database 
      dn: olcOverlay=constraint,olcDatabase={2}mdb,cn=config
      changetype: add
      objectClass: olcOverlayConfig
      objectClass: olcConstraintConfig
      olcOverlay: constraint
      olcConstraintAttribute: species regex "^(Wookiee|Human|Droid|Gungan|Ewok|Yoda|Clone)$"

2. Update the users

   Also here, you can load the ready-to-use file 6.updateusers.ldif, and run:

   ldapmodify -Y EXTERNAL -H ldapi:/// -f ./src/ldifs/6.updateusers.ldif

   The file contains a series of lines like:

   dn: uid=luke.skywalker@galaxy.local,ou=People,dc=galaxy,dc=universe
   changetype: modify
   add: objectClass
   objectClass: LucasfilmPerson
   -
   add: species
   species: Human
   
   [...]

3. Map the Attribute in Okta

   1. Go to Directory → Directory Integrations and select your LDAP directory
   2. In the Provisioning → Integration tab, add LucasfilmPerson as an Auxiliary Object Class

      

   3. Test the configuration with a user (i.e. yoda@galaxy.local) and save
   4. Go to Directory → Profile Editor → Okta → User (default)
   5. Click Add Attribute
   6. Create a new attribute named Species
      • Data type: string
      • Display name: Species
      • Variable name: species
      • Description:
      • (optional) Enum: insert the following list: Wookiee, Human, Droid, Gungan, Ewok, Yoda, Clone

        

   7. Go back to Directory → Profile Editor → Directories
   8. Find your LDAP directory profile and click Add Attributes
   9. Search and select species, then Save

      

   10. Click on Mappings.
   11. Map the LDAP ‘species’ attribute with Okta’s attribute in both directions (LDAP to Okta, and Okta to LDAP) and then Save

       

   12. Go back to Directory → Directory Integrations, select your LDAP directory, and run an LDAP import. Verify that the field is populated for the users

       

Provisioning from Okta to LDAP

#

You can also create and manage users in LDAP directly from Okta.

1. Disable the Profile Sourcing

   1. Go to the Provisioning → To Okta tab for your LDAP integration.
   2. Remove the flag from “Allow LDAP to source Okta users”

      

2. Enable Provisioning

   1. Go to the Provisioning → To App tab for your LDAP integration.
   2. Enable the features you need, such as Create Users, Update User Attributes, and Deactivate Users.
   3. For “Create Users” use the following parameters:
      • Activation email recipient: your email address (or an galaxy.local alias)
      • RDN attribute name: uid ⚠️ this is very important
   4. Change the mapping for the Distinguished Name dn attribute, by using the following expression:

      "uid=" + user.login + ",ou=People,dc=galaxy,dc=universe"

      

   5. Change the mapping for the Common Name (cn) attribute, and map it to the Okta attribute “Display Name”

      

   6. Optionally map the other optional attributes, such as
      • managerDn
      • postalAddress

3. Create two new users:

   1. Jar Jar
      • First name: Jar Jar
      • Last name: Binks
      • Username: jarjar@galaxy.local
      • Primary email: jarjar.binks@galaxy.local
      • Title: Junior Representative
      • DepartmentNumber: GUNGAN-GRAND-ARMY
      • Organization: Resistance
      • Postal Address: Otoh Gunga, Naboo
      • DisplayName: Jar Jar
      • employeeNumber: 10030
      • Species: Gungan
   2. Boba Fett
      • First name: Boba
      • Last name: Fett
      • Username: boba.fett@galaxy.local
      • Primary email: boba.fett@galaxy.local
      • Title: Bounty Hunter
      • DepartmentNumber: BOUNTY-HUNTERS-GUILD
      • Organization: Empire
      • Postal Address: Slave I, Outer Rim
      • Display Name: Boba Fett
      • employeeNumber: 8084
      • Species: Clone

4. Create an LDAP Provisioning group

   1. In the Directory → People → Groups section, click on “Add Group”
   2. name it “LDAP Provisioning”
   3. Once created, click on it and go to the Directories tab
   4. Click on Manage directories
   5. Add the LDAP Directory as a member and click Next

      

   6. Insert ou=People,dc=galaxy,dc=universe as Provisioning Destination DN
   7. Click “Confirm Changes”

5. Add the two users (Jar Jar and Boba Fett) to the “LDAP Provisioning” Group

6. You will then see the users created in the LDAP directory

Password reset

#

You can also enable Self-Service Password Reset (SSPR) for LDAP Users.

1. In the Admin Console, go to Security → Delegated Authentication.
2. Click the LDAP tab.
3. In Delegated Authentication, click Edit.
4. Verify that Enable delegated authentication to LDAP is enabled.
5. Go to Security → Authenticators, click on the Actions dropdown near Password, and select Edit
6. Select “LDAP Policy” from the list on the left
7. Scroll to the bottom and click Add Rule

   

8. Create a new rule and enable Users can perform self-service options

   

Password validation

#

Use the pwdPolicy object class and pwdPolicySubentry attribute to implement OpenLDAP-specific password policies. You can refer to the OpenLDAP manual on how to configure password policies inside the LDAP server.

OU Change

#

Load the file 8.new-ous.ldif by running:

ldapadd -Y EXTERNAL -H ldapi:/// -f ./src/ldifs/8.new-ous.ldif

The file contains instructions to create new OUs:

# --- CREATE NEW ORGANIZATIONAL UNITS ---

dn: ou=Jedi,ou=People,dc=galaxy,dc=universe
objectClass: organizationalUnit
ou: Jedi

dn: ou=Resistance,ou=People,dc=galaxy,dc=universe
objectClass: organizationalUnit
ou: Resistance

dn: ou=Empire,ou=People,dc=galaxy,dc=universe
objectClass: organizationalUnit
ou: Empire

dn: ou=Droid,ou=People,dc=galaxy,dc=universe
objectClass: organizationalUnit
ou: Droid

We can now change the OU using an LDIF, for example:

# --- MOVE USERS TO NEW OUs ---

dn: uid=luke.skywalker@galaxy.local,ou=People,dc=galaxy,dc=universe
changetype: modrdn
newrdn: uid=luke.skywalker@galaxy.local
deleteoldrdn: 1
newsuperior: ou=Jedi,ou=People,dc=galaxy,dc=universe

But, since we want to demonstrate Okta, let’s see how to manage the OU changes using Okta:

1. Go to Settings → Features and enable the Early Access feature Support user moves across OUs in LDAP

   

2. Go back to Directory → Directory Integrations, click on LDAP and Provisioning → To App

3. Enable both Update User Attributes and Update OU when the group that provisions a user to LDAP changes

   

4. Create a new group named “LDAP Provisioning - Resistance”

Follow the same instructions as Provisioning from Okta to LDAP

But change the Provisioning Destination DN value to ou=Resistance,ou=People,dc=galaxy,dc=universe

5. Pick the user Jar Jar Binks, remove him from the group “LDAP Provisioning” and add him to the group “LDAP Provisioning - Resistance”
6. You will find Jar Jar moved to the Resistance OU

   

You can then continue by generating other groups, such as “LDAP Provisioning - Empire” and so on

As an alternative, we can do the same operation with an LDIF file:

ldapadd -Y EXTERNAL -H ldapi:/// -f ./src/ldifs/9.change-ou.ldif

Group Push

#

The Group Push feature, which synchronizes group memberships from Okta to an application, is not currently supported for OpenLDAP directories. This functionality is on Okta’s product roadmap.

This article will be updated as soon as the feature will be available.

Manual Installation

#

This section details the manual process of setting up an OpenLDAP server from scratch on a clean Ubuntu 24.04 installation, and assumes that the operating system is already installed (e.g., deploying an EC2 VM on AWS). It’s an alternative if you cannot use Docker, or if you want a system that it’s then production-ready.

For a Demo/PoC, an EC2 t3.micro instance (included in the free tier) is enough.

OpenLDAP Server Installation and Configuration

#

1. System Preparation

   #

   Update the system packages to latest version:

   sudo apt update && sudo apt upgrade

2. OpenLDAP Installation

   #

   Install the OpenLDAP server (slapd) and command-line utilities (ldap-utils):

   sudo apt update && sudo apt install -y slapd ldap-utils 

3. Core OpenLDAP Configuration

   #

   The slapd package includes an interactive configuration wizard, which is critical for defining the Directory’s structure. Even if you can change these settings later, it is better and quicker to provide the right information during this step.

   Execute the configuration tool:

   sudo dpkg-reconfigure slapd

   Follow the Prompts

   #

   Answer the questions as follows:

   • Omit OpenLDAP server configuration? → No.
   • DNS domain name? → galaxy.universe
     This is the most important setting. It automatically generates the directory’s Base Distinguished Name (DN). For galaxy.universe, the wizard creates dc=galaxy,dc=universe.
   • Organization name? → The Galaxy
   • Administrator password? → Enter a password (e.g., adminpassword).
   • Confirm password: → Re-enter the password.
   • Database backend? → MDB
   • Do you want the database to be removed when slapd is purged? → No
   • Move old database? → Yes.

4. Verification

   #

   • Check Service Status

     #

     sudo systemctl status slapd

     The service should be active (running).

   • Inspect the Directory

     #

     Use slapcat, which will show the entire content of the LDAP database:

     sudo slapcat

     You should see the base structure for dc=galaxy,dc=universe, and the admin user (cn=admin,dc=galaxy,dc=universe).

     

5. cn=config

   #

   The next step is to update the password of the cn=config user. Remember to change line 5 and choose a strong password:

   sudo ldapmodify -Y EXTERNAL -H ldapi:/// <<EOF
   dn: olcDatabase={0}config,cn=config
   changetype: modify
   replace: olcRootPW
   olcRootPW: $(slappasswd -s "configpassword")
   EOF

6. olcAccess

   #

   Now we’ll apply some changes to the default config and security:

   1. in OpenLDAP configuration, the DN gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth represents the local root user (typically UID/GID 0) authenticating via a secure Unix socket for administrative tasks, while cn=config and cn=admin,dc=galaxy,dc=universe are built-in or custom admin DNs with full privileges over the config and MDB databases, respectively. The changes replace existing ACLs to strictly grant these users “manage” access (full read/write/control) to all attributes, denying everything to others for enhanced security, ensuring only trusted admins can modify server settings or data.

   2. Creates indexes on the attributes “mail”, “surname”, and “givenname”. This optimizes searches involving email addresses or names, reducing lookup times in large directories.

   sudo ldapmodify -Y EXTERNAL -H ldapi:/// <<EOF
   dn: olcDatabase={0}config,cn=config
   changetype: modify
   replace: olcAccess
   olcAccess: {0}to * 
   by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth" manage
   by dn.base="cn=config" manage
   by * none
   
   dn: olcDatabase={1}mdb,cn=config
   changetype: modify
   replace: olcAccess
   olcAccess: {0}to * 
   by dn.base="gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth" manage
   by dn.base="cn=admin,dc=galaxy,dc=universe" manage
   by * none
   -
   add: olcDbIndex
   olcDbIndex: mail,surname,givenname eq,pres,sub
   
   EOF

7. Securing OpenLDAP with LDAPS

   #

   To encrypt communication with your LDAP server, you can enable LDAPS (LDAP over TLS) on port 1636.

   1. Generate a Self-Signed Certificate:

      sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
      -keyout /etc/ldap/sasl2/cert.key -out /etc/ldap/sasl2/cert.crt

   2. Configure slapd for LDAPS: Execute the following LDIF to load the certificate paths into the LDAP configuration.

      sudo chown -R openldap:openldap /etc/ldap/sasl2
      
      sudo ldapmodify -Y EXTERNAL -H ldapi:/// <<EOF
      dn: cn=config
      changetype: modify
      replace: olcTLSCACertificateFile
      olcTLSCACertificateFile: /etc/ldap/sasl2/cert.crt
      -
      replace: olcTLSCertificateKeyFile
      olcTLSCertificateKeyFile: /etc/ldap/sasl2/cert.key
      -
      replace: olcTLSCertificateFile
      olcTLSCertificateFile: /etc/ldap/sasl2/cert.crt
      -
      replace: olcTLSVerifyClient
      olcTLSVerifyClient: never
      EOF

   3. Enable LDAPS Port: Edit the slapd service file to include the LDAPS URL.

      sudo nano /etc/default/slapd

      Modify the SLAPD_SERVICES line:

      SLAPD_SERVICES="ldap://:1389/ ldapi:/// ldaps://:1636/"

      Restart the service:

      sudo systemctl restart slapd