--- title: "Okta Connector Guide" slug: "okta" updated: 2026-07-23T06:38:55Z published: 2026-07-23T06:38:55Z canonical: "docs.safe.security/okta" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.safe.security/llms.txt > Use this file to discover all available pages before exploring further. # Okta Connector Guide This integration enables Balbix to securely collect identity and access management data from your Okta environment to provide comprehensive security assessment. Follow these steps for a fast configuration: ### Step 1: Create Service User Account 1. Navigate to **Okta Admin Console → Directory → People**. 2. Click **Add Person**. 3. Configure the service user: - **First name:** Balbix - **Last name:** Integration - **Username & Email:** Example: **balbix-integration@yourcompany.com** - **Password:** Generate a strong password and save securely - **Set by Admin:** Select **Checked** - **User must change password on first login:** Select **Unchecked** 4. Ensure the account is activated, then click **Save**. ### Step 2: Assign Read-Only Administrator Role 1. Go to **Security → Administrators**. 2. Click **Add Administrator**. 3. Select the service user (e.g., **balbix-integration@yourcompany.com**). 4. Assign role: **Read-Only Administrator**, scope: *All resources*. 5. Click **Save Changes**. ### Step 3: Generate API Token for this Service Account / User 1. Open an **incognito/private browser window**. 2. Sign in to **https://yourcompany.okta.com** as the service user. 3. Navigate to **Security → API → Tokens**. 4. Click **Create Token** → Name it *Balbix Security Integration*. 5. **Warning:** Copy the token immediately (format: **1234567890abcdef...**). Save securely – it cannot be viewed again. 6. Sign out. ### Step 4: Test the Integration > [!NOTE] > **# Test basic user access** > > curl -X GET "https://YOUR_DOMAIN.okta.com/api/v1/users?limit=1" \ > > -H "Authorization: SSWS YOUR_TOKEN_HERE" \ > > -H "Accept: application/json" > > > > **# Test organization access (required for enterprise analysis)** > > curl -X GET "https://YOUR_DOMAIN.okta.com/api/v1/org" \ > > -H "Authorization: SSWS YOUR_TOKEN_HERE" \ > > -H "Accept: application/json" > > > > **# Test policy access (critical for security findings)** > > curl -X GET "https://YOUR_DOMAIN.okta.com/api/v1/policies?type=PASSWORD" \ > > -H "Authorization: SSWS YOUR_TOKEN_HERE" \ > > -H "Accept: application/json" Expected: JSON responses with user profile, organization info, and policy data. ### Step 5: Provide Credentials to Balbix In the Balbix Okta integration setup workflow, enter: - Okta Domain: yourcompany.okta.com - API Token: ssws_1234567890abcdef... - Role Assignment: Read-Only Administrator - Resource Scope: All Resources (Organization-wide) Follow this procedure in your Balbix Account: [Embedded content](https://scribehow.com/embed/Okta_Connector__lbG3hkWdTj-rrgR6sd5GWQ?as=scrollable) ## Full Integration Guide (Reference) The following sections provide detailed information, rationale, and troubleshooting for security, audit, and compliance teams. ### Purpose and Overview This integration enables Balbix to securely collect identity and access management data from your Okta environment for comprehensive security assessment. Balbix analyzes user accounts, application access patterns, group memberships, and security configurations to identify potential risks and misconfigurations in your identity infrastructure. ### What Balbix Collects from Okta - **User inventory and profile information** - Complete user profiles, status, and attributes - **User relationships** - Group memberships, role assignments, MFA factor enrollment - **Application assignments and access levels** - User-to-app and group-to-app assignments - **Group memberships and organizational structure** - Complete group hierarchy and relationships - **Authentication policies and security settings** - Password, MFA, and sign-on policies - **Organization configuration** - Enterprise settings and security features - **Administrative assignments** - Privileged user identification and role analysis ### Security Benefits - Identify users and their operational states (Active, Suspended, etc.) - Detect excessive application permissions and access creep - Monitor for privileged access anomalies and administrative security gaps - Assess MFA coverage and compliance across the organization - Analyze authentication patterns for risk indicators - Identify dormant accounts and incomplete user profiles - Detect weak authentication methods and policy violations ### Recommended Approach: Read-Only Administrator For most organizations, we recommend using Okta's standard Read-Only Administrator role. This approach provides comprehensive data access with minimal security risk and minimal setup time.

