Misc doc changes

Besides other documentation changes, this commit ensures the generated
HTML doc for HexDocs.pm will become the source of truth for this Elixir
library and leverage on latest features of ExDoc.

.formatter.exs

@@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

.gitignore

@@ -1,7 +1,26 @@
-/_build
-/cover
-/deps
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
 erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
 *.ez
-*.beam
-/doc
+
+# Ignore package tarball (built via "mix hex.build").
+ueberauth_okta-*.tar
+
+# Temporary files, for example, from tests.
+/tmp/

CHANGELOG.md

@@ -1,27 +1,34 @@
 # Changelog
 
-## v0.3.0
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## v0.3.0 - 2021-07-30
 
 Potentially breaking changes
 
 * bump `ueberauth` 0.7.0 - If you require >= 0.6 then you may need to
   adjust things before updating
   * support CSRF attack protection bia the `with_state_param` from ueberauth (thanks @Jonathan-Arias!)
 
-## v0.2.1
+## v0.2.1 - 2021-06-01
 
 No breaking changes
 
 * Fix some compiler warnings (Thanks @zillou!)
 * Bump development/release deps
 
-## v0.2.0
+## v0.2.0 - 2020-10-19
 
 Addresses issues between Okta API and OAuth2 implementation (Thanks @Deconstrained)
 
 * The client credentials are included in both the body (params) and in the basic authorization header; Okta will issue a 403 in response to this.
 * Okta's response containing the access token is JSON-encoded, and since oauth2 does not by default support the JSON mimetype, the JSON string containing the token is treated as the token itself, which results in a 401 when making the final request to authenticate the user back to Okta.
 
-## v0.1.0
+## v0.1.0 - 2018-04-25
 
-Initial Release
+* Initial Release

LICENSE → LICENSE.md

@@ -1,4 +1,4 @@
-MIT License
+# MIT License
 
 Copyright (c) 2018 Jon Carstens
 

README.md

@@ -1,8 +1,16 @@
 # Überauth Okta
-Okta strategy for Überauth
 
