Using Group Push

Group push allows admins to take existing groupsGroups allow you to organize your end users and the apps they can access. Assigning apps to large sets of end users is made easier with groups. and their memberships in Okta, and push them to provisioning-enabled, third-party applications. These memberships are then mastered by Okta. The most important concept to understand in pushing groups is that pushed groups are managed from Okta. Making changes from the target appAn abbreviation of application. Essentially, it is a web-based site used to perform any number of specific tasks, and requires authentication from end users by signing in. causes a misalignment with Okta and a number of problems.

While Group Push adds these groups to third-party apps, it does not create groups in Okta. To create groups in Okta, use the Groups page, and to add individual apps, use the Applications page.

Requirements

  • You must have provisioning enabled in the target app. If not enabled, you will be prompted to do so.
  • Any group members that you wish to push to the target app MUST be previously provisioned and assigned to the target app. As an Okta-mastered group, changes should never be made from the target app.
  • API access must be enabled in the target app.
  • Because this process is always Okta-mastered, you cannot push a group name that already exists within the target app. However, G Suite, Box, Jive, and Active Directory allow you to link their existing groups to Okta. See Enhanced Group Push for details.
  • Confirm that the relevant group members are imported in Okta, and provisioned for the target app.

Note: UsersIn Okta literature, we generally refer to "users" as the people who serve as Okta administrators. When we refer to "end users" we are generally referring to the people who the administrators serve. That is, those who use Okta chiclets to access their apps, but have no administrative control. who show as inactive in Okta are not pushed to the downstream app. Inactive users must be reactivated and then the group repushed. If the inactive user is part of more than one group, they must be repushed to all groups in which they are members.

Using Office 365 as our example,

  1. Access your Okta instance of O365.
  2. Within the app, choose the Push Groups tab.
  3. Click the green Push Groups button to add one or more groups. Groups can be added by name or by rule. Keep in mind that, unless the app is one listed under Enhanced Group Push, you cannot push groups or group names that already exist in the target app.
  4. If you keep the Push group memberships immediately default (which is checked), the selected membership is immediately pushed to the target app.

  • Find groups by name provides a simple search field with auto complete capability.
  • Find groups by rule is a helpful option when there are a large number of groups or a known naming convention for them. The wizard allows you to create a rule and specify its search criteria. Once created, the rule name is shown under the By rule filter and the found groups are listed under the Group in Okta column.

  1. Once populated with selected groups, use the Bulk Edit button to delete or deactivate the active groups. Simply select one or all of the groups from the list.
  2. You can also delete and deactivate specific groups by clicking the Active / Inactive status button.
  • Deactivate group push: pauses the synchronization of groups, retaining their appearance in the app (e.g., Box). In this mode, you're able to keep adding new members to the group, but those changes won't appear in the target app.
  • Unlink pushed group: permanently removes the group from Okta and the app (e.g., Box). A message appears with two options for deleting groups:

Delete the group in the target app — this option deletes the group and all its associated memberships.
Leave the group in the target app — this option tells Okta to stop pushing memberships, but the group remains in the target app.

  • Push Now serves to "force" a push in the rare occurrence when the state of Okta and the target app are no longer in sync.This action performs a full overwrite of the overall membership and makes Okta the master for the group. The exception to this is Active Directory, which only pushes the newest members to the group, and does not overwrite overall membership.

    The Information button (alongside the Active / Inactive status button) displays creation information and group type. When an error occurs, it provides helpful troubleshooting information. See Troubleshooting details below.

Enhanced Group Push

Enhanced Group Push allows you to push to existing groups in specific apps. As stated under Requirements, you cannot push a group name that already exists within the target app, but these apps allow for the enhanced capability. Note that Okta remains the master of these exchanges.

Current Enhanced Group Push is available for the following apps in Preview orgs only:

G Suite, Box, Jive, Active Directory, Jira, Jira On-Prem, Adobe CQ, DocuSign, Smartsheet, Org2Org, Workplace by Facebook, Slack, Dropbox for Business, ServiceNow UD.

For details specific to AD, see Active_Directory_OUs, below.

