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 a week ago

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

Note: SAML SSO via Okta is only available on the Organization plan (and certain legacy plans).

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

Note on SCIM core attributes and namespaces
Bonusly now accepts SCIM “core” user attributes whether they are provided at the top level or nested under common SCIM 1.x core namespaces. While we recommend using the external namespace urn:scim:schemas:core:1.0:User as shown below,

Bonusly will also parse core user fields when they’re nested under other SCIM 1.x core URNs (for example, urn:scim:schemas:core:1 or providers that emit a nested 0:User node). This means most Okta defaults and common schema variants will work without custom transformation.


If you already mapped attributes to urn:scim:schemas:core:1.0:User, no changes are needed.

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:User

  • externalId (*we recommend using this attribute to map your employee number to)- External company ID requirements: The external company ID must be alphanumeric, serving as a unique identifier for integration purposes. For instance, if your company operates with HRIS platforms such as Marmon Rail, ensure this identifier adopts a standard alphanumeric format devoid of customer-specific details. Using this approach ensures greater compatibility across integration scenarios.- Configuration in Okta: When configuring the externalId attribute in Okta, map the attribute correctly by setting the following details:

    • Variable Name: Use a custom name like 'extId.'

    • External Name: externalId

    • External Namespace: urn:scim:schemas:core:1.0:User. This mapping ensures synchronization between Okta and Bonusly is seamless.

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:

    • cost_center

    • preferred_first_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.

If user names or emails aren’t coming through, verify that your attributes are either:

  • mapped under urn:scim:schemas:core:1.0:User (recommended), OR

  • emitted by your IdP under another SCIM 1.x core namespace.
    Bonusly supports both patterns, so you typically don’t need a custom transform.

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.

If you encounter issues during the synchronization, verify the following:

  • Ensure that the externalId attribute is correctly configured in Okta.

  • Avoid conflicts with existing attributes in the Okta profile.

  • Double-check the permissions to confirm they allow updates to the externalId field. For further guidance, revisit the Bonusly API documentation or consult Okta Support for advanced troubleshooting.

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!


​ 

Did this answer your question?