Bonusly

Before You Begin

Introduction

This document describes how to configure Oracle Identity Cloud Service to provide Single Sign-On (SSO) and user provisioning for Bonusly.

About Bonusly

Bonusly aims to change the incentive model, helping companies reward and motivate employees by using peer-to-peer bonuses. It uses a web platform that offers a different approach to employee recognition, reward, and collaboration.

After integrating Bonusly with Oracle Identity Cloud Service:

  • Users can access Bonusly using their Oracle Identity Cloud Service login credentials.
  • Users can launch Bonusly using the Oracle Identity Cloud Service My Apps console.
  • Admins can assign and revoke user access to the Bonusly app using the Oracle Identity Cloud Service administration console.

What Do You Need?

  • An Oracle Identity Cloud Service account with authorization rights to manage apps and users (Identity Domain Administrator or Application Administrator).
  • A Bonusly account with authorization rights to configure federated authentication and user provisioning.
  • Identity Provider metadata. You can use the following URL to access the metadata: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/metadata and save the metadata in a text file. Use this file later to obtain the identity provider certificate in the "Obtaining the Identity Provider Certificate" section.

Obtaining the Identity Provider Certificate

Use this section to obtain the Identity Provider Certificate in a format that is suitable for Bonusly.

  1. Access the Identity Provider metadata file that you downloaded in the "What Do You Need?" section.

  2. In the metadata file, locate the dsig:X509Certificate tags.

  3. Copy the content between the dsig:X509Certificate tags into a text file. This content is the Oracle Identity Cloud Service signing certificate.

    Image img1.png displays the metadata content with md:IDPSSODescriptor and dsig:X509Certificate tags highlighted.

  4. Add -----BEGIN CERTIFICATE----- at the beginning of the content.

  5. Add -----END CERTIFICATE----- at the end of the content.

    Image img2.png displays the text file with the certificate content highlighted.

    Tip: Use this certificate content later during Bonusly configuration in the "Configuring SSO for Bonusly" section.

Configuring SSO for Bonusly

  1. Access Bonusly as an administrator using the URL: https://bonus.ly/users/sign_in_start. The Bonusly home page appears.

    Note: When the user accesses Bonusly for the first time, the Take a one minute tour! pop-up window appears. Users can either choose to click Let's do this! for more information on the Bonusly features, or click choose I'll skip it to ignore the pop-up window and access the Bonusly home page.

  2. In the left-navigation menu, click INTEGRATIONS.

  3. On the Integrations page, locate the Simple and secure section, and then click SAML.

  4. On the SAML Integration page, make sure that the Automatically Configure from Metadata check box is not selected.

  5. Use the table to update the federated authentication attributes, and then click Save. A success message is displayed stating that the SSO integration is saved successfully.

    Attribute Value
    IdP Issuer (Entity ID) Enter the Entity ID/Issuer URL. Use the metadata file that you downloaded earlier to obtain the Entity ID/Issuer URL. The Entity ID/Issuer URL information is located in the first line of the metadata. See the "What Do You Need?" section. To learn about other methods you can use to access SAML metadata, see Access SAML Metadata.
    IdP SSO target URL Enter the Sign-in URL/SSO Endpoint: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/idp/sso.
    X.509 Cert Paste the identity provider certificate content that you obtained earlier in the "Obtaining the Identity Provider Certificate" section.

  6. On the SAML Integration page, make note of the App ID.

    Note: Use the App ID value during Bonusly registration in the "Registering and Activating the Bonusly App" section.

  7. Under the ADMIN section in the left-navigation menu, click COMPANY, and then select Settings. The Settings page appears.

  8. Locate and click Show advanced settings.

  9. Locate Login Methods, select the Restrict to Single Sign On check box, and then click Save Settings to access Bonusly only via single sign-on.

    Note: When the Restrict to Single Sign On check box is selected, users cannot log in to Bonusly using their email and password.

Obtaining Access Token

  1. In the left-navigation menu of Bonusly, click INTEGRATIONS.

  2. On the Integrations page, locate the If you want to code section, and then select API.

  3. On the API page, under the Your API Access Tokens section, click Create New API Access Token.

  4. On the New Access Token page, enter the label in the text box, and then click Create Api key. You are redirected to the Services page, and a confirmation message displays the Access token in the upper-right corner.

    Image img3.png displays the Access token highlighted in the confirmation message that appears on the Services page.

    Note: It is recommended to note the Access Token immediately as the Access Token appears only once for a brief duration. Use this Access Token value while enabling user provisioning for the Bonusly app in Oracle Identity Cloud Service. See the "Enabling Provisioning" section.

