Synchronisation between your portal and your company's Okta directory is performed by polling the Okta directory periodically for changes. Communication between Cyber Risk Aware and Okta is handled via the Okta API.


Okta API acts as a gateway to data held in your Okta directory. Applications can communicate using the API along with and API secret (password) that will allow the application to query Okta for information.


The steps to integrate your portal with Okta are detailed below.


Configuration within Okta


Within your Okta administation portal, you will need to create a new API token that will act as a password for the Cyber Risk Aware to access the Okta API and query your Okta directory.


  • Log in to your Okta administration portal I.E. {COMPANY-NAME}-admin.okta,com/admin/dashboard
  • Once logged in, select Security -> API from the main navigation


  • Click on the button Create Token.


  • In the dialog that appears, provide a name for the token e.g. Cyber Risk Aware.



  • In the next dialog, you will be presented with the API Secret / Token. Take note of this value as it will not be visible again. This value will be used when configuring Okta integration on the Cyber Risk Aware portal.



Configuration within Cyber Risk Aware portal



  • Log in to your Cyber Risk Aware portal.
  • Select the menu item User Manager -> AD Sync Configuration.



  • In the next screen, select the tab Okta AD Sync.



  • To enable Okta AD synchronisation with the portal, select the checkbox Enable Okta Sync


This will result in the form appearing to provide your Okta details and attribute mapping details. All fields are explained below: 



Field        
Description    
Mandatory
Use Application Specific ProfileWhen pulling user information from Okta, there are two options.

1. Getting users from the overall Okta directory
2. Getting only the users that are associated directly with the registered application.

When this checkbox is checked, the synchronisation process will only consider users directly associated with the app registration. It will use the profile fields associated with user in the application registration.

When the checkbox is left unchecked, the user information is pulled from the overall Okta directory.

No
Application Secret
This is the token / secret generated when creating the API token in the steps above.
Yes
AuthorityThis is the Tenant URI for accessing Okta i.e. company-name.okta.com
Yes
First Name attribute mapping
This will be the attribute in your Okta directory that contains the users First Name. This will be the unique identifier in the portal.
Yes
Last Name attribute mapping
This will be the attribute in your Okta directory that contains the users Last Name. This will be the unique identifier in the portal.
Yes
Email attribute mapping
This will be the attribute in your Okta directory that contains the users Email address. This will be the unique identifier in the portal.
Yes
Department attribute mapping
If applicable, this will be the attribute in your Okta directory that contains the users Department.
No
Country attribute mapping
If applicable, this will be the attribute in your Okta directory that contains the users Country.
No
Locale attribute mapping
If applicable, this will be the attribute in your Okta directory that contains the users locale (defaults to en-US).
No
Office attribute mapping
If applicable, this will be the attribute in your Okta directory that contains the users Office location.
No
Mobile / Cellular phone attribute mapping
If applicable, this will be the attribute in your Okta directory that contains the users mobile phone number.
No
External Id attribute mapping
If applicable, this will be the attribute in your Okta directory that contains the users External Id (such as HR ID).
No
Business unit attribute mapping
If applicable, this will be the attribute in your Okta directory that contains the users Business unit.
No
Users to exclude
This is a list of user emails (separated by a semicolon) that you wish to exclude from synchronisation.
No
Restrict to groups
When this is checked, only the groups included in the Group restrictions field will be considered in the synchronisation. (Only visible when Use Application Specific Profile is unchecked).
No
Group restrictions
This is a list of group names (separated by a semicolon) that you wish to include in synchronisation.  (Only visible when Use Application Specific Profile is unchecked).
No



Custom Fields


Okta Sync allows for users to make use of up to 5 custom fields. These fields can be mapped to a user in the same way as the core filed mappings above. They can be configured on the UI, just below the core field set up.



Synchronised Deletions


The Okta Syncronisation process also allows customers to keep user deletions synchronised. If the checkbox 'Sync Deletion' is checked, then any users that exist on a customers portal, that are not returned during the next synctionisation run, will be removed from the customers portal. 


Re-Enabling Deleted users


It can happen on occasion that a user can enable synchronised deletions by mistake and have the unexpected behavior where users are removed from their portal. It should be noted however that when a user is deleted from their portal, their historical record still exists - therefore the delete can be reversed. The setting Re-enable deleted users serves this purpose.


When the setting Re-enable deleted users is checked, users that had been marked as deleted on the portal but are returned as part of the next sync run will be re-enabled on their portal.