Why Read-Only Administrator is Recommended

 - **Maximum Security**: Zero write permissions – cannot modify any data - **Comprehensive Coverage**: Access to 90%+ of security assessment data - **Simple Setup**: 10-minute configuration using standard Okta roles - **Full Audit Trail**: All API access is logged and auditable ### Alternative Configuration Options - **Fine-Grained Custom Role**: For organizations requiring specific permission control → See Custom Role section - **Enhanced Access**: If additional data beyond Read-Only Administrator is needed, escalation to a Super Administrator may be required for token generation. This is generally not recommended. Contact your Balbix Customer Success team if needed. ### Data Access with Read-Only Administrator | **Data Category** | **What's Included** | **Security Value** | | --- | --- | --- | | User Management | All user profiles, status, attributes, group memberships, role assignments | Identify inactive/orphaned accounts, detect privilege escalation | | Group Management | Group memberships, hierarchies, relationships | Analyze access patterns and role creep | | Application Access | App assignments, permissions, user-to-app mappings | Detect excessive application access and unused applications | | System Logs | Authentication events, security logs (limited) | Monitor for suspicious activities | | Device Management | Device compliance, mobile policies (limited) | Assess endpoint security posture | | Security Policies | Sign-on policies, MFA configurations, password policies | Evaluate authentication security | | Network Zones | Network access controls | Review location-based restrictions | | Admin Roles | Privileged access assignments | Monitor administrative permissions | ### API Coverage Read-Only Administrator provides access to all major Okta APIs required for comprehensive security analysis: **Core Entity APIs:** - **/api/v1/users** – User inventory and profiles - **/api/v1/users/{id}/groups** – User group memberships - **/api/v1/users/{id}/roles** – User administrative roles - **/api/v1/users/{id}/factors** – MFA factor enrollment and status - **/api/v1/users/{id}/appLinks** – User application assignments **Application APIs:** - **/api/v1/app**s – Application configurations and assignments - **/api/v1/apps/{id}/users** – Application user assignments - **/api/v1/apps/{id}/groups** – Application group assignments **Organization APIs:** - **/api/v1/org** – Organization information and settings - **/api/v1/org/features** – Security features status - **/api/v1/policies** – Security policies (Password, MFA, Sign-on) - **/api/v1/groups** – Group definitions and memberships - **/api/v1/zones** – Network security configurations **Limited Access APIs:** - **/api/v1/logs** – System events and audit logs (basic access) - **/api/v1/devices** – Device compliance data (requires additional permissions) ### Security Best Practices

Token Management

 - Store API token in secure credential management system - Never commit tokens to code repositories - Rotate API token annually - Monitor service user activity in Okta System Log

Access Control

 - Use dedicated service user (never personal accounts) - Disable service user when integration is no longer needed - Review permissions quarterly - Monitor for unusual API access patterns

Audit and Compliance

 - All API access is logged in Okta System Log - Read-only access ensures zero modification risk - Standard role assignment simplifies compliance reporting ### Troubleshooting | **Issue** | **Cause** | **Solution** | | --- | --- | --- | | "Invalid token" error | Token copied incorrectly or expired | Verify token starts with ssws_ and has no spaces; regenerate if needed | | "Insufficient privileges" | Role not assigned properly | Verify Read-Only Administrator role assignment | | "User not found" | Wrong domain | Confirm Okta domain is correct | | Service user login fails | Account not activated | Verify user is activated and password is correct | | Some APIs return 403 | Expected for write operations or missing permissions | Contact Balbix if read operations fail | | Rate limiting (429 errors) | Too many API calls | Analysis includes automatic rate limiting; wait for completion | | Partial data collection | Permission gaps for specific endpoints | Review role assignments; some data requires additional permissions | | Analysis timeout | Large organization size | Expected for enterprise orgs; analysis will complete automatically | ### Verification Commands > **# Test comprehensive user access (with relationships)** > > curl -H "Authorization: SSWS YOUR_TOKEN" \ > > "https://YOUR_DOMAIN.okta.com/api/v1/users?limit=1&expand=user" > > > > **# Test organization access (required for enterprise findings)** > > curl -H "Authorization: SSWS YOUR_TOKEN" \ > > "https://YOUR_DOMAIN.okta.com/api/v1/org" > > > > **# Test policy access (critical for security analysis)** > > curl -H "Authorization: SSWS YOUR_TOKEN" \ > > "https://YOUR_DOMAIN.okta.com/api/v1/policies?type=PASSWORD" > > > > **# Test group access** > > curl -H "Authorization: SSWS YOUR_TOKEN" \ > > "https://YOUR_DOMAIN.okta.com/api/v1/groups?limit=1" > > > > **# Test application access** > > curl -H "Authorization: SSWS YOUR_TOKEN" \ > > "https://YOUR_DOMAIN.okta.com/api/v1/apps?limit=1" > > > > **# Test MFA factor access (replace USER_ID with actual user ID)** > > curl -H "Authorization: SSWS YOUR_TOKEN" \ > > "https://YOUR_DOMAIN.okta.com/api/v1/users/USER_ID/factors" ## Custom Role Configuration This section is for organizations requiring more granular permission control than the standard Read-Only Administrator role provides.

