Automatically Creating and Renewing OAuth User Credentials

Automatically Creating and Renewing OAuth User Credentials

Starting in the Digital Hive 2024.2 release (April 2024), it is now possible to automatically 'unlock' OAuth user credentials when a user first logs into Digital Hive. This means that first time users won't have to remember to unlock their personal credentials for content systems that leverage OAuth as a security source, such as Microsoft SharePoint Online and PowerBI. 

When this feature is enabled, it is disabled by default, during the login process a pop-up dialog will appear and if there is already a valid user session for that OAuth provider, it will use that credential and quickly close the pop-up dialog. If the user does not have a valid OAuth session active, the user will be prompted to login.

This will only happen for content systems that use OAuth as a security source and that have been configured for automatic credential creation.

This is the type of experience new users will enjoy when using Digital Hive and the auto generation of OAuth credentials feature enabled.



Enabling Automatic Credential Creation

As with some other Digital Hive features, the automatic credential creation for OAuth is not enabled by default and has to be enabled via a configuration file on the physical Digital Hive server. To enable the feature:
  1. Log into the physical Digital Hive server as an administrator
  2. Through the Windows Services interface, stop the DigitalHive-node1 service
  3. Using the File Explorer, navigate to the <digital_hive_install>\app\node1\tomcat\webapps\theia directory
  4. Open the config.json file in a text editor
  5. Look for the "connectors":{} entry
  6. If configuring for SharePoint online, paste the following code snippet between the { }'s of the connectors line
      "sharePoint": {
          "warmupCooldown": {
            "attemptWarmup": true,
      "oauthAutoCreateCredential":true
          }
        }

  7. If configuring for PowerBI online, paste the following code snippet between the { }'s of the connectors line
      "powerBI": {
          "warmupCooldown": {
            "attemptWarmup": true,
      "oauthAutoCreateCredential":true
          }
        }

  8. If configuring for both PowerBI and SharePoint online, paste the following code snippet 
    between the { }'s of the connectors line
    "powerBI": {
          "warmupCooldown": {
            "attemptWarmup": true,
      "oauthAutoCreateCredential":true
          }
        },
        "sharePoint": {
          "warmupCooldown": {
            "attemptWarmup": true,
      "oauthAutoCreateCredential":true
          }
        }
  9. The resulting file will look like this for a single configured content system (your config,json file may have different entries besides the important "connectors":{} entry) 

  10. The resulting file will look like this for two configured content systems (your config,json file may have different entries besides the important "connectors":{} entry)
  11. Save the config.json file
  12. Start the DigitalHive-node1 service
With these settings in place, the OAuth credentials will be automatically created for new users, and will be refreshed on login (once every 24 hours) for users with existing credentials. In most environments, a 24 hour refresh cycle will not be required. To remove the daily checks, which results in pop-up windows briefly appearing for users on login, it is possible to extend the refresh period.

  1. Log into the physical Digital Hive server as an administrator
  2. Through the Windows Services interface, stop the DigitalHive-node1 service
  3. Using the File Explorer, navigate to the <digital_hive_install>\app\node1\tomcat\webapps\theia directory
  4. Open the config.json file in a text editor
  5. After the "attemptWarmup": true, entry, paste the following code snippet:
  6.   "delayBetweenWarmup": 1728000000,

  7. Save the config.json file
  8. Start the DigitalHive-node1 service
The value used in the delayBetweenWarmup property is in milliseconds and the max value supported is 1728000000, which is equal to a 20 day refresh cycle.

These steps would have to be repeated for each OAuth connector configured for the automatic credential creation feature.

The final appearance of the config.json file, with multiple OAuth connector types, should look something like this:



Troubleshooting

This feature is intended to remove the need for new users to manually unlock their credentials on first login. There may be some scenarios where the feature doesn't appear to be working properly, so the following section helps to remove any confusion and provides guidance on how to proceed with issues are encountered.