Configuring Bonusly in Oracle Identity Cloud Service

Use this section to register and activate Bonusly, and to enable provisioning and synchronization for Bonusly.

Registering and Activating the Bonusly App

  1. Access the Oracle Identity Cloud Service administration console, select Applications, and then click Add.

  2. Click App Catalog.

  3. Search for Bonusly, and then click Add.

  4. In the App Details section, enter your Bonusly App ID, and then click Next.

    Note: This is the App ID that you obtained while configuring SSO for Bonusly in the "Configuring SSO for Bonusly" section.

  5. Click Next to enable provisioning and synchronization for Bonusly. Oracle Identity Cloud Service displays the Provisioning page.

Enabling Provisioning and Synchronization for Bonusly

Use this section to enable provisioning and synchronization for managing user accounts in Bonusly through Oracle Identity Cloud Service.

Enabling Provisioning

  1. On the Provisioning page, select Enable Provisioning.

  2. Under the Configure Connectivity section, enter the Access Token.

    Note: This is the Access Token value that you obtained while performing the steps in the "Obtaining Access Token" section.

  3. Click Test Connectivity. A success message is displayed stating that the connection is successful.

  4. To view predefined attribute mappings between the user account fields defined in Bonusly and the corresponding fields defined in Oracle Identity Cloud Service, click Attribute Mapping, and then click OK.

    Note: To add a new attribute for provisioning, click Add Row, specify the attributes in the User and Bonusly Account columns, and then click OK. For example, if you want to add the External ID field, enter $(user.externalId) in the User column, and then select the corresponding field from the drop-down list in the Bonusly Account column.

  5. Specify the provisioning operations that you want to enable for Bonusly:

    Note: By default, the Create Account, Update Account, De-activate Account, and Delete Account check boxes are selected.

    Create Account: Automatically creates a Bonusly account when Bonusly access is granted to the corresponding user in Oracle Identity Cloud Service.

    Update Account: Automatically updates a Bonusly account when the corresponding user account is edited in Oracle Identity Cloud Service.

    De-activate Account: Automatically deactivates or activates a Bonusly account when the Bonusly access is deactivated or activated for the corresponding user in Oracle Identity Cloud Service.

    Delete Account: Automatically deactivates an account from Bonusly when Bonusly access is revoked from the corresponding user in Oracle Identity Cloud Service.

Enabling Synchronization

  1. On the Provisioning page, select Enable Synchronization.

  2. From the User Identifier drop-down list, select the Oracle Identity Cloud Service user attribute that you want to match with the corresponding record fetched from Bonusly:

    Note: By default, the Primary Email Address option is selected from the drop-down list. It is recommended to leave this default attribute for accurate synchronization of user records.

    Primary Email Address: Primary email address of the Oracle Identity Cloud Service user.

    User Name: User name of the Oracle Identity Cloud Service user.

  3. To match a Bonusly account attribute with the existing Oracle Identity Cloud Service user, select an attribute from the Application Identifier drop-down list.

    Note: By default, the name option is selected that represents the Email attribute of the Bonusly account. It is recommended not to change this default option.    

  1. From the When exact match is found drop-down list, select one of the following actions to be performed when a matching Oracle Identity Cloud Service user is found for an account:

    Link and confirm: Automatically links and confirms the matched account to the corresponding Oracle Identity Cloud Service users based on the defined User Identifier and Application Identifier fields. 

    Link but do not confirm: Automatically links all the matched accounts to the corresponding Oracle Identity Cloud Service users based on the defined User Identifier and Application Identifier fields. You need to manually confirm the linked accounts. 

  2. In the Max. number of creates field, enter a number that is greater than or equal to 10. This value limits the number of accounts to be created during the synchronization run.

  3. In the Max. number of deletes field, enter a number that is greater than or equal to 10. This value limits the number of accounts to be deleted during the synchronization run.

    After enabling provisioning and synchronization for Bonusly, you can synchronize the existing account details from Bonusly and link them to the corresponding Oracle Identity Cloud Service users. For more information on performing synchronization tasks, see the Importing User Accounts from a Software as a Service Application section in Administering Oracle Identity Cloud Service.

    You can also manage Bonusly accounts through Oracle Identity Cloud Service. For more information on performing provisioning tasks, see the Managing Oracle Identity Cloud Service Users and Managing Oracle Identity Cloud Service Groups sections in Administering Oracle Identity Cloud Service.

    Note: According to Bonusly, there is a preset rate of user import requests that can be permitted within a specific duration. Therefore, large number of user import requests are not allowed to be made within a short period of time. If the rate of requests exceeds the limit in Bonusly, the requests will be denied until the rate limit resets. Hence, when importing user accounts from Bonusly to Oracle Identity Cloud Service, all the users may not be imported, if large number of user accounts exist in Bonusly.

  4. Click Finish, and Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Verifying the Integration

