Guide: Okta Integration

To assist companies in integrating their Okta environment with the security awareness platform for user synchronization, follow the step-by-step guide below. This process ensures secure and scoped access using Okta's OAuth 2.0 service app with private key authentication. (Okta Developer)


Step 1: Create an OAuth 2.0 Service App in Okta

  1. Log in to your Okta Admin Console.
  2. Navigate to Applications > Applications.
  3. Click Create App Integration.
  4. Select API Services as the sign-in method and click Next.
  5. Provide an App integration name (e.g., "Goldphish User Sync") and click Save.

Step 2: Configure Client Authentication and Generate Keys

  1. In the app's settings, go to the General tab.
  2. Under Client Credentials, click Edit.
  3. Select Public key / Private key as the client authentication method.
  4. Click Add key and then Generate new key.
  5. A dialog box will appear showing the Private Key in JSON Web Key (JWK) format.
  6. CRITICAL: Click Copy to clipboard to copy the entire private key JSON. Save this JSON content immediately into a plain text file (e.g., okta_private_key.json) on your local machine. You will not be able to see this private key again in Okta after closing this dialog.
  7. Click Done, then Save the changes.

Step 3: Assign Admin Role and Grant API Scope

  1. Navigate to the Admin Roles tab.
  2. Click Edit assignments.
  3. Select Read-only Administrator from the dropdown and click Save Changes. This role allows view access to user data without modification rights.
  4. Go to the Okta API Scopes tab.
  5. Locate the okta.users.read scope and click Grant.
  6. Confirm by clicking Grant Access. This scope permits read-only access to user information.

Step 4: Configure Okta Integration in the Goldphish Platform

  1. Log in to the Goldphish Admin Portal.
  2. Navigate to Settings > User Sync.
  3. Select Setup Okta.
  4. Enter the following details:
  • Okta Domain: Your Okta organisation's domain (e.g., https://yourcompany.okta.com).
  • Client ID: Found in the Okta app's General tab.
  • Private Key: Paste the contents of the private key you saved.
  • Group ID (Optional): Specify if syncing users from a particular group.
  1. Click Test Connection to verify the configuration.
  2. Upon successful test, click Save.

Note: We suggest you use Manual Scheduling while testing, and desired users get retrieved in the Preview Sync.


Step 5: Initiate User Synchronization

After saving the configuration,

  1. Click Preview Sync to view the results of the user sync.
  2. Once you confirm that all the users are there you can either proceed and do a manual sync by pressing Run User Sync.

Step 6: Schedule Automatic Synchronizations

  1. In the User Sync settings, configure the synchronization schedule:
  2. Choose the frequency (e.g., daily, weekly).
  3. Set the time for the sync to execute.
  4. Click Save to apply the schedule.

Note: When set on scheduled, it will delete ALL users not in the list retrieved from users sync api call (except current Managers - they need to be removed by another manager).


Your Okta user synchronization with the Goldphish platform is now set up and operational. If you encounter any issues or require further assistance, please contact Goldphish Support.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us