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 Server. 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 Group admin > Authentication.
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 Server. 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 go to Group admin > Authentication.
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 Group admin > Authentication.
3. Click SAML single-sign on.
4. In the Identity provider field, choose Custom SAML 2.0.
5. Enter your identity provider's Entity ID. 
6. Enter your identity provider's SSO Endpoint URL. 
7. Copy and paste the contents of the identity provider's x.509 certification in the Public certificate field.
8. 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).
9. Save your changes.

10. 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. 

11. 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 Group admin > Authentication. 

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

Turn off SAML single sign-on

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

1. In Hipchat go to Group admin > Authentication.
2. Select SAML single sign-on and 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.