appcues/ueberauth_okta

Okta strategy for Überauth

Überauth Okta

Okta strategy for Überauth.

Installation

Add :ueberauth_okta to your list of dependencies in mix.exs:

def deps do
  [{:ueberauth_okta, "~> 1.0"}]
end

Setup

You'll need to register a new application with Okta and get the client_id and client_secret. That setup is out of the scope of this library, but some notes to remember are:

• Ensure Authorization Code grant type is enabled
• You have valid Login Redirect Urls listed for the app that correctly reference your callback route(s)
• user or group permissions may need to be added to your Okta app before successfully authenticating

Include the provider in your configuration for Ueberauth with any applicable configuration options (Okta and OAuth2 options are supported):

config :ueberauth, Ueberauth,
  providers: [
    okta: {Ueberauth.Strategy.Okta, [client_id: "12345"]}
  ]

Note: Provider options are evaluated at compile time by default (see Plug) so if you use runtime.exs or another mechanism to load options into the Application environment, you'll want to use the Ueberauth.Strategy.Okta.OAuth scope. See below for details

Okta Options

• :oauth2_module - OAuth module to use (default: Ueberauth.Strategy.Okta.OAuth)
• :oauth2_params - query parameters for the oauth request. See Okta OAuth2 documentation for list of parameters. Note that not all parameters are compatible with this flow. (default: [scope: "openid email profile"])
• :uid_field - default: :sub

OAuth2 options

The default OAuth2 module for making the requests is Ueberauth.Strategy.Okta.OAuth which uses the following options:

• :site - (required) Full request URL
• :client_id - (required) Okta client ID
• :client_secret - (required) Okta client secret
• :authorize_url - default: "/oauth2/v1/authorize",
• :token_url - default: "/oauth2/v1/token",
• :userinfo_url - default: "/oauth2/v1/userinfo"
• :authorization_server_id - If supplied, URLs for the request will be adjusted to include the custom Okta Authorization Server ID
• Any OAuth2.Client.t() option

These options can be provided with the provider settings, or under the Ueberauth.Strategy.Okta.OAuth scope:

config :ueberauth, Ueberauth.Strategy.Okta.OAuth,
  site: "https://your-doman.okta.com",
  client_id: System.get_env("OKTA_CLIENT_ID"),
  client_secret: System.get_env("OKTA_CLIENT_SECRET")

Multiple Providers (Multitenant)

To support multiple providers, scope the settings to the same provider key you used when configuring Ueberauth:

config :ueberauth, Ueberauth,
  providers: [
    okta: {Ueberauth.Strategy.Okta, []}
  ]

config :ueberauth, Ueberauth.Strategy.Okta.OAuth,
  okta: [
    site: "https://your-doman.okta.com"
    client_id: System.get_env("OKTA_CLIENT_ID"),
    client_secret: System.get_env("OKTA_CLIENT_SECRET")
  ]

Scoped OAuth settings will take precedence over the global settings

Adding Request Flow

If you haven't already, create a pipeline and setup routes for your callback handler

pipeline :auth do
  plug Ueberauth
end
scope "/auth" do
  pipe_through [:browser, :auth]
  get "/:provider/callback", AuthController, :callback
end

Create an endpoint for the callback where you will handle the Ueberauth.Auth struct

defmodule MyApp.AuthController do
  use MyApp.Web, :controller
  def callback_phase(%{ assigns: %{ ueberauth_failure: fails } } = conn, _params) do
    # do things with the failure
  end
  def callback_phase(%{ assigns: %{ ueberauth_auth: auth } } = conn, params) do
    # do things with the auth
  end
end

Copyright and License

Copyright (c) 2022 Jon Carstens

Released under the MIT License.

ueberauth_okta's Issues

Okta rejects API calls for `get_token` and the final auth exchange

Okta responds with 403 if the client credentials are included in both the basic auth header and the params when calling Okta's API to exchange an authorization code for the token. The oauth2 library by default includes the client_id in the params.

Moreover, the response from Okta with the token is JSON-encoded, and oauth2 does not a priori support JSON encoding.

Pull request #2 fixes both of these these issues by reimplementing AuthCode.get_token and configuring jason as a coder for the application/json mimetype.

I can't add scopes?

No matter what I try, the scope in the url params is always "openid email profile"

How can I override this to add scopes?

In the docs it says

oauth2_params: [scope: "openid email profile"]

but if I add that and add scopes it still doesn't change.

I've tried in both

config :ueberauth, Ueberauth,
  providers: [
    okta: {Ueberauth.Strategy.Okta, [
      oauth2_params: [scope: "openid email profile okta.users.read.self"]
    ]}
  ]

and

config :ueberauth, Ueberauth.Strategy.Okta.OAuth,
  okta: [
    oauth2_params: [scope: "openid email profile okta.users.read.self"],
    site: "https://[***].okta.com",
    client_id: "[***]",
    client_secret: "[***]"
  ]

As well as every other wording or combination I can think of...

Can't set strategy options at runtime

Hello there! After upgrading to 1.0 I can no longer set the settings at runtime. Before the latest release I had:

config.exs

config :ueberauth, Ueberauth,
  base_path: "/oauth",
  providers: [
    okta: {
      Ueberauth.Strategy.Okta,
      [
        oauth2_params: [scope: "openid email"]
      ]
    }
  ]

