DocumentationAPI Reference
Single Sign-On (SSO) with OpenID Connect

Single Sign-On (SSO) with OpenID Connect

Overview

Our customers love using BambooHR as their “employee hub” and system of record for employee data. Employees login to BambooHR to complete onboarding tasks, sign documents, see the company directory, view who’s out of the office, request time-off, track goals, and complete their performance assessments (among other things). Making it easy for employees to simply click into your platform from BambooHR and not have to login again provides a more seamless experience for BambooHR customers and their employees.

We support OpenID Connect as the SSO method for partners who desire to allow users to authenticate with BambooHR and then be logged into the partner application.

What is OpenID Connect?

You can learn more about OpenID Connect at http://openid.net/connect, and see a set of answers to Frequently Asked Questions at http://openid.net/connect/faq/. Also, for your reference, visit http://openid.net/developers/libraries/ for a list of libraries in various languages.

BambooHR’s Supported SSO Implementation

We support Open ID Connect as our SSO protocol.

Common Definitions

  • Available Grant Types: code
  • Scope: openid email
  • Username claim: email
  • Client ID: This is unique for each partner, and is provided by BambooHR
  • Client Secret: This is unique for each partner, and is provided by BambooHR
  • Code/Authorization Code: A one-time use code that the client will exchange for an access token
  • ID Token: A security token that contains data about an authorization server's authentication of a user. To get an api key, use https://documentation.bamboohr.com/page/openid-connect-login-api.
  • Access Token: In general, applications use access tokens to make API requests on behalf of a user. But Bamboo's API requires an API key which you can obtain with an ID Token (see above).

Visual Flow of Documentation for OpenID Connect

Auth Url

The Auth URL will be different for each customer. The subdomain {company} is unique for each customer’s BambooHR account.

Sample Request

GET https://{company}.bamboohr.com/authorize.php?request=authorize&state={state}&response_type=code&scope=openid+email&client_id={client_id}&redirect_uri={redirect_uri}

Explanations:

  • response_type=code: Indicates that your server expects to receive an authorization code
  • client_id: This is unique for each partner, and is provided by BambooHR
  • redirect_uri: Where you want the user to return to once authorization completes. Please note that all redirect URIs must be provided to BambooHR for whitelisting.
  • scope: Indicates what part of the users account you want access to. For this use-case it should always equal "openid email"
  • state: A random string your application provides for later verification

Once authentication occurs, the whitelisted redirect uri you provided will be hit with the new code attached to the url: {redirect_uri}?code={code}&state={state}

Token URL

The Token URL will be different for each customer. The subdomain is unique for each customer’s BambooHR account.

🚧

Caution

Its recommended to only include authentication details inside of the POST Body and not in the URL.

Sample Request

POST https://<company>.bamboohr.com/token.php?request=token
Accept:application/json
Content-Type:application/x-www-form-urlencoded

grant_type=authorization_code
&code={code}
&redirect_uri={redirect uri}
&client_id={client id}
&client_secret={client secret}
&scope=openid+email

Sample Response

{
 "access_token":"5decde9f6ff3af37655fb427f9aa0ce268f6436d",
 "expires_in":3600,
 "token_type":"Bearer",
 "scope":"scope",
 "id_token":"token"
}

User Info URL

The User Info URL will be different for each customer. The subdomain is unique for each customer’s BambooHR account.

Sample Request
POST https://.bamboohr.com/token.php?request=userInfo
Authorization: Bearer <access_token>

Sample Response

{
  "sub":"1234",
  "email":"[email protected]",
  "email_verified":null
}

Note: Sub is the logged in user's id, the email is the logged in user's email.

Setting Up Your Application

We require our partners to provide the following details:

  • Authorized Redirect URIs: Please provide BambooHR with all Redirect URIs so that we can add these to our configuration as an Identity Provider. *Redirect URI’s are required. This may seem difficult if you have multiple “tenants.” You can use the “state” parameter in the URL when you start the authentication flow to keep track of which “tenant” the eventual destination should be. This way, you can have a single destination in the redirect_uri, but that destination can forward the browser to the correct “tenant” with the appropriate information.
  • Login URL: This is the link that users will click on in order to single sign-on into your partner application from the customer’s BambooHR account

Setting the SSO Login URL Inside BambooHR

Additional login URL instructions
The partner should provide this Login URL to the customer, with these instructions:

  • An Admin user of the BambooHR account should login to their BambooHR account and navigate to their “Home” screen.

  • Find the “Company Links” widget and click on “Manage”

  • If desired, create a new link category called “Single Sign-On Links” or something similar

  • Click on “+Add Link” under the newly created link category (if applicable)

  • Add text for the “Link Title” and copy and paste the provided Login URL in the URL box

  • Click save
  • Go back to the “Home” and test the Single Sign-On link by clicking on the newly created link in your Links widget
  • If the link does not work, please contact the partner application who provided the SSO Login URL to you

OpenID Connect Login API: https://documentation.bamboohr.com/page/openid-connect-login-api
Authenticate Integration: https://documentation.bamboohr.com/page/authenticate-integration