Skip to content

Latest commit

 

History

History
120 lines (79 loc) · 3.97 KB

README.md

File metadata and controls

120 lines (79 loc) · 3.97 KB
Raw

Authable

OAuth2 Provider implementation modules and helpers using ecto and postgress for any elixir application.

Installation

The package can be installed as:

  1. Add authable to your list of dependencies in mix.exs:

    def deps do [{:authable, "~> 0.4.0"}] end

  2. Ensure authable is started before your application:

    def application do [applications: [:authable]] end

  3. Add authable configurations to your config/config.exs file:

    config :authable, repo: Authable.Repo, resource_owner: Authable.Models.User, token_store: Authable.Models.Token, client: Authable.Models.Client, app: Authable.Models.App, expires_in: %{ access_token: 3600, refresh_token: 24 * 3600, authorization_code: 300, session_token: 30 * 24 * 3600 }, strategies: %{ authorization_code: Authable.GrantTypes.AuthorizationCode, client_credentials: Authable.GrantTypes.ClientCredentialsGrantType, password: Authable.GrantTypes.Password, refresh_token: Authable.GrantTypes.RefreshToken }, scopes: ~w(read write session)

If you want to disable a strategy then delete from strategies config.

If you want to add a new strategy then add your own module with authorize(params) function and return a Authable.Models.Token struct.

  1. Add database configurations for the Authable.Repo on env config files:

    config :authable, Authable.Repo, adapter: Ecto.Adapters.Postgres, username: "", password: "", database: "", hostname: "", pool_size: 10

  2. Run migrations for Authable.Repo (Note: all id fields are UUID type):

    mix ecto.migrate -r Authable.Repo

  3. You are ready to go!

Usage

Generic Token Storage

To handle all possible token types, a generic token storage scheme is used for Authable.Models.Token. So, it can be used for all OAuth2 tokens and any other token scheme like confirmation token, password recovery tokens, mail list tokens, session tokens and etc...

  :name, :string # Name of the token
  :value, :string # Value of the token
  :expires_at, :integer # Unix timestamp for when the token will expire
  :details, :jsonb # Storage for all other information
  :user_id # User(resource owner) foreign key

Authorizing an App (Install App)

To authorize an app Authable.OAuth2.authorize_app/2 function can be used.

Generating Access Token

Authable has 4 grant types (authorization_code, password, client_credentials and refresh_token) to get an access token by default. To extend or use your own grant-type strategy, add your strategy into config and implement authorize(params) function and return a Authable.Models.Token struct.

Authable.OAuth2.authorize(params) will automatically determine which strategy to use by grant type. Then it authorize client and returns an access token to make further requests to resource server.

Note: To enable a strategy add it to config and to disable a strategy remove from the config.

Authentication Helpers

Authable has 2 main authentication patterns,

  1. Basic Authentication header resolver and
  2. Token Authentication, including Bearer token and Session token.

All authentication patterns return on success a Authable.Models.User struct and on all other conditions it returns nil.

Test

To run tests, jump into authable directory and run the command:

mix test

Contributing

Issues, Bugs, Documentation, Enhancements

  1. Fork the project
  2. Make your improvements and write your tests.
  3. Make a pull request.

To add new strategy:

Authable is an extensible module, you can create your strategy and share as hex package(Which can be listed on Wiki pages).

Todo

  • Documentation
  • HMAC Auth will be added as a new external strategy

References

https://tools.ietf.org/html/rfc6749