Ü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.