Ueberauth.Strategy.Okta (Ueberauth Okta v1.0.0) View Source

Provides an Ueberauth strategy for authenticating with Okta.

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 the required configuration for Okta (site, client_id, and client_secret):

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

If you have configured a custom Okta Authorization Server, you can specify it using the authorization_server_id key. This will cause request URLs to be adjusted to include the ID, saving you the effort of configuring the authorization_url, token_url etc... directly.

You can also include options for the underlying OAuth strategy. If using the default (Ueberauth.Strategy.Okta.OAuth), then options for OAuth2.Client.t() are supported

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

pipeline :auth do
  Ueberauth.plug "/auth"
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

You can edit the behaviour of the Strategy by including some options when you register your provider.

To set the uid_field: (Default is :sub):

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

To set the params that will be sent in the OAuth request, use the oauth2_params key:

config :ueberauth, Ueberauth,
  providers: [
    okta: {
      Ueberauth.Strategy.Okta,
      [oauth2_params: [scope: "openid email", max_age: 3600]]
    }
  ]

See Okta OAuth2 documentation for list of parameters.

Note that not all parameters are compatible with this flow.

Link to this section Summary

Functions

Includes the credentials from the Okta response.

Stores the raw information (including the token) obtained from the Okta callback.

Cleans up the private area of the connection used for passing the raw Okta response around during the callback.

Handles the initial redirect to the okta authentication page.

Fetches the fields to populate the info section of the Ueberauth.Auth struct.

Fetches the uid field from the Okta response. This defaults to the option uid_field which in-turn defaults to sub

Link to this section Functions

Includes the credentials from the Okta response.

Stores the raw information (including the token) obtained from the Okta callback.

Cleans up the private area of the connection used for passing the raw Okta response around during the callback.

Handles the initial redirect to the okta authentication page.

Supports state and redirect_uri params which are required for Okta /authorize request. These will also be generated if omitted. redirect_uri from the strategy config will take precedence over value provided here

Fetches the fields to populate the info section of the Ueberauth.Auth struct.

Fetches the uid field from the Okta response. This defaults to the option uid_field which in-turn defaults to sub