Skip to content

Latest commit

 

History

History
196 lines (147 loc) · 6.56 KB

README.md

File metadata and controls

196 lines (147 loc) · 6.56 KB
Raw

OmniAuth Auth0

FORK ADDITIONS

  1. PASSTHRU PARAMETERS
  2. CUSTOM JWK HOST DOMAIN

An OmniAuth strategy for authenticating with Auth0. This strategy is based on the OmniAuth OAuth2 strategy.

Important security note: The parent library for this strategy currently has an unresolved security issue. Please see the discussion, including mitigations for Rails and non-Rails applications, here.

CircleCI codecov Gem Version MIT licensed

Table of Contents

Documentation

Installation

Add the following line to your Gemfile:

gem 'omniauth-auth0'

If you're using this strategy with Rails, also add the following for CSRF protection:

gem 'omniauth-rails_csrf_protection'

Then install:

$ bundle install

See our contributing guide for information on local installation for development.

Getting Started

To start processing authentication requests, the following steps must be performed:

  1. Initialize the strategy
  2. Configure the callback controller
  3. Add the required routes
  4. Trigger an authentication request

All of these tasks and more are covered in our Ruby on Rails Quickstart.

Additional authentication parameters

To send additional parameters during login, you can specify them when you register the provider:

provider 
  :auth0,
  ENV['AUTH0_CLIENT_ID'],
  ENV['AUTH0_CLIENT_SECRET'],
  ENV['AUTH0_DOMAIN'],
  ENV['AUTH0_KEY_HOST'],
  {
    authorize_params: {
      scope: 'openid read:users write:order',
      audience: 'https://mydomain/api'
    }
  }

... which will tell the strategy to send those parameters on every authentication request.

Passthru parameters

To passthru request parameters the to login, you can whitelist them when you register the provider:

provider
  :auth0,
  ENV['AUTH0_CLIENT_ID'],
  ENV['AUTH0_CLIENT_SECRET'],
  ENV['AUTH0_DOMAIN'],
  {
    authorize_params: {
      scope: 'openid read:users write:order',
      audience: 'https://mydomain/api'
    },
    authorize_params_passthru: ['param1']
  }

... which will tell the strategy to send those parameters on every authentication request if they exist in the request

Authentication hash

The Auth0 strategy will provide the standard OmniAuth hash attributes:

  • :provider - the name of the strategy, in this case auth0
  • :uid - the user identifier
  • :info - the result of the call to /userinfo using OmniAuth standard attributes
  • :credentials - tokens requested and data
  • :extra - Additional info obtained from calling /userinfo in the :raw_info property
{
  :provider => 'auth0',
  :uid => 'auth0|USER_ID',
  :info => {
    :name => 'John Foo',
    :email => '[email protected]',
    :nickname => 'john',
    :image => 'https://example.org/john.jpg'
  },
  :credentials => {
    :token => 'ACCESS_TOKEN',
    :expires_at => 1485373937,
    :expires => true,
    :refresh_token => 'REFRESH_TOKEN',
    :id_token => 'JWT_ID_TOKEN',
    :token_type => 'bearer',
  },
  :extra => {
    :raw_info => {
      :email => '[email protected]',
      :email_verified => 'true',
      :name => 'John Foo',
      :picture => 'https://example.org/john.jpg',
      :user_id => 'auth0|USER_ID',
      :nickname => 'john',
      :created_at => '2014-07-15T17:19:50.387Z'
    }
  }
}

Contribution

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

Support + Feedback

  • Use Community for usage, questions, specific cases.
  • Use Issues here for code-level support and bug reports.
  • Paid customers can use Support to submit a trouble ticket for production-affecting issues.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

What is Auth0?

Auth0 helps you to easily:

  • implement authentication with multiple identity providers, including social (e.g., Google, Facebook, Microsoft, LinkedIn, GitHub, Twitter, etc), or enterprise (e.g., Windows Azure AD, Google Apps, Active Directory, ADFS, SAML, etc.)
  • log in users with username/password databases, passwordless, or multi-factor authentication
  • link multiple user accounts together
  • generate signed JSON Web Tokens to authorize your API calls and flow the user identity securely
  • access demographics and analytics detailing how, when, and where users are logging in
  • enrich user profiles from other data sources using customizable JavaScript rules

Why Auth0?

License

The OmniAuth Auth0 strategy is licensed under MIT - LICENSE

How to Create a Release

Releases happen in CircleCI when a tag is pushed to the repository.

To create a release, you will need to do the following:

  1. Change the version in lib/omniauth-auth0/version.rb to the new version and create a PR with the change.
  2. Once the PR is merged, switch to the master branch and git pull.
  3. git tag <version from version.rb>
  4. git push origin --tags

CircleCI will see the tag push, build, and release a new version of the library.