-## Setup
-Add `:ueberauth_okta` to your list of dependencies in mix.exs:
+[![Module Version](https://img.shields.io/hexpm/v/ueberauth_okta.svg)](https://hex.pm/packages/ueberauth_okta)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ueberauth_okta/)
+[![Total Download](https://img.shields.io/hexpm/dt/ueberauth_okta.svg)](https://hex.pm/packages/ueberauth_okta)
+[![License](https://img.shields.io/hexpm/l/ueberauth_okta.svg)](https://github.com/jjcarstens/ueberauth_okta/blob/master/LICENSE.md)
+[![Last Updated](https://img.shields.io/github/last-commit/jjcarstens/ueberauth_okta.svg)](https://github.com/jjcarstens/ueberauth_okta/commits/master)
+
+> Okta strategy for Überauth.
+
+## Installation
+
+Add `:ueberauth_okta` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
@@ -11,13 +19,15 @@ end
 ```
 
 Add the strategy to your applications:
+
 ```elixir
 def application do
   [extra_applications: [:ueberauth_okta]]
 end
 ```
 
-Include the provider in your configuration for Ueberauth
+Include the provider in your configuration for Ueberauth:
+
 ```elixir
 config :ueberauth, Ueberauth,
   providers: [
@@ -67,3 +77,9 @@ This is just the start `ueberauth_okta` strategy for support with Okta auth prot
 
 - [x] OAuth 2.0
 - [ ] SAML
+
+## Copyright and License
+
+Copyright (c) 2018 Jon Carstens
+
+Released under the [MIT License](./LICENSE.md).

lib/ueberauth/strategy/okta.ex

@@ -3,30 +3,47 @@ defmodule Ueberauth.Strategy.Okta do
   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:
+
+  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
+    * 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:
+
       config :ueberauth, Ueberauth,
         providers: [
           okta: { Ueberauth.Strategy.Okta, [] }
         ]
-  Then include the configuration for okta.
+
+  Then include the configuration for Okta:
+
       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"
-  If you haven't already, create a pipeline and setup routes for your callback handler
+
+  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
+
+  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
@@ -36,18 +53,33 @@ defmodule Ueberauth.Strategy.Okta 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`)
+
+  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:
+
+  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]] }
+          okta: {
+            Ueberauth.Strategy.Okta,
+            [oauth2_params: [scope: "openid email", max_age: 3600]]
+          }
         ]
-  See [Okta OAuth2 documentation](https://developer.okta.com/docs/api/resources/oidc#authorize) for list of parameters. _Note that not all parameters are compatible with this flow_
+
+  See [Okta OAuth2
+  documentation](https://developer.okta.com/docs/api/resources/oidc#authorize)
+  for list of parameters.
+
+  _Note that not all parameters are compatible with this flow_.
   """
   use Ueberauth.Strategy, uid_field: :sub,
                           oauth2_module: Ueberauth.Strategy.Okta.OAuth,

lib/ueberauth/strategy/okta/oauth.ex

@@ -1,13 +1,17 @@
 defmodule Ueberauth.Strategy.Okta.OAuth do
   @moduledoc """
-  An implementation of OAuth2 for okta.
+  An implementation of OAuth2 for Okta.
+
+  Required values are `site`, `client_id`, `client_secret` and should be
+  included in your configuration:
 
-  Required values are `site`, `client_id`, `client_secret` and should be included in your configuration.
       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")
-  You can also include options from the `OAuth2.Client` struct which will take precedence.
+
+  You can also include options from the `OAuth2.Client` struct which will take
+  precedence.
   """
   require Jason
   use OAuth2.Strategy
@@ -25,9 +29,15 @@ defmodule Ueberauth.Strategy.Okta.OAuth do
   Construct a client for requests to Okta.
 
   Optionally include any OAuth2 options here to be merged with the defaults.
-      Ueberauth.Strategy.Okta.OAuth.client(redirect_uri: "http://localhost:4000/auth/okta/callback")
+
+      Ueberauth.Strategy.Okta.OAuth.client(
+        redirect_uri: "http://localhost:4000/auth/okta/callback"
+      )
+
   This will be setup automatically for you in `Ueberauth.Strategy.Okta`.
-  These options are only useful for usage outside the normal callback phase of Ueberauth.
+
+  These options are only useful for usage outside the normal callback phase of
+  Ueberauth.
   """
   def client(opts \\ []) do
 

mix.exs

@@ -5,21 +5,21 @@ defmodule Ueberauth.Okta.Mixfile do
   @source_url "https://github.com/jjcarstens/ueberauth_okta"
 
   def project do
-    [app: :ueberauth_okta,
-     version: @version,
-     name: "Ueberauth Okta",
-     package: package(),
-     elixir: "~> 1.3",
-     build_embedded: Mix.env == :prod,
-     start_permanent: Mix.env == :prod,
-     description: description(),
-     deps: deps(),
-     docs: docs(),
-     preferred_cli_env: [
-       docs: :docs,
-       "hex.build": :docs,
-       "hex.publish": :docs
-     ]
+    [
+      app: :ueberauth_okta,
+      version: @version,
+      name: "Ueberauth Okta",
+      elixir: "~> 1.3",
+      build_embedded: Mix.env() == :prod,
+      start_permanent: Mix.env() == :prod,
+      package: package(),
+      deps: deps(),
+      docs: docs(),
+      preferred_cli_env: [
+        docs: :docs,
+        "hex.build": :docs,
+        "hex.publish": :docs
+      ]
     ]
   end
 
@@ -29,37 +29,38 @@ defmodule Ueberauth.Okta.Mixfile do
 
   defp deps do
     [
-     {:jason, "~> 1.2"},
-     {:oauth2, "~> 2.0"},
-     {:ueberauth, "~> 0.7"},
-
-     # dev/test only dependencies
-     {:credo, "~> 1.5", only: [:dev, :test]},
-
-     # docs dependencies
-     {:ex_doc, "~> 0.24", only: :docs}
+      {:jason, "~> 1.2"},
+      {:oauth2, "~> 2.0"},
+      {:ueberauth, "~> 0.7"},
+      {:credo, "~> 1.5", only: [:dev, :test]},
+      {:ex_doc, ">= 0.0.0", only: :docs, runtime: false}
     ]
   end
 
   defp docs do
     [
-      extras: ["README.md", "CHANGELOG.md"],
+      extras: [
+        "CHANGELOG.md": [],
+        "LICENSE.md": [title: "License"],
+        "README.md": [title: "Overview"]
+      ],
       main: "readme",
-      source_ref: "v#{@version}",
       source_url: @source_url,
+      source_ref: "v#{@version}",
+      formatters: ["html"],
       skip_undefined_reference_warnings_on: ["CHANGELOG.md"]
     ]
   end
 
-  defp description do
-    "An Ueberauth strategy for using Okta to authenticate your users."
-  end
-
   defp package do
     [
-      files: ["CHANGELOG.md", "lib", "mix.exs", "README.md", "LICENSE"],
+      description: "An Ueberauth strategy for using Okta to authenticate your users.",
+      files: ["CHANGELOG.md", "lib", "mix.exs", "README.md", "LICENSE.md"],
       licenses: ["MIT"],
-      links: %{"GitHub": @source_url}
+      links: %{
+        Changelog: "https://hexdocs.pm/ueberauth_okta/changelog.html",
+        GitHub: @source_url
+      }
     ]
   end
 end