# Intro

A Keycloak client to easily manage authenetication, with minimum effort. KeycloakEx is made up of clients and plugs. There are 2 clients:

* `KeycloakEx.Client.User` - Requires a client to be setup in keycloak and for security should be the primary client to be used. The client is utilised to verify tokens and redirect if the token is incorrect.
* `KeycloakEx.Client.Admin` - Admin Client to easily connect with keycload admin REST API, so as to be able to manage keycloak or get information that is not possible from clients.

There are also 2 plugs. Each usefull in different scenarios:

* `KeycloakEx.VerifyBearerToken` - Ideal for API scenarios where the token is not managed by the backend. Where the token is received in the header  as authorisation bearer token. The plug will verify  the validty of the token and responde accordingly.
        
* `KeycloakEx.VerifySessionToken` - Ideal for Phoenix HTML/Live views but the token is managed by the backend. Plug would manage token in the session.
  
**NOTE**

  From keycloak 18 there where a number of update one of which is the removel of "auth" from the host_uri.
  The plugin was update to remove /auth from the uri by default. So if you are utilising an older version of
  Keycloak its importat to add "/auth" as part of the host_uri ex:  host_uri: "http://localhost:8081/auth"

# Setup

## User Client

To create a User Client. Add the following snippet in a config.exs file:

    config :test_app, TestApp.KeycloakClient,
        realm: "test_app",
        client_id: "testapp-portal",
        site: "http://localhost:4000",
        scope: "testapp_scope",
        host_uri: "http://localhost:8081"

Create module with the user client code

      defmodule TestApp.KeycloakClient do
          use KeycloakEx.Client.User,
            otp_app: :test_app
      end

## Admin Client

  To create an Admin Client. Add the following snippet in a config.exs file:

    config :test_app, TestApp.KeycloakAdmin,
      realm: "master",
      username: "admin",
      password: "test123!",
      client_id: "admin-cli",
      client_secret: "83bf8d8e-e608-477b-b812-48b9ac4aa43a",
      host_uri: "http://localhost:8081"

  Create module with the admin client code

    defmodule TestApp.KeycloakAdmin do
      use KeycloakEx.Client.Admin,
        otp_app: :test_app
    end

## Plugs

As mentioned in the introduction the library has 2 different plugs which can be used in different scenarions.

### Verify Authorization Bearer Access Token

In the case when the access token is handled by a third party such as the front-end. Utilise the VerifyBearerToken, the plug would check the token and introspect the values of it and redirect if incorret.

    plug KeycloakEx.VerifyBearerToken, client: TestApp.KeycloakClient

### Manage token from the backend.

In the case where the access token is managed by the backend in the plug session, utilise the VerifySessionToken.

    plug KeycloakEx.VerifySessionToken, client: TestApp.KeycloakClient

Its important to also handle the call back when handling the access token from the backend. For this add the following route in the phoenix router.ex.

    get "/login_cb", UserController, :login_redirect

In the controller its important to get the token from the code passed in the call back

    defmodule TestApp.UserController do
        use TestAppWeb, :controller

        def login_redirect(conn, params) do
          token =
            TestApp.KeycloakClient.get_token!(code: params["code"])

          conn
          |> put_session(:token, token.token)
          |> redirect(to: "/")
          |> halt()
        end
    end