Okta Provisioning in Happeo

This guide provides the steps required to configure Okta Provisioning for Happeo

Okta Provisioning is only included with Happeo’s Recommended and Custom packages. Please reach out to your CSM if you would like to upgrade your Happeo package.

Happeo supports syncing your users and groups from Okta using the SCIM Provisioning protocol (System for Cross-domain Identity Management) that Okta offers. To learn more about how Okta works with SCIM, please see this article

If you have feedback related to our testing process or suggestions on how this can be improved or any other remarks, please feel free to reach out to our support team.

Table of contents

  1. Features
  2. Prerequisites
  3. Configuration instructions
    1. Verify your domain
    2. Activate Okta Provisioning and obtain credentials from Happeo to add to Okta
    3. Install the Happeo App in Okta
    4. Setup SAML SSO login
    5. Optional: Enable the Happeo Organisational Chart using Okta
    6. Assign users to Happeo
    7. Provisioning groups from Okta to Happeo using Okta’s Push Groups feature
  4. Extra observations related to Okta SCIM Provisioning
    1. User provisioning
    2. Groups provisioning
  5. Troubleshooting

Features

The following features are supported by Happeo at the moment:

  • Create users – Create or sync a user in Happeo when assigning the app to a user in Okta
  • Update user attributes – If a user's attributes are updated in Okta, they will also be updated in Happeo
  • Deactivate users via Okta sync – Deactivates a user's Happeo account when the user is unassigned from the Happeo app in Okta or their Okta account is deactivated. Accounts in Happeo can be reactivated if the user is assigned back to the Happeo app in Okta
  • Push Groups – Groups and their users in Okta can be pushed to Happeo. Groups synched from Okta can be used to set Page and Channel creation permissions. These groups can also be added as Channels or Pages members

Prerequisites

To enable Okta Provisioning, you will first need to create your Happeo instance using a Google user account tied to your organisation. To find out how to create an organisation please see the article here. Note: You will need to be logged in with an administrator account.

Configuration instructions

Verify your domain

  1. Go to Admin Settings in the top-right corner
  2. Click on Security > Domain Verification and add your company domain there. Please note it can take up to 48 hours for the DNS settings to propagate and hence your domain to be verified by Happeo

3.   Once the TXT record has been made, make sure to log in to your DNS provider account and        add a new TXT record for the domain you're verifying with the value provided

Activate Okta Provisioning and obtain credentials from Happeo to add to Okta

  1. Go to Admin Settings in the top-right corner
  2. Click on Integrations
  3. Click on the Setup button for the Okta Provisioning item
  4. You will be prompted with a set of credentials needed for Okta’s side of the setup

Install the Happeo App in Okta

  1. Go to Admin Settings in the top-right corner
  2. In the Admin Console, go to Applications > Applications

3.   Click Browse App Catalog and search for Happeo

4.   Click Add and Done. This will create the integration

5.   After the integration is created, click on the Provisioning tab

6.   In the main panel, click on Configure API Integration

7.   Also, make sure to check the Enable API Integration check box

8.   Enter the base URL and the API token received from Happeo Admin Panel from above                ("Activate Okta Provisioning and obtain credentials from Happeo to add to Okta")

9.   Click Test API Credentials to test if the Okta integration can connect to Happeo's SCIM API

      a.   If successful, you will see a message stating “Happeo was verified successfully!”

      b.   If Happeo was not verified successfully, please contact Happeo's customer support

10.  Press Save in the bottom-right corner

Setup SAML SSO login

Happeo supports SAML SSO SP initiated, which means the login needs to start from within the Happeo login page

You will need a custom login page with SAML login enabled. Please contact Happeo's customer support to have this enabled

  1. Go to OktaApplications Sign-on page
  2. Open up the Identity Provider metadata link
  3. Open Happeo > Admin Console > Security > Single sign-on settings. You will have 2 fields to fill in:
    1. Copy the URL of the Identity Provider metadata link into the SAML metadata URL
    2. Copy the entityID into the SAML entity ID

Optional: Enable the Happeo Organisational Chart using Okta

Setting up the manager id relation to enable the Happeo Organisational Chart:

In your Okta User Profile, if the manager ID field is populated with the user’s Okta ID or with the user’s email, the manager will be automatically provisioned in Happeo. You can see this under the Happeo Organisational Chart.

