OAuth2 Provider implementation modules and helpers using plug, ecto and postgress for any elixir application.
The package can be installed as:
- Add authable to your list of dependencies in
mix.exs:
Only for ecto versions > 2.0
defdepsdo[{:authable,"~> 0.8.0"}]end- Ensure authable is started before your application:
defapplicationdo[applications: [:authable]]end- Add authable configurations to your
config/config.exsfile:
config:authable,ecto_repos: [Authable.Repo],repo: Authable.Repo,resource_owner: Authable.Model.User,token_store: Authable.Model.Token,client: Authable.Model.Client,app: Authable.Model.App,expires_in: %{access_token: 3600,refresh_token: 24*3600,authorization_code: 300,session_token: 30*24*3600},grant_types: %{authorization_code: Authable.GrantType.AuthorizationCode,client_credentials: Authable.GrantType.ClientCredentials,password: Authable.GrantType.Password,refresh_token: Authable.GrantType.RefreshToken},auth_strategies: %{headers: %{"authorization"=>[{~r/Basic ([a-zA-Z\-_\+=]+)/,Authable.Authentication.Basic},{~r/Bearer ([a-zA-Z\-_\+=]+)/,Authable.Authentication.Bearer},],"x-api-token"=>[{~r/([a-zA-Z\-_\+=]+)/,Authable.Authentication.Bearer}]},query_params: %{"access_token"=>Authable.Authentication.Bearer},sessions: %{"session_token"=>Authable.Authentication.Session}},scopes: ~w(read write session),renderer: Authable.Renderer.RestApiIf you want to disable a grant type then delete from grant types config.
If you want to add a new grant type then add your own module with authorize(params) function and return a Authable.Model.Token struct.
- Add database configurations for the
Authable.Repoon env config files:
config:authable,Authable.Repo,adapter: Ecto.Adapters.Postgres,username: "",password: "",database: "",hostname: "",pool_size: 10- Run migrations for Authable.Repo (Note: all id fields are UUID type):
mixecto.migrate-rAuthable.Repo- You are ready to go!
Please refer to hex docs for each module, function details and samples https://hexdocs.pm/authable.
Authable supports 3 main authentication types by default using Plug.Conn. You can add or remove authentication types using configuration. On successful authentication, resource owner automatically set on conn.assigns[:current_user] immutable.
- Sessions
Reads session for configured sessions keys and passes to the matched authenticator to authenticate.
- Query Params
Reads query params for configured query_params keys and passes to the matched authenticator to authenticate.
- Headers
Reads headers for configured headers keys and passes to the matched authenticator to authenticate.
Configure your application OAuth2 scopes on configuration. Then add import Authable.Plug.Authenticate with scopes into your controller.
defmoduleSomeModule.AppControllerdouseSomeModule.Web,:controllerplugAuthable.Plug.Authenticate,[scopes: ~w(read write)]defindex(conn,_params)do# access to current user on successful authenticationcurrent_user=conn.assigns[:current_user]...endenddefmoduleSomeModule.AppControllerdouseSomeModule.Web,:controllerplugAuthable.Plug.Authenticate,[scopes: ~w(read write)]whenactionin[:create]defindex(conn,_params)do# anybody can call this action...enddefcreate(conn,_params)do# only logged in users can access this actioncurrent_user=conn.assigns[:current_user]...endend# if you need to allow a resource only unauthorized thendefmoduleSomeModule.AppControllerdouseSomeModule.Web,:controllerplugAuthable.Plug.UnauthorizedOnlywhenactionin[:register]defregister(conn,_params)do# only not logged in user can access this actionendendOn failure of authentication, authable renders as a RestApi json format, if you need to change the format file you need to implement the behaviour of Authable.Renderer and then change the renderer configuration.
Currently, authable library supports by default authorization code, client credentials, password, and refresh token OAuth2 authorizations. You can add or remove grant types using configuration.
To authorize a client for resources, all you need to do is calling OAuth2.authorize method with necessary params, on successful authorization Authable.Model.Token struct will return, on failure {:error, errors, http_status_code}.
# For authorization_code grant typeAuthable.OAuth2.authorize(%{"grant_type"=>"authorization_code","client_id"=>"52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e","client_secret"=>"Wi7Y_Q5LU4iIwJArgqXq2Q","redirect_uri"=>"http://localhost:4000/oauth2/callbacks","code"=>"W_hb8JEDmeYChsNfOGCmbQ","scope"=>"read"# optional})# For client_credentials grant typeAuthable.OAuth2.authorize(%{"grant_type"=>"client_credentials","client_id"=>"52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e","client_secret"=>"Wi7Y_Q5LU4iIwJArgqXq2Q","scope"=>"read"# optional})# For password grant typeAuthable.OAuth2.authorize(%{"grant_type"=>"password","email"=>"foo@example.com","password"=>"12345678","client_id"=>"52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e","scope"=>"read"# optional})# For refresh_token grant typeAuthable.OAuth2.authorize(%{"grant_type"=>"refresh_token","client_id"=>"52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e","client_secret"=>"Wi7Y_Q5LU4iIwJArgqXq2Q","refresh_token"=>"XJaVz3lCFC9IfifBriA-dw","scope"=>"read"# optional})# You can adjust token expiration durations from configuration.Authorizing client may mean installing client or giving permission to a client to make OAuth2 Authorization requests and allowing resources with selected scopes. To authorize a client for a resource owner, you need to call OAuth2.authorize_app function.
Authable.OAuth2.authorize_app(user,%{"client_id"=>"52024ca6-cf1d-4a9d-bfb6-9bc5023ad56e","redirect_uri"=>"http://localhost:4000/oauth2/callbacks","scope"=>"read,write"})To change models, you have two options:
You may change the module name from configuration
You may copy Authable.Model.XXX and update it on your app.
To run tests, jump into authable directory and run the command:
mix testFork the project
Make your improvements and write your tests.
Make a pull request.
Authable is an extensible module, you can create your strategy and share as hex package(Which can be listed on Wiki pages).
- HMAC Auth will be added as a new external strategy
MIT