Provisioning for HipChat (Legacy Connector)

Note. This version of the HipChat connector was replaced by a new connector on May 17, 2016. This version is no longer available for new app integrations, but is still supported if you added your HipChat app in OneLogin and enabled provisioning before May 17, 2016. The information in this article is provided solely to support existing HipChat app integrations that were created before May 17, 2016. For information about the new HipChat connector, which connects to HipChat API version 2 over OAuth, see Provisioning for HipChat.

Prerequisites

1. Get a HipChat API token.

   Go to https://your_hipchat_domain.hipchat.com/account/api and generate an authentication token using all of the available scopes.

   Note. The above instructions are for HipChat REST API version 2. If your OneLogin account already uses the legacy HipChat API (version 1), you created your HipChat API authentication admin token at https://www.hipchat.com/admin/api.

2. If you would like users to be provisioned into HipChat with the password that they use with Active Directory, log in to OneLogin as the OneLogin account owner and turn on the Enable password mapping feature under Settings > Account Settings.

   If you don't turn this setting on, users will be provisioned into HipChat using a random password.

   OneLogin only stores the password when Enable directory fallback password cache is turned on and the user signs into OneLogin at least once (allowing OneLogin to store the password securely). If the user has been provisioned with a random password and you have enabled directory fallback password cache, the Active Directory password will be stored and provisioned into HipChat.

   For more information about these settings, see Account Settings for Account Owners.

Enabling provisioning

1. Go to Apps > Add Apps, search for HipChat, and select the HipChat connector that includes provisioning.
2. Click Save to add HipChat to your OneLogin account.

3. On the Configuration tab, connect to the HipChat API.

   

   1. Under API Version, select Version 2 to connect to the HipChat REST API version 2.

      HipChat API version 1 is only for OneLogin accounts that enabled HipChat provisioning before the OneLogin HipChat connector supported version 2. If you currently connect to API version 1 and you want to upgrade to API version 2, you must create a new API authentication token and reauthenticate to the API. See Prerequisites for API token generation instructions.

   2. Enter the API Authentication Token that you created in the HipChat administrative interface (see Prerequisites).

   3. Click Connect.

      When the connection is successful, the green icon appears.

4. On the Provisioning tab, enable provisioning and configure the provisioning approval workflow.

   1. Click Enable provisioning for HipChat.

   2. Choose the provisioning actions that should require administrator approval.

      For any action you select, a OneLogin administrator must go to Users > Provisioning and manually approve each action for provisioning to complete. Clear these options if you want OneLogin to provision new users and user updates to HipChat without administrative approval.

      Important! When you first configure provisioning, we recommend that you enable these approval options so that you can confirm that the correct users are being provisioned with the correct entitlements. Once you have confirmed that provisioning is working as expected, you can clear these options to enable provisioning to proceed without approval, if you want.

   3. Select what happens to a user in HipChat when that user is deleted from OneLogin.

      Choose between Delete and Do Nothing.

   4. Click Save.

5. On the Parameters tab, select how you want user credentials to be configured.

   You can also select the OneLogin attributes that you want to map to HipChat user attributes. For most implementations, you should keep the defaults.

6. (Optional) On the Rules tab, create rules to provision HipChat admin-level access based on OneLogin attribute values. 

   

   1. Click New Rule to open the New Mapping dialog.

   2. Name your new Mapping.

   3. Set the Action for your mapping and the Conditions that will trigger it.

      In the example shown in the screenshot, the mapping Conditions = MemberOf > contains > it_managers and Actions = Set Is Admin? in HipChat > Is Admin? means "If provisioning encounters a user who is a MemberOf the AD Security Group (OU) it_managers, assign that user as a HipChat Administrator. 

   4. Click Show Affected Users to makes sure that the mapping will affect the desired users.
   5. Click Save.

   6. Go the the More Actions menu and select Reapply provisioning mappings.

      Do this every time you create or update a mapping to ensure that the most recent mappings are being applied to your users.