Configuring SAML with Okta

Set up the Okta integration in Bonusly

Navigate to your Admin Settings page, then navigate to Integrations
Click on Okta
Set up the Okta integration by:
1. App ID: Save this value (you will need to enter it in Okta when you complete the integration on their end).
2. Check the "Automatically Configure from Metadata" box
3. Copy the IdP Metadata URL and IdP Issuer (Entity ID) from Okta's Support article here and paste them into the corresponding fields in Bonusly.
4. Click save

Set up the Bonusly integration in Okta

Travel to Okta's Bonusly App
Click "Add Integration":
Modify your General settings as you wish and click "Next":
Choose the SAML 2.0 option
1. You can leave the relay state option blank in Okta if you don't need to redirect users to a specific URL after authentication. If left blank, users will be redirected to a default or home page determined by the service provider’s configuration after successful authentication.
2. Under "Advanced Sign-on Settings," enter the App ID you saved from your Okta app in Bonusly earlier.
3. Under "Credentials Details," ensure you select "Email" from the dropdown:
4. Click "Done."

Test it out!

IdP-initiated SSO:
1. Log out of Bonusly
2. Log in to your IdP (e.g. Okta, OneLogin, etc)
3. Click on the Bonusly app in your app panel
SP-initiated SSO:
1. Log out of Bonusly
2. Visit the URL https://bonus.ly/saml/APP_ID/index
  1. Make sure you replace APP_ID from the above link with the App ID from the SAML Integration page in Bonusly!

Restricting Login Methods

Once you have confirmed that your configuration is correct and the integration is working, you can set login methods to "Restrict to Single Sign On" from your Admin > Company > Recognition settings page.

To restrict to SAML SSO only:

Go to Manage Admin Settings > Company > Account Settings
Scroll down to "Security" and select the check box to only allow users to login via single sign on.
Select the "Save settings" button.

Enable User Management Through Okta

What is a user management integration?

A user management integration will keep your Bonusly user list in sync. This is a great way to reduce the administrative overhead of your employee recognition program. As you add, edit, or remove employees internally, your Okta integration will make the corresponding changes in Bonusly. This Okta integration is separate from the Single Sign-On integration, which you can learn more about here.

How does the user management integration with Okta work?

IMPORTANT❗️ If you aren't familiar with Okta and user provisioning, we suggest connecting with your representative at Okta. Bonusly cannot support troubleshooting for Okta and can only support the integration connection.

The Okta user management integration is done via API. You can view our API documentation here.

Here is a list of the actionable items you can accomplish with this integration:

Creating users
Activate deactivated users
Update user information

The attributes you can send to the API when creating or updating a user are names defined by SCIM. We map those attributes to the corresponding fields on our User model.

Below is a list of SCIM attributes accepted by our API, followed by the field on User that they map to:

userName → email
name.givenName → first_name
name.familyName → last_name
externalId → external_unique_id
addresses.country → country (when addresses.type is work)
urn:scim:schemas:extension:bonusly:1.0:User.hired_on (optional) → hired_on
urn:scim:schemas:extension:bonusly:1.0:User.date_of_birth (optional) → date_of_birth (Bonusly will only show MM-DD but YYYY-MM-DD is required for syncing purposes)
urn:scim:schemas:extension:enterprise:1.0.department → custom_properties.department
urn:scim:schemas:extension:bonusly:1.0:User.location → custom_properties.location
urn:scim:schemas:extension:bonusly:1.0:User.employee_id → custom_properties.employee_id
urn:scim:schemas:extension:bonusly:1.0:User.role → custom_properties.role
urn:scim:schemas:extension:bonusly:1.0:User.job_title → custom_properties.job_title
urn:scim:schemas:extension:bonusly:1.0:User.division → custom_properties.division
urn:scim:schemas:extension:bonusly:1.0:User.business_unit → custom_properties.business_unit
urn:scim:schemas:extension:bonusly:1.0:User.user_mode → user_mode
urn:scim:schemas:extension:bonusly:1.0:User.manager_email → manager association

Note the SCIM attributes above are case-sensitive.

You can learn more about each API attribute here.

What does the integration process look like?

Create an API access token:
1. To integrate Bonusly and Okta, you must have an API access token* for an active Bonusly account. You can learn more about creating an API access token here.
  1. IMPORTANT❗️If you decide to create a read-only token, your integration will not be able to create, update, activate, or deactivate users in Bonusly.
Add the API access token in Okta:
1. In the “Provisioning” tab of the Bonusly app page, click on “Configure API Integration.”
2. Check the box next to "Enable API integration," enter your Bonusly API access token, and click "Save."
3. Edit Integration set up:
  1. Click on “To App.”
  2. Check the checkboxes for “Create Users,” “Update Users,” and “Deactivate Users” to enable those actions.
  3. Select "Save."

That's it! Okta will now provide automated user management for your users in Bonusly. Hooray!

Questions? Send us a note to [email protected]; we'd be happy to help!

Was this article helpful? Let us know by rating it below with an emoji and sharing your feedback!

How to Configure SAML SSO with ADFS

How to set up Single Sign On with SAML