If an existing user manually deletes their existing OAuth credential, their credential isn't re-created on next login. This is by design. The reason that the feature works this way, is that not all users may want, require, or even have, a valid credential for PowerBI, SharePointOnline, and other OAuth secured content systems. Once a user deletes their existing OAuth credential, or cancels out of the pop-up when the credential is being created or refreshed, a flag is set to indicate that the credential for this system should not be automatically created on subsequent logins. If this flag was not in place, a user would get prompted to login to a content system that they either don't have access to, or don't want to access. This would be a horrible experience for these types of users.

If a user deletes their credential, it is possible to restore the automatic creation process, but it would be easier for the user to simply manually 'unlock' their credential ... especially since they knew how to delete it in the first place. 



Authentication pop-up doesn't appear or there is a Please Wait   message displayed in the left-hand corner of the browser. This is usually because a browser setting that disabled pop-ups for a website. Looking at the browser address bar, this icon is visible: 
Clicking on the icon will open a message that states that Pop-ups are blocked. To remediate the issue, click the radio button beside the Always allow pop-ups and redirects from ... and then press Done.



Authentication pop-up doesn't appear or there is a Please Wait   message displayed in the left-hand corner of the browser. If pop-ups are enabled for the site, another cause for the Please Wait message to be visible on the screen is that the authentication window popped up, it requires user input, and the user inadvertently click away from the pop-up and the original browser window has focus, so the pop-up is no longer visible. To remedy this, the user will have to move the windows around until the pop-up window is located and the user fulfills the prompt values.

Problem with Connector detected. When opening the Digital Hive Control Center, there is a message on the Overview tab stating that a problem with the connector is detected.

Changing view to the Content -> Connectors tab, and looking at the details for either the PowerBI or Sharepoint Online connectors, the Can't connect message is displayed.


or


As the message implies, the system credential requires re-authentication. 
  1. From the connector details page, select the  tab
  2. Click the  button in the upper right-hand corner of the screen
  3. Satisfy the authentication prompts if required
Ensure that you are logged in as the correct user that will be used as the system credential and not your own account.

Being prompted for authentication earlier than the delay between warmup setting value. This can occur, and is expected, in a couple of scenarios:
  1. Your credential is being used as the System Credential for the connector. This happens when you're a Digital Hive administrator and either your credentials are being used as the system credential, or you've mistakingly re-authenticated the system credential and there was already an active session for your account in the browser. Sign-out of all browser sessions and re-authenticate with the correct system credential.
  2. You've logged in to Digital Hive as another user since logging in with your account. This typically happens when administrators are using different accounts for testing. Most users do not have multiple logins and would not encounter this issue.


    • Related Articles

    • Enhancing the User Experience with Visual Cues

      Question Is there a way within Digital Hive to highlight certain types of content so that users can easily identify relevant objects? For example, highlighting content that has recently been added, that has been certified, or that have been tagged ...

    • Using OAuth as the Authentication Source for Digital Hive

      Question Can Digital Hive leverage OAuth as the authentication source so that existing users and groups can be used? Answer OAuth sources like Azure and Google can both be leveraged for Digital Hive authentication. When using external third-party ...

    • Using OIDC or Oauth as the Authentication Source for Digital Hive

      Question Can Digital Hive leverage OIDC (OpenID Connect) or Oauth as the authentication source for Digital Hive? Answer Digital Hive can be configured to use OIDC and/or Oauth authentication, but some default configuration parameters will have to be ...

    • Getting Prompted for IBM Cognos Analytics Credentials

      Question When viewing a Digital Hive page that contains an IBM Cognos Analytics visualization, the IBM Cognos Analytics login screen appears instead of the visualization. My IBM Cognos Analytics connector credentials are persisted as part of my ...

    • Creating a Personalized Greeting within a Hive

      Question Is there way to insert a personalized greeting onto a Hive page to create a more personal user experience? Answer As of the Digital Hive 2.1 release, it is possible to insert a customized personal greeting into the Digital Hive experience. ...