Use this section to verify that SSO works when initiated from Oracle Identity Cloud Service (IdP initiated SSO) and Bonusly (SP initiated SSO).

Verifying Identity Provider Initiated SSO from Oracle Identity Cloud Service

  1. Access the Oracle Identity Cloud Service My Profile console using the URL: https://<IDCS-Service-Instance>.identity.oraclecloud.com/ui/v1/myconsole.

  2. Log in using credentials for a user that is assigned to the Bonusly app. Oracle Identity Cloud Service displays a shortcut to Bonusly under My Apps.

  3. Click Bonusly. The Bonusly home page appears.

  4. In the lower-left corner, confirm that the user that is logged in is the same for both Bonusly and Oracle Identity Cloud Service.

    This confirms that SSO that is initiated from Oracle Identity Cloud Service works.

Verifying Service Provider Initiated SSO from Bonusly

  1. Access Bonusly using the URL: https://bonus.ly/users/sign_in_start. The Bonusly login page appears.

  2. Enter the email address, and then click Next. You are redirected to the Oracle Identity Cloud Service login page.

  3. Log in using credentials for a user that is assigned to the Bonusly app. The Bonusly home page appears.

  4. In the lower-left corner, confirm that the user that is logged in is the same for both Bonusly and Oracle Identity Cloud Service.

    This confirms that SSO that is initiated from Bonusly works.

Troubleshooting

Use this section to locate solutions to common integration issues.

Known Issues

Bonusly displays the message, "Authorization failed: No user found for email."

Cause 1: The user account assigned to Bonusly is deactivated in Oracle Identity Cloud Service under the Bonusly application's Users tab, and the user attempts to initiate single sign-on from Bonusly.

Solution 1: Ensure that the user account is activated under the Users tab of the Bonusly app in Oracle Identity Cloud Service.

Cause 2: The user account assigned to Bonusly is deactivated in the Manage page of the Bonusly app, and the user attempts to initiate single sign-on.

Solution 2: Ensure that the user account is activated in the Manage page of the Bonusly app.

Cause 3: The email attribute sent by Oracle Identity Cloud Service during SSO doesn't match any existing user in Bonusly.

Solution 3: Ensure that the user that you assign to the Bonusly app has an account in both Oracle Identity Cloud Service and Bonusly with the same email address.

Oracle Identity Cloud Service displays the message, "You are not authorized to access the app. Contact your system administrator."

Cause 1: The SAML 2.0 integration between the Oracle Identity Cloud Service Bonusly app and Bonusly is deactivated.

Solution 1:

  • Access the Oracle Identity Cloud Service administration console, select Applications, and then select Bonusly.
  • In the App Details section, click Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Cause 2: The administrator revokes access for the user at the same time that the user tries to access the Bonusly app using Oracle Identity Cloud Service.

Solution 2:

  • Access the Oracle Identity Cloud Service administration console, select Applications, and then select Bonusly.
  • In the App Details section, select Users, and then click Assign to re-assign the user.

Unknown Issues

For unknown issues, contact Oracle Support:

  1. Go to https://support.oracle.com.

  2. Select Cloud Support, and then sign in with your support credentials.

  3. In the Cloud Dashboard, confirm that there are no planned outages in Oracle Identity Cloud Service, and then click Create Service Request.

  4. Select Oracle Identity Cloud Service as the service type.

  5. Complete your service request.