Skip to main content

Okta

Okta is an enterprise identity and access management platform that provides authentication, authorization, user management, and security features for organizations. It enables centralized management of user identities, applications, and access policies.

Authentication Types​

Okta supports 2 authentication methods:

  • OAuth 2.0 - Create your own Okta OAuth application with granular scopes. Every user connects with their Okta account.

    • Pros: Most secure, per-user tracking, granular permissions, production-ready
    • Cons: Requires admin privileges to set up, ~5 min setup

  • API Token - Use an API token (SSWS token) for all users.

    • Pros: Quick setup for testing/development
    • Cons: Single shared credential, no per-user tracking, requires org admin to generate

Setting up OAuth 2.0​

OAuth 2.0 is the recommended authentication method for production use. You'll need administrator privileges in your Okta organization.

  1. Log in to your Okta Admin Console

  2. Navigate to Applications → Applications

  3. Click Create App Integration

  4. Select OIDC - OpenID Connect as the Sign-in method

  5. Select Web Application as the Application type

  6. Click Next

  7. Fill in the application details:

    • App integration name: Give it a descriptive name (e.g., "Webrix AI Assistant")
    • Grant type: Check Authorization Code and Refresh Token
    • Sign-in redirect URIs: Copy the Redirect URL from Webrix and paste it here
    • Sign-out redirect URIs: Leave empty or use your app URL
    • Controlled access: Choose who can use this integration (typically "Allow everyone in your organization to access")

  8. Click Save

  9. After creation, you'll see the Client ID and Client Secret - copy both

  10. Scroll down to General Settings and click Edit

  11. Under Login, set:

    • Login initiated by: Either Okta or App
    • Application visibility: Check "Display application icon to users"
    • Login flow: Redirect to app to initiate login

  12. Click Save

  13. Go to the Okta API Scopes tab

  14. Click Grant for the scopes you need:

    • Minimum scopes: okta.users.read, okta.groups.read, okta.apps.read, okta.logs.read
    • Recommended scopes: Add okta.users.manage, okta.groups.manage, okta.roles.read, okta.policies.read
    • Admin scopes (use with caution): okta.apps.manage, okta.roles.manage, okta.policies.manage

  15. In Webrix, paste the Client ID and Client Secret

  16. Under General Settings, Enter your Okta Domain (e.g., https://company.okta.com)

  17. Select the scopes you granted in Okta

  18. Click Save Changes

  19. Click Connect to authorize the integration

tip

If you see "insufficient permissions" errors, make sure you've granted the required OAuth scopes in the Okta Admin Console under the Okta API Scopes tab.

Setting up API Token​

API Tokens provide quick setup but use a shared credential. Requires Super Admin or Org Admin privileges.

  1. Log in to your Okta Admin Console

  2. Navigate to Security → API

  3. Click the Tokens tab

  4. Click Create Token

  5. Give your token a descriptive name (e.g., "Webrix Integration")

  6. Click Create Token

  7. IMPORTANT: Copy the token value immediately - it will only be shown once

  8. In Webrix:

    • Paste the token value
    • Enter your Okta Domain (e.g., company.okta.com)
    • Click Save Changes
caution

API Tokens have full administrative access to your Okta organization. Store them securely and rotate them regularly. Never commit them to source control.

Available Operations​

The Okta connector provides 25 tools across 6 categories:

User Management (7 tools)​

  • List Users - Search and filter users with pagination
  • Get User - Retrieve specific user details by ID or email
  • Search Users - Advanced user search with filter expressions
  • Create User - Provision new user accounts
  • Update User - Modify user profile information
  • Deactivate User - Disable user accounts
  • Activate User - Enable or reactivate user accounts

Group Management (6 tools)​

  • List Groups - Browse and search groups
  • Get Group - Retrieve specific group details
  • List Group Members - See all users in a group
  • Create Group - Create new groups
  • Add User to Group - Grant group membership
  • Remove User from Group - Revoke group membership

Application Management (5 tools)​

  • List Applications - View all applications
  • Get Application - Retrieve application details
  • List Application Users - See users assigned to an app
  • List Application Groups - See groups assigned to an app
  • Assign User to Application - Grant user access to an app

System Logs (2 tools)​

  • Get System Logs - Query audit logs with filters
  • Get Log Event - Retrieve specific log event details

Roles & Permissions (3 tools)​

  • List User Roles - View user's administrative roles
  • List Group Roles - View group's administrative roles
  • Assign Role to User - Grant administrative permissions

Policies (2 tools)​

  • List Policies - View security policies by type
  • Get Policy - Retrieve specific policy details

Common Use Cases​

User Onboarding​

Create a new user → Activate the user → Add user to groups → Assign user to applications

User Offboarding​

List user's applications → Remove user from groups → Deactivate user

Access Audit​

List users → Get user details → List user roles → List group memberships → Get system logs for user activities

Security Investigation​

Get system logs with filters → Get specific log events → Identify affected users → Review user activities

Troubleshooting​

"Invalid API token" error​

Cause: The API token is incorrect, expired, or has been revoked.

Solution:

  1. Verify you copied the complete token value (they're quite long)
  2. Check that the token hasn't been deactivated in Okta Admin Console
  3. Generate a new token and update Webrix

"Insufficient permissions" error (OAuth)​

Cause: The OAuth application doesn't have the required scopes granted.

Solution:

  1. Go to your OAuth app in Okta Admin Console
  2. Click the Okta API Scopes tab
  3. Grant the required scopes for the operation you're trying to perform
  4. Reconnect in Webrix to get a new token with updated scopes

"Invalid domain" error​

Cause: The Okta Domain is formatted incorrectly.

Solution:

  • Use only the domain name: company.okta.com (NOT https://company.okta.com or company.okta.com/)
  • For preview: company.oktapreview.com
  • For dev orgs: dev-12345.okta.com

"User not found" error​

Cause: The user ID or login doesn't exist, or you don't have permission to access it.

Solution:

  1. Verify the user ID or email is correct
  2. Check that you have okta.users.read scope granted
  3. Try searching for the user first using List Users or Search Users

Rate limit errors​

Cause: Too many API requests in a short time period.

Solution: Okta enforces rate limits on API requests. If you hit rate limits:

  1. Wait a few minutes before retrying
  2. Reduce the frequency of requests
  3. Consider using pagination with smaller page sizes
  4. Contact Okta support to increase your rate limits if needed

"SSWS" token format error (API Token)​

Cause: The token is being used incorrectly or the format is wrong.

Solution:

  • API tokens in Okta use the SSWS (Single Sign-on Web Services) authentication scheme
  • Webrix automatically formats this correctly - just paste the token value
  • Don't include "SSWS" prefix when entering the token

Best Practices​

  1. Use OAuth 2.0 for production - It provides better security and audit trails
  2. Grant minimal scopes - Only grant the permissions you actually need
  3. Rotate API tokens regularly - If using API tokens, rotate them every 90 days
  4. Monitor system logs - Regularly review logs for unusual activity
  5. Use groups for access management - Manage application access via groups rather than individual assignments
  6. Test in preview/sandbox - Test integrations in a non-production environment first
  7. Document admin role assignments - Keep track of who has administrative access

Security Considerations​

  • Administrative operations (user deactivation, role assignment) are marked as destructive
  • Role assignment operations grant elevated privileges - use with caution
  • System logs contain sensitive information - restrict access appropriately
  • API tokens have full org admin access - store them securely
  • OAuth scopes should follow principle of least privilege
  • Regular audits of user access and administrative roles are recommended