The Generic Directory Connector supports all Create, Read, Update & Delete actions on users in OneLogin, allowing the source system to act as the source of truth for users in your OneLogin Tenant. Once a user is disabled in the source system, for example, they are automatically disabled in OneLogin.

Adding the Generic Directory Connector

1. In your OneLogin Administrative account, go to Users > Directories > New Directory.

2. Choose the Generic connector.

3. Give the directory a name.

4. Ensure Authenticate users in is set to OneLogin.

5. Save. Once the Connector is added, you can begin configuring it to connect to your target system of choice.

Import Users

• Enabled: select to enable importing users.

• Include user status: select to enable importing users with their statuses.

• Skip disabled users: select to skip disabled users when importing.

• Automatic Import Cron Definition: use this field to Schedule the directory connector to run on a regular basis.

  For example, to run the directory connector every...

  •  

  • 1 hour: enter 0 */1 * * *

  • 2 hours: enter 0 */2 * * *

  • 4 hours: enter 0 */4 * * *

Exporting Users

• Enabled: select to enable exporting users.

  If enabling this function, ensure the Export Action is defined in the JSON template defining communication field.

API Communication

• JSON template defining communication: JSON template which defines how the connector communicates to the external system REST API for supported actions.

{
  "import": {
    "users": {
     "path": "/users",
     "parameters": {
       "page": 1,
       "custom_attributes.food": "pizza",
       "limit": 100
     },
     "responses": {
       "oauth_refresh": {
          "401": [
            "onelogin_oauth"
          ]
        },
       "extract": [
         {
           "first_name": {
             "*by_path": "body.*.firstname",
             "*constant" : "missing_firstname"
           },
           "last_name": {
             "*by_path": "body.*.lastname",
             "*constant" : "missing_lastname"
           },
           "username": {
             "*by_path": "body.*.username",
             "*constant" : "missing_username"
           },
           "email": {
             "*by_path": "body.*.email"
           },
           "phone": {
             "*by_path": "body.*.phone",
             "*constant" : "missing_phone_number"
           },
           "id": {
             "*by_path": "body.*.id"
           },
           "status": {
             "*by_path": "body.*.status",
             "#map": {
               "0": "{$user_status.suspended}",
               "1": "{$user_status.active}",
               "2": "{$user_status.suspended}",
               "3": "{$user_status.suspended}",
               "4": "{$user_status.active}",
               "5": "{$user_status.active}",
               "7": "{$user_status.suspended}",
               "8": "{$user_status.suspended}"
             }
           },
           "external_id": {
             "*raw": "{}"
           }
         }
       ],
       "validate": {
         "unless": {
           "headers.content-length": "2"
         }
       }
     },
     "page_increase": {
       "parameters": "page"
     }
   },
    "users_count": [
      {
        "path": "/users",
        "parameters": {
          "page": 1,
          "custom_attributes.food": "pizza",
          "limit": 100
        },
        "responses": {
          "oauth_refresh": {
          "401": [
            "onelogin_oauth"
          ]
        },
          "extract": {
            "*by_path": "headers.*.total-count"
          },
          "validate": {
         "unless": {
           "headers.content-length": "2"
         }
          }
        }
      }
    ],
    "user_ids": [
      {
        "path": "/users",
        "parameters": {
          "page": 1,
          "custom_attributes.food": "pizza",
          "limit": 100
        },
        "responses": {
         "oauth_refresh": {
          "401": [
            "onelogin_oauth"
          ]
        },
          "extract": {
            "*by_path": "body.*.id"
          }
        },
        "validate": {
         "unless": {
           "headers.content-length": "2"
         }
          },
        "page_increase": {
          "parameters": "page"
        }
      }
    ],
    "fields": {
      "*constant": [
        "id",
        "first_name",
        "last_name",
        "email",
        "username",
        "external_id",
        "phone"
      ]
    }
  },
  "base_url":"https://{$tokens.ol_subdomain_name}.onelogin.com/api/2",
  "headers": {
    "Authorization": "Bearer {$oauth.access_tokens.onelogin_oauth}",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  "skip_empty_body_properties": true
} 

API Tokens

• JSON defining secrets: JSON block containing secrets or other key value pairs which can then be referenced from within the JSON template defined in JSON template defining communication.

{ 
    "ol_subdomain_name": "cedarstoneworkforceeu-dev" 
} 

API Authorization

• JSON template defining authorization: JSON template that defines how the OneLogin Directory service should obtain access tokens to communicate to the external system via Oauth2 flows. Supported flows include Auth code flow and client Credentials flow.

{ 
  "onelogin_oauth": { 
     "api_name": "OneLogin", 
     "configuration": { 
      "client_credentials": { 
         "token_url": "/auth/oauth2/v2/token", 
         "authorize_url": "/oauth/authorize", 
         "site": "https://[source_ol_subdomain_name].onelogin.com/", 
          "client_secret": "TBC", 
          "client_id": "TBC", 
           "redirect_url": "https://[local_ol_subdomain_name].onelogin.com/directory/authorize" 
      } 
     } 
  } 
} 

Once all required values are filled, Save. After the save operation has completed, there may be a could not authenticate directory error. If this occurs, ignore it and refresh the page in your browser. After the page refreshes there should now be an Authorize button visible underneath the API Authorization parameter.

Testing the connection

Once the API Authorization JSON Template confirmation has been completed (Client ID , Secret, Token URL, etc), you can test the connection to the target system by clicking Authorize. Please ensure the redirect_url is set to the subdomain of the OneLogin tenant you are adding this connector to, e.g https://example.onelogin.com/directory/authorize.

If the connection to the external system was successful, after clicking Authorize you will see the following message: Directory successfully Authorized. A new Directory Attributes tab will appear on the connector. If you do not see this tab then the connection to the external system has not been successful. Verify your configuration and try again.

Directory Attributes

The Directory Attributes tab contains a directory mapping table which displays the following attributes by default:

• external_id: the external id attribute on the user object level.

• firstname: the firstname attribute on the user object level.

• lastname: the lastname attribute on the user object level.

Map fields from your custom directory/system accordingly by selecting an attribute from the drop-down menu. Add an additional attribute by clicking Add Attribute. Map a new attribute mapping on the OneLogin field side to either username or email, as this is required to create new users in the system.

Testing the mappings

1. Once the Directory Attribute table is configured as per your requirements, go to the more actions section and test out the configuration by selecting the Synchronize Users option. You will be presented with a Directory Sync has started message.

2. Go to the Events tab; you should see some new users created in your OneLogin Tenant.

3. Update attributes in your source system for users which have successfully synced into your OneLogin Tenant.

4. Run Synchronize Users again.

5. Return to the Events tab. You should see those users updated in your OneLogin tenant.