runtime.exs

config :ueberauth, Ueberauth.Strategy.Okta.OAuth,
  site: System.get_env("OKTA_CLIENT_SITE"),
  client_id: System.get_env("OKTA_CLIENT_ID"),
  client_secret: System.get_env("OKTA_CLIENT_SECRET")  

Using 1.0 Im doing:

config.exs

config :ueberauth, Ueberauth,
  base_path: "/oauth",
  providers: [ # it fails if I don't set the providers key
    okta: {
      Ueberauth.Strategy.Okta,
      []
    }
  ]

runtime.exs

config :ueberauth, Ueberauth,
        base_path: "/oauth",
        providers: [
          okta:
            {Ueberauth.Strategy.Okta,
             [
               site: System.get_env("OKTA_CLIENT_SITE"),
               client_id: System.get_env("OKTA_CLIENT_ID"),
               client_secret: System.get_env("OKTA_CLIENT_SECRET")
             ]}
        ]

But I keep getting

Request: GET /oauth/okta
12 ** (exit) an exception was raised:
11** (RuntimeError) [Ueberauth.Strategy.Okta.OAuth] missing required key: :client_id
10    (ueberauth_okta 1.0.0) lib/ueberauth/strategy/okta/oauth.ex:124: Ueberauth.Strategy.Okta.OAuth.validate_config_option!/2
9    (ueberauth_okta 1.0.0) lib/ueberauth/strategy/okta/oauth.ex:57: Ueberauth.Strategy.Okta.OAuth.client/1
8    (ueberauth_okta 1.0.0) lib/ueberauth/strategy/okta/oauth.ex:70: Ueberauth.Strategy.Okta.OAuth.authorize_url!/2
7    (ueberauth_okta 1.0.0) lib/ueberauth/strategy/okta.ex:152: Ueberauth.Strategy.Okta.handle_request!/1
6    (identity_gate 0.1.2) MyAppWeb.Router.auth/2
5    (identity_gate 0.1.2) lib/my_app_web/router.ex:1: MyAppWeb.Router.__pipe_through0__/1
4    (phoenix 1.6.15) lib/phoenix/router.ex:346: Phoenix.Router.__call__/2
3    (identity_gate 0.1.2) lib/my_app_web/endpoint.ex:1: MyAppWeb.Endpoint.plug_builder_call/2
2 09:15:50.751 request_id=20f9af1083ccbdf6a55d92a4ea04a5e2 [info] GET /css/app.css
1 09:15:50.751 request_id=20f9af1083ccbdf6a55d92a4ea04a5e2 [info] Sent 404 in 99µs

Any idea how can keep having the configuration in the runtime file?

Thanks!

Call to check if the session still open on the OKTA side

Hi! Is there any function to check that the user doesn't log out on the OKTA side, and then, make a decision like logging from the app side?

Docs for multi-tenant support?

Last month you merged in PR #8, which is great. However, I cannot figure out to take advantage of it. I hate to ask, but would you be able to provide some documentation on how to use this strategy in a multi-tenant environment?

In other words, assume that the client_id, client_secret, and site are all stored in the database, one set for each of my Okta customers. How would I go about calling into this strategy with these?

If I use a controller with plug Ueberauth, then this strategy takes over and retrieves the default single-tenant configuration. If I use a controller with my own request and callback actions, I can call this strategy with Ueberauth.run_request/3, but I don't know how to process the callback after calling Ueberauth.run_callback/3. Or even if that's the right approach at all.

Any help you can offer would be appreciated? Thanks.

Support multiple providers

It looks like only one global set of credentials for Okta can be used. However, Ueberauth allows multiple providers to be configured using the same strategy. So in the example given in the documentation:

config :ueberauth, Ueberauth,
  providers: [
    okta: { Ueberauth.Strategy.Okta, [] }
  ]

The provider here is :okta, but another one could be defined using this strategy, and it could require different credentials. But the credentials are provided globally for the strategy, with no reference to the individual provider:

config :ueberauth, Ueberauth.Strategy.Okta.OAuth,
  client_id: System.get_env("OKTA_CLIENT_ID"),
  client_secret: System.get_env("OKTA_CLIENT_SECRET"),
  site: "https://your-doman.okta.com"

Okta rejects API calls from this library

Okta responds with 403 if the client credentials are included in both the basic auth header and the params when calling Okta's API to exchange an authorization code for the token. The oauth2 library by default includes the client_id in the params.

Moreover, the response from Okta with the token is JSON-encoded, and oauth2 does not a priori support JSON encoding.

Pull request #2 fixes both of these these issues by reimplementing AuthCode.get_token and configuring jason as a coder for the application/json mimetype.

Ueberauth.Strategy.Okta fetch_user/2 got error message

When setting the client_id and other required config in config.exs, it will raise an error

[Ueberauth.Strategy.Okta.OAuth] missing required key: :client_id

I found out that Ueberauth.Strategy.Okta.fetch_user/2 doesn't contain |> add_oauth_options(conn) in option that triggers this error.

The easiest way is adding that pipe function in fetch_user/2?

Function Ueberauth.plug/1 is undefined or private

Defining the following pipeline in router.ex causes undefined function erro:

pipeline :auth do
  Ueberauth.plug "/auth"
end

I am running phoenix version 1.5.1
and elixir 1.7