Skip to main content

How to Configure SAML SSO and User Provisioning with Okta

Our Okta integration can be used both for single sign on and user management purposes!

Updated over 2 weeks ago

You can also refer to Okta's setup instructions to enable this integration!

This article is best for:

- Global Admins

In this article:

Configuring SAML with Okta

Set up the Okta integration in Bonusly

  1. ​Navigate to your Admin Settings page, then navigate to Integrations
    ​

  2. Click on Okta
    ​

  3. 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

  1. Travel to Okta's Bonusly App

  2. Click "Add Integration":
    ​

  3. Modify your General settings as you wish and click "Next":
    ​

  4. 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!

  1. 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

  2. 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:

  1. Go to Manage Admin Settings > Company > Account Settings​

  2. Scroll down to "Security" and select the check box to only allow users to login via single sign on.
    ​

    ​

  3. 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.

What does the integration process look like?

  1. 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.

  2. 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."
        ​

How do I map the correct attributes?

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

Note the SCIM attributes above are case-sensitive. You can learn more about each API attribute here.

To map them correctly from Okta, you'll need to go to the Profile Editor for the Bonusly app:

Once opened, you can begin adding attributes. Attributes like the users name, email, and department are already pre-mapped!

Select "Add Attribute" which will bring up the next screen to add custom properties

For the following parameters, you'll want to input the following:

For more information on each attribute, don't forget to check out the API Documentation!

  • External namespace: urn:scim:schemas:core:1.0:User

  • External name:

    • id

    • userName (*this is automatically mapped when you enable SSO)

    • name

    • meta

    • emails

    • active

    • addresses[country] (string, optional) - This will be imported into Bonusly as the user's country when addresses[type] is working.

      • This should be a valid ISO 3166-1 alpha-2 country code.

      • When configuring this in Okta, you need to create an attribute with the External Name addresses.^[type=='work'].country and the External namespace of urn:scim:schemas:core:1.0

    • externalId (*we recommend using this attribute to map your employee number to)

Note: If you are not sending country information for your users, the first time a user logs in to the system, their country will be set based on geocoding the IP address they are using. It will not be changed unless it's changed manually by an Admin or user management integration.

  • External namespace: urn:scim:schemas:extension:enterprise:1.0

  • External name:

    • department (*this is automatically mapped via Group)

  • External namespace: urn:scim:schemas:extension:bonusly:1.0:User

  • External name:

    • location

    • employee_id

    • role

    • job_title

    • division

    • business_unit

    • manager_email

    • user_mode

    • date_of_birth (*format must be YYYY-MM-DD - Bonusly does not store the year)

    • hired_on (*format must be YYYY-MM-DD)

Applying the Attributes

Once you've finished adding the attributes, you'll want to apply these attributes to sync with Bonusly.

  1. Head back to the "Provisioning" tab in the Bonusly app in Okta.

  2. Scroll down to "Bonusly Attribute Mappings"

  3. Select "Show Unmapped Attributes", you should see the ones you just added previously greyed out.

  4. Then select the pencil button next to the attribute you want to map.

Your profile should show automatically in the corner so you can see the preview of data that will be mapped when your user is synced.

Select the correct string to map for the specific attribute, you'll see the data that will populate when synced to Bonusly. Select "Create and update" under Apply on and save your changes.

Begin Syncing your Users from Okta to Bonusly

Note: We highly recommend testing 1-5 users to confirm that the correct information is being imported from Okta to Bonusly.

Bonusly Support has limited visibility into the data being sent from Okta, if we are unable to find a solution you may consider reaching out to Okta Support.

Once you're ready to send over users from Okta to Bonusly, navigate to the "Assignments" tab.

Warning: Once a Group or a User is assigned to Bonusly, they will immediately be sent an invite to join the account.

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!


​ 

Related Articles
How to Configure SAML SSO with ADFS
How to set up Single Sign On with SAML
Did this answer your question?