When to Use Custom Roles

 Consider custom roles if your organization has: - Strict service account policies prohibiting standard admin roles - Requirements for granular permission scoping - Audit compliance needs for detailed permission documentation - Policies limiting access to specific resource types only ### Custom Role vs. Read-Only Administrator | **Aspect** | **Read-Only Administrator** | **Custom Role** | | --- | --- | --- | | Setup Time | 10 minutes | 20–30 minutes | | Data Coverage | 90%+ comprehensive | 70–80% with basic setup | | Permission Control | Standard, organization-wide | Granular, customizable | | Security Review | Standard role, easy approval | Custom role evaluation needed | | Maintenance | Automatic Okta updates | Manual permission management | ### Custom Role Setup Process 1. **Create Custom Read-Only Role**: Configure role with view-only permissions for users, groups, apps, IAM, and directory integration. 2. **Create Resource Set**: Add all relevant resource types for Balbix data collection. 3. **Assign Custom Role**: Assign the role to the Balbix service user and continue with token generation. ### Required Okta Permissions for Custom Role **Minimum Required Permissions:** - **okta.users.read** - User profiles and status - **okta.users.userAdmin** - User group and role memberships (read-only) - **okta.groups.read** - Group definitions and memberships - **okta.apps.read** - Application configurations and assignments - **okta.policies.read** - Security policies and rules - **okta.org.read** - Organization settings and information **Optional for Enhanced Analysis:** - **okta.logs.read** - Authentication logs (requires Report Administrator role) - **okta.devices.read** - Device compliance (requires Help Desk Administrator role) ### Custom Role Data Access | **Data Category** | **Access with Custom Role** | **Notes** | | --- | --- | --- | | User inventory & profiles | ✓ | Full profile data and attributes | | User relationships (groups, roles) | ✓ | Requires userAdmin permission | | Group memberships | ✓ | Includes hierarchies and relationships | | Application assignments | ✓ | Configuration and access details | | Admin role assignments | ✓ | IAM resources and admin mappings | | Organization settings | ✓ | Requires org.read permission | | Security policies | ✓ | Password, MFA, sign-on policies | | System logs & events | ✗ | Requires Report Administrator role | | Device compliance data | ✗ | Requires Help Desk Administrator | ### Expanding Custom Role Access **Option 1**: Add Standard Role: Add Report Administrator or Help Desk Administrator for additional data. **Option 2**: Upgrade to Read-Only Administrator: Replace custom role with standard Read-Only Administrator role. ## Network Security Okta allows applying Network ACL restrictions to any administrator role, including both the standard Read-Only Administrator setup and Custom Roles. Balbix strongly recommends enabling ACL restrictions for the dedicated integration account. This ensures API access is only possible from Balbix-controlled IP addresses. Always refer to the Access Control List Configuration document for the latest Balbix IP addresses. ## Security Findings Categories Balbix analyzes your Okta environment to identify security risks across three entity types: ### Enterprise Findings - **Password Policy Violations**: Weak length requirements, missing complexity, inactive policies - **MFA Enforcement Gaps**: Missing MFA requirements, weak factor allowances - **Administrative Security Issues**: Excessive super admins, stale admin assignments - **Policy Misconfigurations**: Inactive sign-on policies, missing account lockout - **Network Security Gaps**: Overly broad network zones, insecure trusted origins ### Application Findings - **Weak Authentication Methods**: Basic auth, browser plugins, deprecated OAuth flows - **Application Lifecycle Issues**: Inactive apps with users, active apps without users - **SSO Security Problems**: Missing SAML certificates, insecure redirect URIs - **Access Management Issues**: Over-provisioned applications, suspicious app names - **Configuration Vulnerabilities**: Wildcard redirect URIs, sensitive SAML assertions ### User Findings - **MFA Security Gaps**: Missing enrollment, weak factors, single factor dependency - **Account Hygiene Issues**: Dormant accounts, incomplete profiles, never-logged-in users - **Access Anomalies**: Excessive application assignments, service account access - **Administrative Risks**: Admins without strong MFA, orphaned privileged accounts ## Getting Support - **For Setup Issues**: Contact internal Okta administrator, review Okta documentation, or check System Logs. - **For Balbix Integration Questions**: Contact Balbix Customer Success team with Okta domain, role configuration, and any API error messages. - **For Enhanced Access Requirements**: Contact Balbix Customer Success before considering Super Administrator access. ## Summary This integration provides Balbix with secure, comprehensive access to your Okta environment for security assessment. ### Security Assurance - Read-only access with zero modification risk - Standard or custom role options for different security requirements - Full audit trail of all API interactions - Dedicated service account with strong credentials ### Comprehensive Data Collection - Complete user and application inventory with relationships - Access patterns and permission analysis - Security policy and compliance assessment - Authentication and device security insights - Administrative privilege monitoring ### Implementation Benefits - Quick 10-minute setup with standard approach - Flexible custom role option for granular control - Easy security team approval process - Scalable access that can be expanded if needed - Automatic rate limiting and performance optimization **Recommendation**: In most cases, Balbix strongly recommends the Read-Only Administrator approach for comprehensive coverage and the fastest setup.