Aquera to Okta Integration Guide

ATTENTION: Any Aquera apps that were added to your Okta org before August 31, 2018 that need to utilize the profile mastering functionality will need to re-authenticate under the API Inetgration tab.

All customers who want to use profile mastering need to contact Okta support to enable the following feature flags to get this feature to work:

  • ALLOW_BOTH_PROFILE_MASTERING_AND_PUSH
  • ATTRIBUTE_LEVEL_MASTERING

 

Introduction

Aquera provides a cloud service for integrating Okta with applications to support Identity Lifecycle Management. This includes importing users from applications to setup the application assignments in Okta, deactivating users in applications when they are deactivated in Okta, syncing passwords into those applications for password reset and random password support, updating users with changes in Okta, and creating users in applications when Okta assigns the user to an application. This guide will describe the setup of Aquera and Okta to provide this functionality.

Prerequisites

In order to implement Aquera with Okta you will need to have a tenant in Aquera. This can be done by visiting https://admin.Aquera.io and registering.  Next you will need an instance of Okta.  You can get access to an Okta instance by visiting https://Okta.com.  Next you will need to get the Aquera Application enabled for your Okta tenant.  Email support@Okta.com the following: “Please enable the Aquera and Aquera (Basic Auth) applications in my Okta org which is xxx.Oktapreview.com”. Once Okta support enables your Aquera App you are ready to go. Finally you will need an application, like targetprocess.com or logmeinresuce.com or any other SaaS or on-premises application you would like to perform identity lifecycle management against.

Deploying the On-Premises Aquera Agent (Optional)

In order to manage users in applications that are on-premises you will need to install the Aquera agent somewhere in your network that has access to your application. The Aquera agent will run on Windows 2008 R2 or later server. The installer can be found in the Agent tab of the Aquera Admin Console. Download the installer and run it on your Windows Server. A secret key is available in the Aquera Admin console on that same. Use this key when installing the Agent. For redundancy purposes multiple instances of the Aquera Agent should be installed. The Agent can be installed on the same machine that the AD Agent is installed on which will not increase the number of Windows on prem instances required for the Okta implementation. If the Windows Server that the Agent is installed on uses some type of whitelist of IP addresses that outbound calls can be made to, this list can be obtained from this page on AWS https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html.

Creating the Application in Aquera

In the Applications tab of the Aquera Admin console select “Add Application” to launch the catalog browser. Select the application to be added. Give the application a name and description. If the application requires information about the specific tenant that will be connected to, supply this information in the Tenant text box. The Tenant help section will describe specific help for the application identifier. Make note of the type of Authentication the application supports. It will be either username/password (Basic) or Token. If there are other attributes that need to be configured they will have descriptions and help to indicate their purpose and what values are required. Save the application. The application is now in the network ready to use.

Creating the Application in Okta

In the Okta Admin console in the Applications tab, click on the Create application button and type in “Aquera”. Aquera and Aquera (Basic) will appear among other supported Aquera apps. Based on the Token information described above pick the appropriate Aquera app. Give it a name and keep the default settings for the sign on mechanism (this application will be used for provisioning only). Once created the application will have a Provisioning Tab. Select this tab and enable the API Integration. In the BaseURL fill in the url defined in the application in Aquera. This can be copied into the buffer by clicking on the copy button in the Aquera Admin console for the desired application. Next fill out the username and password or the access token. Follow the Token instructions in the Aquera admin console to gather the right credentials. Click on the Test button and then save the application. The application is now setup in Okta.

The next step is to create the custom attributes for the application user for the application just created. In the provisioning tab under the To Application section at the bottom of the screen click on the Profile button to navigate to the application user profile page. Next click on the Add Custom Attribute. In the Aquera application Schemas section a list of attributes that the application supports is displayed. There are copy buttons for the name of the attribute and the namespace. Copy these into the custom attribute dialog. Also make a note of the type of the attribute and set the correct value. Do this for all of the attributes. It is worth noting that custom attributes for an application will be placed in the external namespace urn:ietf:params:scim:schemas:ian:2.0:User in the SCIM object. As custom attributes are added to the user object in the application either through upgrading the application or customizing the user object directly, they will appear in the object sent to Okta through the import process. They also will be available to push to when creating and updating users. As the application changes these additional attributes are seamlessly handled by the Aquera SCIM gateway.

