Creating and Configuring an Okta System of Record

Prerequisites

  • An Okta User account with elevated privileges to read the Okta APIs

Permissions Required

  • Ability to add a new API Service Integration with scopes:
    • okta.users.read, okta.groups.read
  • Ability to generate an Okta API Key (if using an API Key method of authentication)
  • Ability to read User and/or Group objects that are needed to be synchronized to SGNL

Configuring Okta

Using OAuth2 with an API Service Integration

  1. Login to your Okta Organization and select Applications from the left-navigation menu
  2. Choose API Service Integrations and select ‘Add Integration’
  3. Find and select SGNL in the list of integrations then choose ‘Next’
  4. On the ‘Authorize SGNL’ page, choose to ‘Install & Authorize’ SGNL
  5. On the next screen, you will have a single opportunity to copy your ‘client secret’ – copy it and keep it somewhere safe, you’ll need this to configure SGNL in a moment
  6. Once copied, select ‘Done’
  7. In the ‘General’ tab, copy the ‘Client ID’ - you’ll need those to configure SGNL in a moment
  8. By default, the new API Service integration will use scopes ‘okta.users.read’ and ‘okta.groups.read’ to support the synchronization of users and groups from Okta
  9. (Optional) Give the App an image to make it more easily discernable later

Using an API Key

  1. Login to your Okta Organization with the desired User Account that will be responsible for synchronization - note the Okta sub-domain you use to sign-in to this organization
    • Note: SGNL and Okta recommends using an account that does not belong to any individual, but instead acts as a service account in Okta
  2. Create an Okta API Token

Configuring SGNL

  1. Login to the SGNL Console

  2. From the left menu, select Systems of Record

  3. Add a New System of Record and select Okta

  4. Give the new System of Record a friendly Display Name and helpful Description

  5. Select your ‘Authentication Method’ - SGNL recommends using OAuth2 Authentication using an Okta API Service Integration

  6. Enter the following data into SGNL:

    If using OAuth2 authentication for an API Service Integration

    • Client ID: Enter the Client Id you copied previously from Okta
    • Client Secret Enter the Client Secret you copied previously from Okta

SGNL - Add System of Record with OAuth2

If using API Key authentication method

  • AuthToken: Enter the API Key you generated in Okta, prefixed with the needed Okta Token type of “SSWS " - note trailing space

SGNL - Add System of Record

  1. Once configured, click Continue to save your System of Record and move on to configuring Entities

  2. From the Entities tab, click on ‘Edit Attributes’ to select the entities and attributes you will need synchronized into SGNL to be used in your specified SGNL policies

    • Refer to Okta’s documentation for descriptions of attributes you choose to synchronize into SGNL: User, Group
    • E.g. If you want to create a policy that Okta Users of profile__title: Customer Support and with status: Active are allowed to access certain assets, you will need to select the following attributes from the Okta User entity: profile__title, status in addition to principal identifiers such as profile__email or profile__employeeNumber

  3. (If applicable) If you will be synchronizing entities and attributes from 2+ different Systems of Record into SGNL to define policies, click on Add join rule to specify the attribute(s) that will join the entities you’ve configured to synchronize from Okta to other entities in the SGNL Graph

    • You only have to specify a join rule from one System of Record. For instance, if you specify a join rule between Okta Users and Azure Active Directory Users, you only need to configure the relationship from either the Okta or Azure Active Directory System of Record
    • E.g. If User Employee Numbers are found in your Okta and HRIS system and are consistent, you can choose the Employee Number Attribute in this Okta Instance and the Employee Number Attribute in your HRIS System of Record to join these entities together
    • Join rules should only be used for entities that represent the same object across 2+ different Systems of Record. For instance, if a User in Okta represents the same User as one in Azure Active Directory, it is a good candidate for a join rule
      • However, a User in Azure Active Directory and a Group in ServiceNow represent different objects and are therefore not good candidates for join rules, and instead should have custom relationships created via the Relationships API. Additionally, if a User in Azure Active Directory is not the same User as one in ServiceNow, it is not a good candidate for a join rule

  4. Save the Configuration