Note: Currently, this option is only available for the listed applications, but Okta will periodically add this functionality to more and more provisioning-enabled apps.

Using G Suite as our example,

  1. Access your Okta instance of G Suite (Google Apps).
  2. Click the Refresh App Groups button to update any imports or changes that occurred in the third-party app. This ensures that all groups from the target app are represented in Okta.
  3. Click the Action button (Group Push Settings) if you want the ability to rename a group in the third-party app when linking.
  4. Choose the Push Groups tab.
  5. Under the By name column, use a keyword to find the group in Okta.
  6. Once found, look to the Match results & push action column. Use the drop-down menu to
  • Create Group: This group does not exist in the target app, but can now be pushed from Okta to the app. This is group push without enhanced functionality.
  • Link Group: Displays a drop-down menu to find an existing group in the target app by keyword. Once found, this group is linked to Okta and shown under the Group in Google Apps column.

Active Directory OUs

When you choose a group in Okta to push to AD, you must specify the target OUAn acronym of Organizational Unit. Organizational units are Active Directory containers into which you can place users, groups, computers, and other organizational units. It is the smallest scope or unit to which you can assign Group Policy settings or delegate administrative authority., and pre-select it on the Settings tab of your Active Directory instance.

To pre-select the target OU,

  1. From the AdminAn abbreviation of administrator. This is the individual(s) who have access to the Okta Administrator Dashboard. They control the provisioning and deprovisioning of end users, the assigning of apps, the resetting of passwords, and the overall end user experience. Only administrators have the Administration button on the upper right side of the My Applications page. Dashboard, click to the Directory drop-down menu.
  2. Select Directory Integrations.
  3. From the Directory Integrations page, click the Active Directory instance.
  4. From the Settings tab, scroll down to the Import and Account Settings section.
  5. From the Group OUs connected to Okta window, chose the appropriate domainA domain is an attribute of an Okta organization. Okta uses a fully-qualified domain name, meaning it always includes the top-level domain (.com, .eu, etc.), but does not include the protocol (https). and container.

To specify a target OU,

  1. From the Admin Dashboard, click the Active Directory instance.
  2. Select Directory Integrations and choose the AD instance.
  3. From the Push Groups tab, select the By name filter.
  4. Click the Push Groups drop-down menu and choose Find Groups by name. The Push Groups by Name page appears.
  5. Scroll down to the Find Group and Push group to the following OU to specify the groups you pre-selected.
  6. From the Admin Dashboard, click to the Directory drop-down menu.

Group Push Operations

Group Push (GP) allows admins to take ownership of third-party, target apps in Okta. This is done by either pushing Okta groups to target apps (GP) or by using enhanced Group Push (GPE) to import groups from target apps and linking them to Okta. The table below details the supported operations and how they appear in Okta.

Diagnosing Errors

When an error occurs, alerts appear to diagnose the problem. An red error panel and menu appear to list possible issues.

  • The red Information button displays the "time of failure" details and the probable cause.
  • The Retry All Groups appears and allows you to simultaneously re-push the groups after corrections are made.

Troubleshooting

Please note that users who show as inactive in Okta are not pushed to the downstream app. Inactive users must be reactivated and then the group repushed. If the inactive user is part of more than one group, they must be repushed to all groups in which they are members.

The most important concept to understand in pushing groups is that pushed groups are managed from Okta. Making changes from the target app causes a misalignment with Okta and a number of problems. Some can be diagnosed through the Errors page, while others may not.

Groups appear in the target app without their users

If you have successfully pushed a group to the target app, but the assigned group members do not appear, verify that one of the following is true:

  • The target app has been added to the new group.
  • All group members of the new group are assigned to the target app (even if the group itself was not yet assigned).
  • All group members appear as users in the target app.

If some group members are assigned to the target app and others are not, only successfully assigned members will appear in the target app.

A group has been deleted directly from the target app

To recover, you must delete the pushed group and reinstate the target app memberships.

  1. Click the Active / Inactive status button and choose Delete pushed group in app.
  2. Choose the Leave the group in the target app option.
  3. Run an import from the target app.
  4. Retry the push.
Top