The following tutorial walks through the process of integrating Okta with Genea. You will need admin privileges in both Okta and Genea to complete this integration.
Features:
The following provisioning features are supported:
Push New Users
New users created through OKTA will also be created into the Genea.Push Profile Updates
Updates made to the user's profile through OKTA will be pushed to the Genea.Push User Deactivation
Deactivating the user or disabling the user's access to the application through OKTA will deactivate the user in Genea.Push User Suspend
Suspending the user through OKTA will deactivate the user from the Genea.Reactivate Users
Reactivating the user through OKTA will reactivate the user in Genea.Push Group
Push existing groups from OKTA to create, update, deactivate, suspend or reactive one or more users.
Important Notes:
The primary email address and phone number listed in Okta will be the email address and phone number listed in the Genea employee directory.
If an Okta user does not have a primary email address, they will not be synced to the Genea employee directory.
When adding or updating employees, Genea will match based on the primary email address listed for the Okta user. If the primary email address is not found in Genea, a new employee will be added to the Genea employee directory.
When user are assigned to a push group. They will get the access to Genea system as defined in the Integration Rules. Admin will be able to review the changes (Create/Update/Delete) in Audit Log (Activity menu>Audit Log) and in All Users list as well.
We do not support the "Link Group" feature as of now, We only support the "Create Group".
Step 1 : Prepare to enable the Genea Access Control + Okta provisioning integration.
Create Access Groups - You can grant permissions to specific doors in Genea based on your Okta organizational groups. Please create appropriate Access Groups in Genea based on your requirements (this could reflect your Okta group structure) Let's say Employees, Contractors, IT Admins etc.
If you have multiple office locations enabled with Genea, decide whether you’d like to sync all users to all locations or sync specific users per location. This will impact how you set up the integration.
Decide whether you would like to assign mobile keys to all newly boarded users by default.
Step 2 : Generate an API Token for your Okta account
Login to the Okta account and create new token.
Go to Admin > Security > API > Tokens and click on Create Token button.
Provide a desired name to the token and proceed.
Copy the token as it will be the only time that you will be able to view it. After this step, it will be stored as a hash for your account protection in the Okta application.
Token Best Practice: Service Account
Okta API tokens inherit the API access of the user who creates them, so we recommend you create a “service account” user with only the permission levels you need for the token to perform the API tasks you require. In this case it can be "Read Only Administrator"
Note: API tokens are valid for 30 days and automatically renew every time they are used with an API request. When a token has been inactive for more than 30 days, it is revoked and cannot be used again. Okta Agents are also issued API tokens during installation which they use to access your Okta organization. Reference
Step 3 : Enable Genea + Okta provisioning integration on Genea.
Login to the Genea Web application and go to Integrations.
Find Okta and click 'Install.'
1. Provide your Okta domain and token (Optional).
If you want to configure your rules based on Okta groups then please provide the token created in your Okta application and the domain of your Okta application in the respective fields and click on the Install button.
If you just want to create a default rule and don't want to create groups based rules then you can click on "Install without Token"
2. Okta Integration Token
In the next step, you will be assigned a secured token for your Okta provisioning integration. Please copy this token as you will need it in the next step when we copy it onto your Okta web application.
Step 4 : Configure your Okta application.
Login to your Okta account as an admin.
Go to Admin-> Applications -> Add Applications-> Search for : “Genea Access Control”
Click on "Add"
Once the Genea Access Control app is add, click on 'Next' and go to the Sign-on Options from the Tab. If you want to configure the Single Sign-on (SSO) then follow this article or you can setup later. Click on "Done" to continue.
Please configure the API Integration In the Provisioning tab by clicking on the Configure Api Integration button.
Select the checkbox “Enable API Integration”.
Paste the API token that we generated in Genea into the API Token field. Click “Test API Credentials” to validate the connection.
Edit the App provisioning options and make sure that Create Users, Update User Attributes, and Deactivate Users are all enabled (boxes checked).
Click “Save” at the bottom of the provisioning page.
Step 5 : Configure provisioning rules
This is really important step since there must be at least one rule specified for each property for successful synchronization. All your properties will be listed on the rules section where you can manage rules for respective properties.
With provisioning rules, you can :
Map your organizational groups to Genea "door access groups"
Decide which "role" needs to be assigned
Decide whether newly on-boarded employees should automatically receive mobile key or not.
Manage access to multiple office locations
Simple Provisioning Rule :
You can have just one default simple rule where every employee being synced is granted common door access and a regular user role.
For example, you can define a rule where every employee being synced from Okta gets assigned to the "Employee" access group and to the "User" role.
As you can see in the below screenshot, in this case you don't need to add any conditions to the rule for a simple default rule.
Advanced Provisioning Rules
You can get more advanced with the rule engine to make sure right group of users in your organization gets the right access.
As shown below, based on your "Okta groups," you can assign appropriate doors access to appropriate users. If you have multiple office locations you can also choose which all employees gets synced to which all office locations.
You can drag these rules up or down to sets its execution priority. Rules are executed in order based on its priority, once one rule is matched and executed, rest of the rules will be skipped.
You can also add multiple conditions in a single rule as shown below. If you have multiple conditions in a single rule, you can choose either "match all" conditions or "match any" condition option.
Provisioning Rules When Apple Wallet is Installed
When Apple Wallet is installed, you can get more specific with the rule engine to make sure certain groups of users in your organization are enabled for Apple Wallet pass.
As shown below, Add Rule page will have option to select Apple Wallet. You can select BLE option too. Selecting both will have BLE and Apple Wallet both the passes (keys).
Summary of the rule table will have ability to see which rule has which mobile access assigned. Other functionality of rearranging and priority of the rule remains the same.
You can edit the rule and make necessary changes too.
Notes :
Please ensure to define rules for provisioning to work. If no rules are defined then any provisioning request from Okta will be dropped.
When already provisioned user gets updated in Okta, it will re-evaluate the rules and then apply the necessary updates. But if no rules matched in this scenario then that user will be de-activated in that property. For example, you have rule that "Any user that belongs to Employees Okta group gets assigned to Regular Employees access group in Genea". Once user have been created with this rule in Genea and then moved from this Okta group to Contractors Okta group for which we have no rules in Genea then this user will be deactivated in Genea.
UPDATE FLAGS
While setting up your Okta integration, you may choose to enable or disable certain user updates from Okta to Genea.
If your integration set-up includes a few basic and/or broad rules, or if you plan on changing user attributes manually within Genea after users have been synced via Okta, we recommend disabling the ‘Override Roles on Update’ and ‘Override Access Groups on Update’ update flags. If enabled, these User Update flags may override manual changes made to your users’ roles and/or access groups in Genea.
Delete User If No Rules Match: if changes have been made to a user’s profile within Okta that no longer qualify them for any of your integration rules, the user will be deactivated within Genea. IMPORTANT NOTE: This flag will only come into play during directory updates. If you deactivate or suspend a user within your directory, the user will automatically be deactivated within Genea, regardless of whether this User Update flag is enabled or not.
Enable Push Group (Recommended): If turned on then it allows to update the user profile real time
IMPORTANT NOTE: If your integration does not include a specialized rule for provisioning system administrators, we recommend disabling the ‘Override Roles on Update’ flag as system administrator privileges may be revoked for existing administrators during updates. To avoid losing administrative privileges while keeping this flag enabled, we recommend creating a specialized rule within your integration that will provision system administrators. Ensure that this rule is placed first within your rule priority list so that system administrators will be provisioned first, then remaining users will be matched to the following rules accordingly.
Step 6 : Sync users from Okta to Genea.
There are different ways we can begin syncing users from Okta to Genea. We recommend assigning Groups.
Group Based Access
You can either create new groups or use existing ones , based on your organization setup. Let's say you have Employees, Contractors and IT Admins.
Assign the Genea Access Control app to these groups and then assign users to these groups.
Okta allows multiple groups assigned to the user. When a user is a member of more than one group assigned to the application, Group priority determines the provisioning. Please read more about Okta groups and its priority feature here.
Multiple Offices
If you have multiple offices at multiple locations we recommend you create different "Groups" to sync only specific users to specific locations. Or you could leverage user's city, state or zip attributes within the provisioning rules you define on Genea side.
Once you have assigned new employees to the Genea Access Control app, navigate back to Genea. Click on the Employees List and refresh the page. Your employees should have imported automatically with appropriate Access Group permissions.
Notes :
If you already have Genea Access Control installed with all of your employees prior to enabling this integration, it will automatically link your existing employees between Okta and Genea. It will not create duplicate records as it's all based on unique email addresses.
Migration
If you want to migrate your existing Okta Genea Access Control app to new Genea Access Control app then follow these migration steps mentioned on this article. This article is only relevant if you have added the Genea Access Control Okta app before 01/30/2020.
Troubleshooting Tips
Genea app does not support modifications to the username or email address.
When users are deactivated in Okta, they will be deactivated in Genea. Users will not be able to login to the application, but their data will remain available as an ‘inactive user’.
If you need assistance or have any questions about this integration, please feel free to reach out to us at acsupport@getgenea.com