# HubIdentityElixir
An Elixir Package designed to make implementing HubIdentity authentication easy and fast.
In order to use this package you need to have an account with [HubIdentity](https://stage-identity.hubsynch.com/)
Currently this is only for [Hivelocity](https://www.hivelocity.co.jp/) uses. If you have a
commercial interest please contact the Package Manager Erin Boeger through linkedIn or Github or
through [Hivelocity](https://www.hivelocity.co.jp/contact/).
## Installation
The package can be installed by adding `hub_identity_elixir` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:hub_identity_elixir, "~> 0.1.0"}
]
end
```
## Setup
Setup your configuration in `config.exs, dev.exs, prod.exs` etc:
```elixir
config :hub_identity_elixir, :url, # Either staging, production, or localhost
config :hub_identity_elixir, :public_key, # The public key from HubIdentity
```
Inside your Router add `use HubIdentityElixir.Phoenix.Router` and include
the `hub_identity_routes()`
in `router.exs`:
```elixir
defmodule MyAppWeb.Router do
use MyAppWeb, :router
use HubIdentityElixir.Phoenix.Router # <- Add HubIdentity Router
# router stuff..
scope "/", MyAppWeb do
pipe_through :browser
hub_identity_routes() # <- Add HubIdentity routes
get "/", PageController, :index
end
```
This will add the following routes to your application:
- session_path DELETE /sessions/logout HubIdentityElixir.Phoenix.SessionController :delete
- session_path GET /sessions/new HubIdentityElixir.Phoenix.SessionController :new
- session_path GET /sessions/create HubIdentityElixir.Phoenix.SessionController :create
If you want a `@current_user` helper then add `plug :fetch_current_user` to your pipeline.
## Logging a user out
It is recommended to allow two logout options.
- Logout from your Application
- Logout from HubIdentity
Both use the same logout path `sessions_destroy`
### Logout from your Application
This will clear the users session and still allow a user to login using a HubIdentity
cookie (if the cookie persists). This will allow a user who is authenticated at HubIdentity
to continue to use applications which use HubIdentity until the cookie expires.
### Logout from HubIdentity
This will clear the users session and destroy the HubIdentity cookie.
This will allow users who use other applications which use HubIdentity until they logout from them.
Then they will have to authenticate again with HubIdentity.
## Restricted routes
For authentication required (restricted) routes add the plug `require_authenticated_user`
for example:
```elixir
scope "/", MyAppWeb do
pipe_through [:browser, :require_authenticated_user]
get "/something/restricted", PageController, :something
get "/something_else/restricted", PageController, :something_else
end
```
## Documentation
Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm) at
[hub_identity_elixir](https://hexdocs.pm/hub_identity_elixir)