decisiv/omniauth-okta

OAuth2 strategy for Okta

OmniAuth Okta OAuth2 Strategy

Strategy to authenticate with Okta via OAuth2 in OmniAuth.

This strategy uses Okta's OpenID Connect API with OAuth2. See their developer docs for more details.

Installation

Add this line to your application's Gemfile:

gem 'omniauth-okta'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install omniauth-okta

OmniAuth

Here's an example for adding the middleware to a Rails app in config/initializers/omniauth.rb:

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :okta, ENV['OKTA_CLIENT_ID'], ENV['OKTA_CLIENT_SECRET'], {
    client_options: {
      site:                 'https://your-org.okta.com',
      authorization_server: '<authorization_server>',
      authorize_url:        'https://your-org.okta.com/oauth2/<authorization_server>/v1/authorize',
      token_url:            'https://your-org.okta.com/oauth2/<authorization_server>/v1/token',
      user_info_url:        'https://your-org.okta.com/oauth2/<authorization_server>/v1/userinfo',
      audience:             'api://your-audience'
    }
  }
end

Devise

First define your application id and secret in config/initializers/devise.rb.

Configuration options can be passed as the last parameter here as key/value pairs.

config.omniauth :okta, ENV['OKTA_CLIENT_ID'], ENV['OKTA_CLIENT_SECRET'], {}

or add options like the following:

  require 'omniauth-okta'
  config.omniauth(:okta,
                  ENV['OKTA_CLIENT_ID'],
                  ENV['OKTA_CLIENT_SECRET'],
                  scope: 'openid profile email',
                  fields: ['profile', 'email'],
                  client_options: {
                    site:          'https://your-org.okta.com',
                    authorize_url: 'https://your-org.okta.com/oauth2/default/v1/authorize',
                    token_url:     'https://your-org.okta.com/oauth2/default/v1/token',
                    user_info_url: 'https://your-org.okta.com/oauth2/default/v1/userinfo',
                  },
                  strategy_class: OmniAuth::Strategies::Okta)

Then add the following to 'config/routes.rb' so the callback routes are defined.

devise_for :users, controllers: { omniauth_callbacks: 'users/omniauth_callbacks' }

Make sure your model is omniauthable. Generally this is "/app/models/user.rb"

devise :omniauthable, omniauth_providers: [:okta]

Auth Hash

Here's an example of an authentication hash available in the callback by accessing request.env['omniauth.auth']:

{
  "provider" => "okta",
  "uid" => "0000000000000001",
  "info" => {
    "name" => "John Smith",
    "email" => "[email protected]",
    "first_name" => "John",
    "last_name" => "Smith",
    "image" => "https://photohosting.com/john.jpg"
  },
  "credentials" => {
    "token" => "TOKEN",
    "expires_at" => 1496617411,
    "expires" => true
  },
  "extra" => {
    "raw_info" => {
      "sub" => "0000000000000001",
      "name" => "John Smith",
      "locale" => "en-US",
      "email" => "[email protected]",
      "picture" => "https://photohosting.com/john.jpg",
      "website" => "https://example.com",
      "preferred_username" => "[email protected]",
      "given_name" => "John",
      "family_name" => "Smith",
      "zoneinfo" => "America/Los_Angeles",
      "updated_at" => 1496611646,
      "email_verified" => true
    },
    "id_token" => "TOKEN",
    "id_info" => {
      "ver" => 1,
      "jti" => "AT.D2sslkfjdsldjf899n090sldkfj",
      "iss" => "https://your-org.okta.com",
      "aud" => "https://your-org.okta.com",
      "sub" => "[email protected]",
      "iat" => 1496613811,
      "exp" => 1496617411,
      "cid" => "CLIENT_ID",
      "uid" => "0000000000000001",
      "scp" => ["email", "profile", "openid"]
    }
  }
}

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

The gem is available as open source under the terms of the MIT License.