https://github.com/intercom/omniauth-intercom
Intercom strategy for OmniAuth
https://github.com/intercom/omniauth-intercom
Last synced: 5 months ago
JSON representation
Intercom strategy for OmniAuth
- Host: GitHub
- URL: https://github.com/intercom/omniauth-intercom
- Owner: intercom
- License: mit
- Created: 2016-05-03T14:49:56.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2025-02-13T10:03:13.000Z (about 1 year ago)
- Last Synced: 2025-04-12T06:43:22.948Z (12 months ago)
- Language: Ruby
- Size: 41 KB
- Stars: 6
- Watchers: 150
- Forks: 7
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# OmniAuth Intercom
Intercom OAuth2 Strategy for OmniAuth.
Supports the OAuth 2.0 server-side and client-side flows. Read the [Intercom OAuth docs](https://developers.intercom.io/reference#oauth) for more details:
## Installing
Add to your `Gemfile`:
```ruby
gem 'omniauth-intercom', '~> 0.1.9'
```
Then `bundle install`.
## Usage
**Important** For this to work you need to select the `read_single_admin` permissions in your OAuth application to use this middleware.
**Important** You will also need to ensure your `redirect_url` is set to `/auth/intercom/callback`
`OmniAuth::Strategies::Intercom` is simply a Rack middleware. Read the OmniAuth docs for detailed instructions: https://github.com/intridea/omniauth.
Here's a quick example, adding the middleware to a Rails app in `config/initializers/omniauth.rb`:
```ruby
Rails.application.config.middleware.use OmniAuth::Builder do
provider :intercom, ENV['INTERCOM_KEY'], ENV['INTERCOM_SECRET']
end
```
To start the authentication process with Intercom you simply need to access `/auth/intercom` route.
You can start the authentication process directly with the signup page by accessing `/auth/intercom?signup=1`
**Important** Reminder: As noted earlier you need the `read_single_admin` permissions to use this middleware.
**Important** Reminder: As noted earlier your `redirect_url` should be `/auth/intercom/callback`
By default Intercom strategy rejects users with unverified email addresses. `info` and `raw_info` in `request.env['omniauth.auth']` will not be populated in that case.
To disable this check add `verify_email: false` to your config:
```ruby
Rails.application.config.middleware.use OmniAuth::Builder do
provider :intercom, ENV['INTERCOM_KEY'], ENV['INTERCOM_SECRET'], verify_email: false
end
```
## Auth Hash
Here's an example *Auth Hash* available in `request.env['omniauth.auth']`:
```ruby
{
:provider => 'intercom',
:uid => '342324',
:info => {
:email => 'kevin.antoine@intercom.io',
:name => 'Kevin Antoine'
},
:credentials => {
:token => 'dG9rOmNdrWt0ZjtgzzE0MDdfNGM5YVe4MzsmXzFmOGd2MDhiMfJmYTrxOtA=', # OAuth 2.0 access_token, which you may wish to store
:expires => false
},
:extra => {
:raw_info => {
:name => 'Kevin Antoine',
:email => 'kevin.antoine@intercom.io',
:type => 'admin',
:id => '342324',
:email_verified => true,
:app => {
:id_code => 'abc123', # Company app_id
:type => 'app',
:secure => true, # Secure mode enabled for this app
:timezone => "Dublin",
:name => "ProjectMap"
},
:avatar => {
:image_url => "https://static.intercomassets.com/avatars/343616/square_128/me.jpg?1454165491"
}
}
}
}
```
### Intercom Button / Popup authentication
To use `Intercom Button` to display authentication in a popup it is simple :
- Add the following code in the html file in which you want to start to authenticate with Intercom ( `/views/home/index.html.erb` if you want to authenticate with Intercom in `home#index`)
```html
$('.intercom-oauth-cta').unbind('click').click(function() {
var auth_window = window.open('/auth/intercom', 'Sign in', 'width=700,height=450');
var checkWindow = function() {
if (auth_window.closed) {
window.location = '/';
} else if (window.oauth_success === undefined) {
setTimeout(checkWindow, 200);
}
};
checkWindow();
});
```
Create a `views/home/intercom_callback.html.erb` file ( if your callback route is `home#intercom_callback`)
```html
Authorized
setTimeout(function() {
if (window.opener) {
window.opener.oauth_success = true;
}
window.close();
}, 1000);
```
### Example application
[testapp-intercom-omniauth](https://github.com/Skaelv/testapp-intercom-omniauth) is a simple application implementing the authentication process with Intercom with a popup display.
## Troubleshooting
#### omniauth-oauth2 dependency in v0.1.4
From v0.1.4 we have defined our `omniauth-oauth2` dependency to allow any version from 1.2 on. If you relied on our Gemspec version config for `omniauth-oauth2` you can simply add `gem 'omniauth-oauth2', '~> 1.2'` to your Gemfile. This will ensure your `omniauth-oauth2` version is `1.2.x` again.