Using OpenID Connect to Authenticate and Retrieve an API Key
Overview
Approved Apps Marketplace Partners are required to use our OpenID Connect Login API to retrieve the API Key for the authorized BambooHR user who is configuring the integration between the Partner Application and the respective user’s BambooHR account.
This guide will document how BambooHR’s implementation of OpenID Connect can be used in conjunction with the new OpenID Connect Login API to provide an OAuth-like user experience when configuring the integration between BambooHR and the Partner Application.
In order to be able to implement this method, you’ll need to be issued OpenID credentials including a Client ID, Client Secret, and Application Key (from BambooHR) as well as an understanding of our OpenID Connect Implementation and our OpenID Connect Login API.
For Ruby Applications
One of our partners, Bonusly, has pulled their code into a gem so that it’s easy to reuse. It’s available for your reference at https://github.com/bonusly/bamboo-id.
Let’s get started
The workflow would look something like the following:
- The BambooHR user would login to the Partner Application and navigate to the BambooHR integration configuration screen.
- The BambooHR user would be prompted to provide the BambooHR subdomain (if their login URL was https://company.bamboohr.com, their subdomain would be “company“).
- The Partner Application would direct the user to BambooHR for authentication using the Auth URL (https://documentation.bamboohr.com/page/single-sign-on-sso-with-openid-connect#auth-url). BambooHR will know if the user should login using their standard BambooHR login credentials, Google login, or be directed to a third party SAML IdP. Once authenticated, BambooHR will pass an auth code back to the Partner Application using the specified redirect uri.
- The Partner Application’s servers will then request an ID Token using the Token URL (https://documentation.bamboohr.com/page/single-sign-on-sso-with-openid-connect#token-url) from BambooHR’s servers and provide the auth code received in the previous step.
- BambooHR’s servers will then provide an ID Token for that user back to the Partner Application.
Using the provided ID Token together with the issued Application Key, the Partner Application will then use the OpenID Connect Login API (https://documentation.bamboohr.com/page/openid-connect-login-api) to retrieve the API Key of the user. - BambooHR will generate and send the API Key of the authenticated user back to the Partner Application.
- The Partner Application should store and use that API Key for the integration and all API requests going forward.