If the manager ID field is not populated in the User Profile and you want to provision the field in Happeo - in the User Profile in Okta, you will need to add a custom attribute to the User Profile.   

  1. Go to Okta > Profile Editor > User and click on Add attribute

2.   Click on Save

      a.   Go to the User Profile page for each of the users and edit the Manager field by selecting              a manager user

In the Okta Profile Editor in Happeo, you will see a custom property called managerId. This is mapped in Okta's Mappings as described in the next section.

Assign users to Happeo

  1. On the Assignments tab in Okta, add users to the app integration. Make sure the users you assigned have all properties filled in
    1. Note: When assigning a user to Happeo, a modal will pop up with all the properties of that user. These properties will also appear in Happeo, so, please check if any properties are empty
    2. Another note: You can also assign groups to Happeo. This means all users in that group will be synchronised into Happeo, but not the group themselves. In other words, when you need to assign many users to Happeo, you can assign an entire group that will sync all the users to Happeo, however, you don't necessarily need to have the group itself in Happeo

Provisioning groups from Okta to Happeo using Okta’s Push Groups feature

  1. First, make sure that all users that are part of the groups you want to provision to Happeo are already assigned to the Happeo app, as described in the previous section
  2. Then, on the Push Groups tab, add the groups (either by name or by rule) that you want to provision in the Happeo App

3.   Click on the Sign-On and click Edit

4.   Next to the Application user name format, choose email and click on Save

5.   Verify everything works as expected in Happeo

      a.   You should be set up and the users and groups you assigned should be provisioned

      b.   Check Happeo > Admin Settings Users Management and Group Management

      c.   Also check the People section (from the navigation bar) > search and navigate through                users' profiles making sure that the needed information is filled in. Make sure to also                      check the organisational chart

      d.   In the Group Management tab, also check the Permissions settings

            a.   Click on a group’s three-dot menu on the far-right of each listed group's row

            b.   Change permissions for Page and Channel creation as needed and verify that 

                  permissions work as expected

Extra observations related to Okta SCIM Provisioning

User provisioning

  • Deactivating a user in Okta automatically unassigns the user from the Happeo app
  • Reactivating does not send any access permission requests to us. Reassigning the user does send us an activation request
  • Suspending an active, assigned to app user does not send any request to us. The user remains assigned to the app
  • Unsuspending an assigned to app user does not send any request to us
  • Deleting a user does not send any request to us
    • Note: Only deactivated users can be deleted
  • There is a setting related to Deactivating users. If you disable that, then Happeo will not get an active: false patch request when a user is deactivated. Therefore, please do not deactivate that

Groups provisioning

  • The Okta ID comes as an external ID when provisioning users, but not when provisioning groups. Therefore, we can only rely on the display name of the group and your customer ID to uniquely identify groups
  • At the moment, custom group attributes cannot be provisioned. Only the group name and members. This is something that we have verified with Okta support and they plan to add support for this, but no ETA yet. Therefore, for attributes such as the group’s email, we cannot provision. The Happeo workaround, as we require emails to be present for groups, is to generate a no-reply-group-name-random-string group email for your groups. These will be updated once we will be able to receive custom group attributes from Okta
    • Note: The email is autogenerated by Happeo. If your groups have an email set in Okta and you sync that group to Happeo, the group will have another email in Happeo. For instance, something like no-reply-groupName1234567@happeo.com
  • Only users that have been assigned to the application are sent as members of a push group
    • If you want to use the Push groups functionality from Okta - before you push the groups, please make sure that the users in the group you wish to push have been assigned to the Happeo App from the Assignments tab
      • Please see the above section called "Assign users to Happeo"
  • Deleting a member from a group does not make Okta send Happeo an update. Only clicking on Push Groups > Group name > Push now sends us the update
  • When a group from Push Groups is deleted from Directory > Groups, a delete request is sent to us
    • This means that if you delete a group in Okta, it will also be deleted in Happeo
  • When a group from Push Groups is Unlinked, there are 2 options. Please use the recommended one

Troubleshooting

Happeo does not automatically log out a user that was unassigned from Okta, but as soon as the user tries to perform any action on the website, it will log them out with an error message about an inactive session.