Table of contents

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

Okta_Provisioning_in_Happeo_1.png

 

Happeo supports syncing your Users and Groups from Okta using the SCIM Provisioning protocol (System for Cross-domain Identity Management) that Okta offers. Please see this article to learn more about how Okta works with SCIM. 

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.

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 need to create your Happeo instance using a Google user account tied to your organization. To find out how to create an organization please see the article here

Okta_Provisioning_in_Happeo_4.png

Configuration instructions

Verify your domain

  1. Go to Happeo's Admin Settings by clicking on your Happeo avatar > Admin Settings
  2. Click on Security > Domain Verification and add your company domain there
    1. 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

Okta_Provisioning_in_Happeo_3.png

Okta_Provisioning_in_Happeo_12.png

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

    1. Go to Happeo's Admin Settings by clicking on your Happeo avatar > Admin Settings
    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

You will be prompted to:

  1. Go to Domain Verification and verify your domain (as detailed in the previous section)
  2. Open your Okta environment and use the Base URL and API Token credentials (that you are given in the pop-up after clicking on the Setup button for the Okta Provisioning item) as your Happeo integration provisioning settings

Install the Happeo App in Okta

  1. In Okta, go to Admin Settings
  2. In the Admin Console, go to Applications > Applications
  3. Click Browse App Catalog and search for Happeo
  4. Click Add integration > Done. This will create the integration
  5. After the integration is created, click on the Provisioning tab in the Happeo App Overview
  6. In the Integration tab on the left panel, click on Configure API Integration
    1. Also, make sure to check the Enable API Integration check box
  7. Enter the base URL and the API token received from Happeo Admin Settings from above ("Activate Okta Provisioning and obtain credentials from Happeo to add to Okta")
  8. Click Test API Credentials to test if the Okta integration can connect to Happeo's SCIM API
    1. If successful, you will see a message stating “Happeo was verified successfully!”
    2. If Happeo was not verified successfully, please contact our support team
  9. 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 our support team to have this enabled.

  1. Go to Okta Admin Settings > Applications > Sign-on page
  2. Open up the Identity Provider metadata link
  3. Then go to Happeo > Admin Settings
  4. And then click on Security > Single sign-on settings. You will have 2 fields to fill in:
    1. Copy the URL of the Identity Provider metadata link (in Okta) into the SAML metadata URL (in Happeo)
    2. Copy the entityID (in Okta) into the SAML entity ID (in Happeo)

Okta_Provisioning_in_Happeo_4.png

Optional: Enable the Happeo Organizational Chart using Okta

Setting up the manager id relation to enable the Happeo Organizational 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 Organizational 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 Admin Settings > Directory > Profile Editor > Users
  2. Click on the Okta user profile > Add attribute
  3. Fill in the necessary fields
    1. Data type - Linked object
    2. Display name - Manager
    3. Variable name - Manager
    4. Description - The user's manager (or any description you wish to add)
  4. Click on Save

Okta_Provisioning_in_Happeo_5.png

You can then Go to the User Profile page for each of the users and edit the Manager field by selecting a manager user. You can do this by navigating to:

  1. Directory > People
  2. Select the user profile you wish to edit the Manager field for
  3. Click on Profile in the user menu
  4.  Scroll down until you see Linked object
  5. Click on Edit
  6. Type in the manager for the user
  7. Click on Save

Okta_Provisioning_in_Happeo_6.png

Okta_Provisioning_in_Happeo_2.png

In the Okta Profile field 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

Okta_Provisioning_in_Happeo_7.png

Assign Happeo to an individual user

  1. Navigate to Applications > Applications
  2. Click on the Assignments tab
  3. Select Assign
  4. Click on Assign to People
  5. Click on Assign next to the user(s) you wish to assign to Happeo
    1. Note: Make sure the users you assigned have all properties filled in
    2. 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
  6. If all looks good, click on Save and go back

Assign Happeo to a group of users

You can also assign groups to Happeo. This means all users in that group will be synchronized 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.

  1. Navigate to Applications > Applications
  2. Click on the Assignments tab
  3. Select Assign
  4. Click on Assign to Groups
  5. Click on Assign next to the group(s) you wish to assign to Happeo
    1. Note: You may be asked to fill in additional information to assign the group to Happeo. Please fill in these details
  6. Once all details have been filled in, click on Save and go back

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

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.

Then, navigate to:

  1. Applications > Applications
  2. Click on the Push Groups tab
  3. Click on Push Groups and:
    1. Add the groups by name
    2. Or groups by rule that you want to provision in the Happeo App
  4. You can then click on Save to push in the group(s) you've selected

Okta_Provisioning_in_Happeo_8.png

Then, you can navigate to:

  1. The Sign-on tab in Applications > Applications
  2. Click on Edit at the top
  3. Scroll down to Credential details
  4. Next to Application username format, select email as the format
  5. Click on Save

Okta_Provisioning_in_Happeo_9.png

Lastly, verify everything works as expected in Happeo. The users and groups you assigned should be provisioned. To do so, you can take a look at the following:

  1. Check Happeo > Admin Settings > Users Management and Group Management
  2. 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 Organizational Chart
  3. In the Group Management tab, also check the Permissions settings
    1. Click on a group’s three-dot menu on the far right of each listed group's row
    2. Change permissions for Page and Channel creation as needed and verify that permissions work as expected

Additional 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 (Applications > Applications > Provisioning). 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

Okta_Provisioning_in_Happeo_10.png

Okta_Provisioning_in_Happeo_11.png

Happeo App / Tile in Okta

When clicking on the Happeo App in Okta, it will direct you to app.happeo.com, as opposed to your custom login page. This, unfortunately, cannot be changed. However, the icon can be hidden in Okta. 

A custom bookmark can then be made which can be linked to the custom URL / login page. 

Creating an Okta bookmark

Bookmark apps in Okta are used to point users to a certain web page. They operate normally on any browser and do not require passwords.

  1. Be sure to log into the Okta portal as an Admin
  2. Expand the Applications drop-down in the left pane, then click on Applications
  3. Click on Browse App Catalog
  4. Search for Bookmark App
  5. Select it from the list of results
  6. Click on Add in the left pane
  7. Choose an app name (this will be the display name)
  8. Copy the URL you're trying to link directly to into the URL box
  9. Click on Save

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.

 

 

 

Previous
Next
8045269963153