Importing Users into Okta

Click on the Import users button in the application Import tab. This will connect from Okta to Aquera to the application to GET all of the users in the application. Once the import is complete, assign a new or confirm an existing assignment. The user will now appear in the assignments tab. Click on the edit button to review the details of the user attributes. All of the custom attributes along with the standard ones should have values.

Automating the Importing of Users into Okta

To import users from the application into Okta on a scheduled basis a few settings have to be made. First setup a profile map to copy values from the application user object into the Okta user object. This profile map can be found by navigating to the Provisioning tab and selecting the Profile Map button. To both copy attributes during creation as well as on updates the profile mastering setting will have to be enabled. This is at the bottom of the Import Provisioning section of the application. When enabled values will be copied into the Okta user attribute whenever the user is updated in the application on the next import. Finally setup the schedule in the application tab. The schedule can be as frequent as 1 hour. When these imports are run the user that is now assigned this application will have the application assigned to them on their dashboard. This allows Okta to show only users who have accounts in the application chicklets on their dashboard.

Creating Users from Okta

To create a user in an application, go to the assignments tab in the application and assign a new user to the application. A dialog box will appear. Fill in all of the appropriate values and click ok. This will assign the user to this application which will cause a create message to be sent from Okta to Aquera to the application.

Automating the Creation of users from Okta

To automate the assignment of users into the application from Okta three configurations will need to be setup:

 

  1. Create a profile map that will copy values from the Okta user profile into the application user profile. This profile map can be found in the Directory->Profile under the application just created.
  2. Create a group or use an existing group to assign the application to. The group assignment will have the option of setting values based on that group. All users that are assigned to the application will get those values.
  3. Create a group assignment rule in the Groups tab. This configuration allows for defining properties of the Okta user attributes to determine which user will be assigned to the group. Once assigned the user will be then provisioned into the application.

 

Migrating Imported Users to Group Assigned Users

When an application is first onboarded, users must be imported into Okta to bootstrap the setup. Once steady state group rule assignments have been setup these imported users must be converted over to the group assigned. Once done, users moving in and out of groups will determine the values the user will get in the application…as well as being removed from the application if they are no longer in the appropriate group. To perform this migration in the application assignment tab, select the convert user to groups.

Updating Users from Okta

In the profile map for the “Okta to application” attribute assignments the option of “copy on create” and “copy on both create and update” are available. When the copy on update is enabled, any change to the Okta user attribute will trigger a profile update push to the application.

Deactivating Users from Okta

When a user is unassigned from an application, a message is sent to Aquera and then to the application to deactivate or delete the user from the application. In the case where content is assigned to the user account that needs reassignment, Aquera will update the application with the new assigned owner of the content. Depending on the application this feature is configured in different ways. In the configuration of the application attributes settings are available to manage the movement of documents to the specified user.

Syncing Passwords from Okta

In the application provisioning tab under the “to application” section select the sync password check box. There are two settings. One to push random passwords, the other to push the Okta password. If the application utilizes SWA then by pushing a random password, Okta can be made to setup these credentials for the user without them actually knowing the password being used. In the case of applications where users will log into the application themselves outside of Okta SSO because it is a thick non-browser based application, pushing the Okta password can give the user a single login credential experience and a self-service password reset when the password is forgotten.

Task Management and Error Handling

All communication between Okta and Aquera and the Application is done with Synchronous commands. If there are any issues they are reported back to Okta and logged as tasks in the admin console. For example, if a user was attempted to be created in an application and some of the required fields were missing, this would create a task in the Okta admin console that needs to be addressed. Editing the user record and resubmitting will remedy the assignment error. Similarly, when a user is updated in Okta and that triggers a user update that contains bad data or if the connection to the application is down, a task will be created and the administrator can make changes to the user profile map to remedy the error and resubmit.

Conclusion

As described above, once the Aquera application is added to the network and integrated into the Okta as an application all of the features of identity lifecycle management are available just as if Okta was managing those applications in the OIN.