From f49e27b4a566dbdf9b908f2ddc9eae0fd1d4b0c6 Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Sun, 1 Aug 2021 20:39:58 +0800 Subject: [PATCH] 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 | 4 ++ .gitignore | 29 ++++++++++--- CHANGELOG.md | 17 +++++--- LICENSE => LICENSE.md | 2 +- README.md | 24 ++++++++-- lib/ueberauth/strategy/okta.ex | 56 +++++++++++++++++++----- lib/ueberauth/strategy/okta/oauth.ex | 20 ++++++--- mix.exs | 65 ++++++++++++++-------------- 8 files changed, 153 insertions(+), 64 deletions(-) create mode 100644 .formatter.exs rename LICENSE => LICENSE.md (98%) diff --git a/.formatter.exs b/.formatter.exs new file mode 100644 index 0000000..d2cda26 --- /dev/null +++ b/.formatter.exs @@ -0,0 +1,4 @@ +# Used by "mix format" +[ + inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"] +] diff --git a/.gitignore b/.gitignore index 578548b..8a0a4d8 100644 --- a/.gitignore +++ b/.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/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 7948c4a..246478f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,13 @@ # 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 @@ -8,20 +15,20 @@ Potentially breaking changes 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 diff --git a/LICENSE b/LICENSE.md similarity index 98% rename from LICENSE rename to LICENSE.md index e073c29..93266ea 100644 --- a/LICENSE +++ b/LICENSE.md @@ -1,4 +1,4 @@ -MIT License +# MIT License Copyright (c) 2018 Jon Carstens diff --git a/README.md b/README.md index 921e7af..1d8c0cc 100644 --- a/README.md +++ b/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). diff --git a/lib/ueberauth/strategy/okta.ex b/lib/ueberauth/strategy/okta.ex index fec7a2f..06c9b5b 100644 --- a/lib/ueberauth/strategy/okta.ex +++ b/lib/ueberauth/strategy/okta.ex @@ -3,22 +3,36 @@ 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 @@ -26,7 +40,10 @@ defmodule Ueberauth.Strategy.Okta 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, diff --git a/lib/ueberauth/strategy/okta/oauth.ex b/lib/ueberauth/strategy/okta/oauth.ex index c124c05..a2affb8 100644 --- a/lib/ueberauth/strategy/okta/oauth.ex +++ b/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 diff --git a/mix.exs b/mix.exs index 103d091..4d7d04e 100644 --- a/mix.exs +++ b/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