Okta Provisioning

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

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. 

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

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 checkbox
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

Update Okta security token

On August 24th, 2023 we released an improvement to our security token, further increasing security between Happeo’s connection to Okta. 

Please note that if you do not follow these 5 steps before then, your integration with Okta will stop working. As a result, new users will no longer be provisioned into Happeo, and new fields will not be synced, but you will still have access to the platform.

1. Go Happeo’s Admin panel by clicking on your avatar and then Admin Settings
2. Click on the Integrations section and look for the toggle slider that says Okta
3. Slide the toggle off, wait a minute, then slide it on again. A new security token will appear
4. Copy and paste this security token into Okta’s admin settings
   1. For a more detailed overview, please see the section above starting from "Configuration instructions" – it’s the same as when you initially set up Happeo
5. Press the Test button to test the connection
6. If everything works, save it, and you’re done

In the unlikely event that the test fails, please cancel and continue to use the old token and contact our support team.

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)

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

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

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

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

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

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

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