# 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`:
If you need install for ecto versions > 2.0, then use
def deps do
[{:authable, "~> 0.5.0"}]
end
If you need install for ecto versions > 1.0 and < 2.0, then use
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,
ecto_repos: [Authable.Repo],
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.AuthorizationCodeGrantType,
client_credentials: Authable.ClientCredentialsGrantType,
password: Authable.PasswordGrantType,
refresh_token: Authable.RefreshTokenGrantType
},
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.
4. 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
5. Run migrations for Authable.Repo (Note: all id fields are UUID type):
mix ecto.migrate -r Authable.Repo
6. 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