Connect to a SAML identity provider for single sign-on

HipChat Data Center supports single sign-on (SSO) using SAML 2.0. If you're an IT admin of your organization, you can make it easier for your team to log in to HipChat by using your organization's identity provider. Your team has one less password to remember and their identities are more secure.

What you need

Before you start configuring SSO for your team, you'll need to know your identity provider (IdP). HipChat supports OneLogin and Okta right out of the box. If you use a different identity provider or have a custom SAML 2.0 implementation, you may still be able to use it with HipChat, but support will be limited.

On this page:

Set up SSO with OneLogin

HipChat supports OneLogin right out of the box, however the HipChat listing in OneLogin's apps list will not work for HipChat Data Center. You'll need to use the SAML Test Connector to add HipChat as a custom application.  

See the OneLogin documentation for help using the SAML Test Connector and giving your people access to HipChat. 

To connect HipChat to OneLogin:

  1. In OneLogin, add a new app using the SAML Test Connector (IdP w/attr.)
  2. In HipChat go to User management > SAML.
  3. Select SAML single sign-on and choose OneLogin as your identity provider. 
  4. Copy each of the SSO URLs provided in HipChat and paste them into OneLogin in the Configuration tab of your new app.
  5. In OneLogin, in the SSO tab of your new app, copy the Issuer URL.
  6. In HipChat, paste this into the Issuer URL field. 
    HipChat populates the SSO URL and x.509 certificate for you.
  7. Choose how you want to provision users, synch profile information and log in (more information). 
    (We recommend allowing both internal directory and SAML single sign-on until you've verified that your users can log in via your identity provider) 
  8. In OneLogin, in the Parameters tab, map the following attributes. This is used to populate the Full Name, @mention and Job Title fields in HipChat.
     

    Field name OneLogin value
    email Email
    user.firstName First Name
    user.lastName Last Name
    user.title Title

      

  9. Save your changes in HipChat and OneLogin. 
  10. In OneLogin, do any additional steps required to give users access to your new HipChat app. 

Here's how it looks in HipChat:

Set up SSO with Okta

HipChat supports Okta right out of the box, however the HipChat listing in Okta's applications list will not work for HipChat Data Center. You'll need to create a brand new application. 

See the Okta documentation if you need help using the Application Wizard to add a new application or assigning people to your new HipChat application.  

To connect HipChat to Okta:

  1. In Okta, go to Admin > Add Applications > Create new app to create a new application (don't choose it from the list) and select SAML 2.0 as the sign-on method.
  2. In HipChat log in to the admin web UI, and click User management > SAML.
  3. Select SAML single sign-on and choose Okta as your identity provider. 
  4. Copy each of the SSO URLs provided in HipChat and paste them into Okta at the Configure SAML step.  
  5. In Okta, map the following attributes at the Configure SAML step. This is used to populate the Full name, @mention and Job title fields in HipChat.
     

    Name Okta value
    user.email user.email
    user.firstName user.firstName
    user.lastName user.lastName
    user.title user.title

      

  6. In Okta, complete the application set-up process. 
  7. Navigate to your new application in Okta and head to the Sign On tab to download or copy the Identity Provider Metadata. 
  8. In HipChat, upload or paste this into the Identity Provider Metadata field. 
  9. Choose how you want to provision users, synch profile information and log in (more information). 
    (We recommend allowing both internal directory and SAML single sign-on until you've verified that your users can log in via your identity provider).
  10. Save your changes in HipChat. 
  11. In Okta, do any additional steps required to give users access to your new HipChat app. 

Here's how it looks in HipChat:

Set up SSO with other identity providers or a custom implementation

If you're using a SAML 2.0 implementation other than OneLogin or Okta, you can still configure SSO in HipChat, but assistance from our support team will be limited.

Before you start, you'll need to get the following information from your identity provider:

  • Their entity ID - a unique name (usually a URL) that the identity provider uses for SAML 2.0. (It's sometimes provided in a field called "identity provider issuer").
  • Their SSO Endpoint URL - a SAML 2.0 endpoint URL to which HipChat will redirect your people when they start logging in to HipChat, so your identity provider can authenticate them.
  • Their x.509 certificate - the identity provider's public certificate that has their public key, so HipChat can validate login requests from them.

Once you have the information you need, you can configure SSO in HipChat.

  1. Log in to HipChat in your browser.
  2. Go to User management > SAML.
  3. In the Identity provider field, choose Custom SAML 2.0.
  4. Enter your identity provider's Entity ID
  5. Enter your identity provider's SSO Endpoint URL. 
  6. Copy and paste the contents of the identity provider's x.509 certification in the Public certificate field.
  7. Choose how you want to provision users, synch profile information and log in (more information). 
    (We recommend allowing both internal directory and SAML single sign-on until you've verified that your users can log in via your identity provider).
  8. Save your changes.
  9. Next, copy each of the SSO URLs provided in HipChat and paste them into your identity provider to complete the configuration.

    • Audience - the unique name (in this case, a URL) your HipChat group will use for SAML 2.0.  This is sometimes known as the Service Provider Entity ID.
    • Recipient (ACS consumer URL) - the SAML 2.0 endpoint URL that the identity provider will use to log your team in to HipChat
    • Single log-out (SLO) URL - an optional URL the identity provider can use to log your team out of HipChat. When your team members log out of your identity provider (for example, they log out of OneLogin), your identity provider will automatically log them out of HipChat too. 
  10. If required by your identify provider, map the following attributes / fields to the appropriate values for your identity provider. This is used to populate the Full name, @mention and Job title fields in HipChat.  
     

    HipChat field name IdP value
    user.email the user's email address
    user.firstName the user's first name
    user.lastName the user's last name
    user.title the user's role or job title (if applicable)

Known issues with other identity providers

  • Customers have reported issues connecting Google IdP.

Sign-on and account provisioning options

The following options allow you to control how users sign in and when accounts are provisioned. You can change these settings in User management > SAML

  • Just in time provisioning
    Enable this option to create HipChat accounts for new users when they log in through your identity provider. 
  • Profile synchronization
    Enable this option to automatically update users' names and titles when they log in through your identity provider. 
  • Internal directory and SAML single sign on
    Enable this option to allow users to log in to HipChat directly or through your identity provider. If this option is disabled, single sign-on is mandatory, and users will only be able to log in to HipChat through your identity provider.  

SAML with encrypted assertions

If your SAML provider sends encrypted assertions, you can set up trust between the SAML IdP and the HipChat Server so that HipChat can decrypt these assertions.  

To set up trust between HipChat Data Center and your SAML identity provider: 

  1. Generate a public/private key pair. 
  2. Install the public key on your SAML IdP.
  3. Copy the private key to one of the HipChat nodes. 
  4. Then run the following command, replacing 'path/to/cert' with the actual path to the private key the on the HipChat node.
hipchat saml --sp-cert path/to/cert 

 

Turn off SAML single sign-on

If you decide you no longer want to use SAML single sign-on:

  1. In HipChat go to User management > SAML.
  2. Choose None as your identity provider. 

Users will be then authenticated via HipChat's internal directory or your external directory (if configured). If a user does not know their internal directory password they can use the Forgot password link to set a new password.  

Troubleshooting

  • Unable to log in using SSO? If you're not able to login using single sign-on (for example your identity provider is not available), administrators can still log in using HipChat's internal directory using the Admin login link on the HipChat login screen. 
    If you're unable to log in using single sign-on right after you've configured SAML 2.0, change the authentication type back to Internal Directory then check your configuration settings in both HipChat and your identity provider. 
  • Need help? Our support team can help you troubleshoot connecting HipChat to your IdP, but for questions related specifically to your IdP set up, you'll need to contact your identity provider directly for support.  
Last modified on Jul 25, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Not finding the help you need?

Ask the community

Powered by Confluence and Scroll Viewport.