Überauth

https://hexdocs.pm/ueberauth
Admin
Überauth is an Elixir authentication system and a two-phase framework for Plug-based web...
Tokens:4,584
Snippets:45
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Fetch Project Dependencies with Mix

Source: https://hexdocs.pm/ueberauth/readme

After adding Überauth (or any other dependency) to your `mix.exs` file, run this command in your project's root directory to download and install the dependencies.

```bash
mix deps.get

```

--------------------------------

### Plug Ueberauth into Phoenix Controller

Source: https://hexdocs.pm/ueberauth/Ueberauth

This example shows how to integrate the Ueberauth plug into a Phoenix controller. The plug should be placed before your application's routes to intercept authentication-related requests. Ueberauth uses pattern matching for URL routing, ensuring strategies only activate for relevant requests.

```elixir
defmodule MyApp.AuthController do
  use MyApp.Web, :controller
  plug Ueberauth

  ... 
end
```

--------------------------------

### Customizing HTTP Methods for Callbacks

Source: https://hexdocs.pm/ueberauth/Ueberauth

Overriding the default HTTP method (GET) for callback URLs.

```APIDOC
## Http Methods
By default, all callback URLs are only available via the `"GET"` method. You can override this via options to your strategy.

**Example:**
```elixir
providers: [
  identity: {Ueberauth.Strategies.Identity, [callback_methods: ["POST"]]}
]
```
```

--------------------------------

### Override HTTP Methods for Ueberauth Callbacks in Elixir

Source: https://hexdocs.pm/ueberauth/index

This configuration snippet demonstrates how to override the default HTTP method for Ueberauth callback URLs. By default, callbacks only accept GET requests. This example shows how to configure the Identity strategy to accept POST requests for its callback.

```elixir
providers: [
  identity: {Ueberauth.Strategies.Identity, [callback_methods: ["POST"]]}
]
```

--------------------------------

### Override HTTP Method for Ueberauth Callbacks in Elixir

Source: https://hexdocs.pm/ueberauth/readme

Allows overriding the default HTTP method for callback URLs from 'GET' to other methods like 'POST'. This can be configured on a per-strategy basis.

```elixir
providers: [
  identity: {Ueberauth.Strategies.Identity, [callback_methods: ["POST" C]]}
]
```

--------------------------------

### Fetch Project Dependencies with Mix

Source: https://hexdocs.pm/ueberauth/index

This command fetches all the dependencies listed in your `mix.exs` file, including Überauth. Run this command in your project's root directory after adding new dependencies.

```bash
mix deps.get
```

--------------------------------

### Ueberauth Init Function

Source: https://hexdocs.pm/ueberauth/Ueberauth

Implements the `Plug.init/1` function for Ueberauth, responsible for initializing the plug with given options.

```elixir
init(options \\ [])
```

--------------------------------

### Per-OTP App Ueberauth Configuration

Source: https://hexdocs.pm/ueberauth/Ueberauth

Shows how to configure Ueberauth instances differently for multiple OTP applications by using OTP app-specific configuration and passing the `:otp_app` option to the Ueberauth plug.

```elixir
config :my_app, Ueberauth,
  providers: [
    …
  ]
```

```elixir
defmodule MyApp.Admin.AuthController do
  use MyApp.Web, :controller
  plug Ueberauth,
    otp_app: :my_app,
    providers: [:identity],
    base_path: "/admin/auth"
end
```

--------------------------------

### Callback Phase Paths

Source: https://hexdocs.pm/ueberauth/Ueberauth

The default callback paths for Ueberauth providers.

```APIDOC
## Callback Phase Paths
/auth/facebook/callback
/auth/github/callback
```

--------------------------------

### Ueberauth Strategy Helper Functions (Elixir)

Source: https://hexdocs.pm/ueberauth/Ueberauth.Strategy

This snippet includes various helper functions for Ueberauth strategies written in Elixir. These functions assist in managing connection parameters, generating URLs, and setting errors within the Plug.Conn object. They are crucial for implementing custom authentication strategies.

```elixir
def add_state_param(conn, value)
  conn |> assign(:ueberauth_state, value)
end

def allowed_callback_method?(conn)
  allowed_callback_methods(conn) |> Enum.member?(conn.method)
end

def allowed_callback_methods(conn)
  options(conn)[:allowed_callback_methods] || ["GET", "POST"]
end

def callback_params(conn, query_params \ []) do
  whitelisted_params = options(conn)[:callback_params]
  params = query_params || conn.params

  if whitelisted_params do
    Enum.reduce(whitelisted_params, %{}, fn
      key, acc when is_atom(key) -> Map.put(acc, Atom.to_string(key), params[Atom.to_string(key)])
      key, acc -> Map.put(acc, key, params[key])
    end)
  else
    params
  end
end

def callback_path(conn)
  request_path(conn)
end

def callback_url(conn, query_params \ []) do
  request_url(conn, query_params)
end

def error(key, message)
  %{message_key: key, message: message}
end

def options(conn)
  conn.assigns[:ueberauth_options] || []
end

def redirect!(conn, url)
  conn |> Plug.Conn.redirect(to: url) |> Plug.Conn.halt()
end

def request_path(conn)
  options(conn)[:request_path] || "/auth/:provider"
end

def request_url(conn, query_params \ []) do
  path = request_path(conn)
  query = URI.encode_query(query_params)
  url = URI.join(base_url(conn), path)
  if query != "", do: url <> "?" <> query, else: url
end

def set_errors!(conn, errors)
  assign(conn, :ueberauth_errors, errors)
end

def strategy(conn)
  conn.assigns[:ueberauth_strategy]
end

def strategy_name(conn)
  conn.assigns[:ueberauth_strategy_name]
end

def with_state_param(opts, conn)
  state = conn.assigns[:ueberauth_state]
  if state, do: Keyword.put_new(opts, :state, state), else: opts
end

defp assign(conn, key, value)
  %Plug.Conn{conn | assigns: Map.put(conn.assigns, key, value)}
end

defp base_url(conn)
  scheme = conn.scheme
  host = conn.host
  port = if conn.port == 80 || conn.port == 443, do: "", else: ":" <> Integer.to_string(conn.port)
  "#{scheme}://#{host}#{port}"
end

```

--------------------------------

### Customizing Ueberauth Paths

Source: https://hexdocs.pm/ueberauth/Ueberauth

Illustrates how to customize absolute request and callback paths for specific Ueberauth strategies, such as the Identity provider, by setting options directly within the configuration.

```elixir
config :ueberauth, Ueberauth,
  base_path: "/login", # default is "/auth"
  providers: [
    identity: {Ueberauth.Strategies.Identity, [request_path: "/login/identity",
                                               callback_path: "/login/identity/callback"]}
  ],
  json_library: Poison # or Jason
```

--------------------------------

### Provider Configuration Per OTP App

Source: https://hexdocs.pm/ueberauth/Ueberauth

Configuring Ueberauth with different providers for multiple OTP applications.

```APIDOC
## Provider Configuration Per OTP App
When using Ueberauth in multiple OTP apps with different provider configurations, you should set differing configurations under the name of your OTP app.

**Example Configuration in `config.exs`:**
```elixir
config :my_app, Ueberauth, 
  providers: [
    ...
  ]
```

**Example Usage in Controller:**
```elixir
defmodule MyApp.Admin.AuthController do
  use MyApp.Web, :controller
  plug Ueberauth,
    otp_app: :my_app,
    providers: [:identity],
    base_path: "/admin/auth"
end
```
This ensures that values set under your own namespace are used with priority over globally configured values.
```

--------------------------------

### Customizing Callback Paths

Source: https://hexdocs.pm/ueberauth/Ueberauth

How to customize request and callback paths on a per-strategy basis.

```APIDOC
## Customizing Paths
Paths can be configured on a per-strategy basis by setting options on the provider. Note that these paths are absolute.

**Example Configuration:**
```elixir
config :ueberauth, Ueberauth,
  base_path: "/login", # default is "/auth"
  providers: [
    identity: {Ueberauth.Strategies.Identity, [request_path: "/login/identity",
                                               callback_path: "/login/identity/callback"]}
  ],
  json_library: Poison # or Jason
```
```

--------------------------------

### Customizing Ueberauth Callback Scheme

Source: https://hexdocs.pm/ueberauth/Ueberauth

Explains how to specify a custom callback scheme for Ueberauth, either by using the `X-Forwarded-Proto` header or by overriding it via strategy options.

```nginx
proxy_set_header X-Forwarded-Proto $scheme;
```

```elixir
providers: [
  identity: {Ueberauth.Strategies.Identity, [callback_scheme: "https"]}
]
```

--------------------------------

### Ueberauth Functions

Source: https://hexdocs.pm/ueberauth/Ueberauth

Details the core functions available in the Ueberauth library.

```APIDOC
## Functions
### auth(conn)
Fetches a successful authentication from the `Plug.Conn`. This should only be called after the callback phase has run.

```elixir
@spec auth(Plug.Conn.t()) :: Ueberauth.Auth.t()
```

### call(conn, routes)
Implements `Plug.call/2`.

### init(options \\ [])
Implements `Plug.init/1`.

### json_library(otp_app \\ nil)
Fetches the configured JSON library. Defaults to `Jason` but can be configured to `Poison`.

**Configuration Examples:**
```elixir
# Global configuration
config :ueberauth, Ueberauth, json_library: Jason

# Per-app configuration
config :my_app, Ueberauth, json_library: Jason
```

Requires the `jason` or `poison` dependency in `mix.exs`.

### run_callback(conn, provider_name, arg, options \\ [])
Requests authentication against a provider.

### run_request(conn, provider_name, arg, options \\ [])
Requests authentication against a provider.
```

--------------------------------

### Add Überauth Dependency to Mix Project

Source: https://hexdocs.pm/ueberauth/readme

This snippet shows how to add Überauth as a project dependency in your Elixir `mix.exs` file. Ensure you are using a compatible version of Überauth.

```elixir
defp deps do
  # Add the dependency
  [{:ueberauth, "~> 0.10"}]
end
```

--------------------------------

### Ueberauth Call Function

Source: https://hexdocs.pm/ueberauth/Ueberauth

Implements the `Plug.call/2` function for Ueberauth, handling incoming requests and routing them appropriately.

```elixir
call(conn, routes)
```

--------------------------------

### Define Ueberauth.Auth.Info Struct Type

Source: https://hexdocs.pm/ueberauth/Ueberauth.Auth

Defines the structure of the Ueberauth.Auth.Info type. This struct holds various user-related information fields, each with specified types or nil.

```elixir
@type t() :: %Ueberauth.Auth.Info{
  birthday: binary() | nil,
  description: binary() | nil,
  email: binary() | nil,
  first_name: binary() | nil,
  image: binary() | nil,
  last_name: binary() | nil,
  location: binary() | nil,
  name: binary() | nil,
  nickname: binary() | nil,
  phone: binary() | nil,
  urls: map()
}
```

--------------------------------

### Fetch Ueberauth JSON Library Configuration

Source: https://hexdocs.pm/ueberauth/Ueberauth

Retrieves the configured JSON library (e.g., Jason or Poison) used by Ueberauth. This configuration can be set globally or per OTP app.

```elixir
config :ueberauth, Ueberauth, json_library: Jason
```

```elixir
config :my_app, Ueberauth, json_library: Jason
```

```elixir
json_library(otp_app \\ nil)
```

--------------------------------

### Customizing Ueberauth Callback Port

Source: https://hexdocs.pm/ueberauth/Ueberauth

Demonstrates how to override the default `Plug.Conn` port for Ueberauth callbacks by specifying a custom port through strategy options.

```elixir
providers: [
  identity: {Ueberauth.Strategies.Identity, [callback_port: 4000]}
]
```

--------------------------------

### Integrate Ueberauth Plug in Phoenix Controller

Source: https://hexdocs.pm/ueberauth/readme

Adds the Ueberauth plug to a Phoenix controller to handle authentication requests. This plug should be placed before other application routes to ensure it intercepts authentication flows correctly.

```elixir
defmodule MyApp.AuthController do
  use MyApp.Web, :controller
  plug Ueberauth
  ...
end
```

--------------------------------

### Configure Ueberauth Providers in Elixir

Source: https://hexdocs.pm/ueberauth/readme

Defines a list of authentication providers (e.g., Facebook, GitHub) for Ueberauth in the application's configuration file. The provider name is used for routing and in the Ueberauth.Auth struct. Options can be passed to customize strategy behavior.

```elixir
config :ueberauth, Ueberauth,
  providers: [
    facebook: { Ueberauth.Strategy.Facebook, [ opt1: "value", opts2: "value" ] },
    github: { Ueberauth.Strategy.Github, [ opt1: "value", opts2: "value" ] }
  ]
```

--------------------------------

### Customizing Schemes

Source: https://hexdocs.pm/ueberauth/Ueberauth

Overriding the default scheme (derived from Plug.Conn) with a custom scheme.

```APIDOC
## Customizing Schemes
By default, Ueberauth uses your `Plug.Conn` scheme. A custom scheme can be provided via the `X-Forwarded-Proto` request header or by overriding it via strategy options.

**Example using Nginx:**
```nginx
proxy_set_header X-Forwarded-Proto $scheme;
```

**Example overriding via strategy options:**
```elixir
providers: [
  identity: {Ueberauth.Strategies.Identity, [callback_scheme: "https"]}
]
```
```

--------------------------------

### Ueberauth Callback Function for GitHub Authentication

Source: https://hexdocs.pm/ueberauth/Ueberauth

Handles the callback from an authentication provider, specifically for GitHub. It configures the GitHub strategy with necessary paths and scopes before running the callback through Ueberauth.

```elixir
def callback(conn, %{"provider_name" => provider_name} = _params) do
  provider_config = case provider_name do
    "github" ->
      { Ueberauth.Strategy.Github, [
        default_scope: "user",
        request_path:  provider_auth_path(conn, :request, provider_name),
        callback_path: provider_auth_path(conn, :callback, provider_name)
      ]}
  end
  conn
  |> Ueberauth.run_callback(provider_name, provider_config)
  |> handle_callback(params, provider)
end
```

--------------------------------

### Customizing Ports

Source: https://hexdocs.pm/ueberauth/Ueberauth

Overriding the default port (derived from Plug.Conn) for callbacks.

```APIDOC
## Customizing Ports
By default, Ueberauth uses your `Plug.Conn` port. You can override this via options to your strategy.

**Example:**
```elixir
providers: [
  identity: {Ueberauth.Strategies.Identity, [callback_port: 4000]}
]
```
```

--------------------------------

### Configure Ueberauth Providers in Elixir

Source: https://hexdocs.pm/ueberauth/Ueberauth

Demonstrates how to configure Ueberauth to use a specific list of providers within an Elixir application, allowing for selective integration of authentication services.

```elixir
defmodule MyApp.Admin.AuthController do
  use MyApp.Web, :controller
  plug Ueberauth, providers: [:identity], base_path: "/admin/auth"
end
```

--------------------------------

### Ueberauth Auth Function

Source: https://hexdocs.pm/ueberauth/Ueberauth

Fetches a successful authentication result from a `Plug.Conn` object. This function should only be called after the callback phase has been completed.

```elixir
@spec auth(Plug.Conn.t()) :: Ueberauth.Auth.t()
```

--------------------------------

### Configure Ueberauth Providers

Source: https://hexdocs.pm/ueberauth/Ueberauth

This configuration defines the authentication providers to be used by Ueberauth. It specifies the strategy module and any associated options for each provider. The provider name is used for routing and within the `Ueberauth.Auth` struct.

```elixir
config :ueberauth, Ueberauth,
  providers: [
    facebook: {Ueberauth.Strategy.Facebook, [opt1: "value", opts2: "value"]},
    github: {Ueberauth.Strategy.Github, [opt1: "value", opts2: "value"]}
  ]
```

--------------------------------

### Ueberauth Request Function for Dynamic Provider Authentication

Source: https://hexdocs.pm/ueberauth/Ueberauth

Initiates an authentication request to a specified provider. This function allows for dynamic provider selection and configuration, including setting scopes and callback paths, demonstrated with the GitHub provider.

```elixir
def request(conn, %{"provider_name" => provider_name} = _params) do
  provider_config = case provider_name do
    "github" ->
      { Ueberauth.Strategy.Github, [
        default_scope: "user",
        request_path:  provider_auth_path(conn, :request, provider_name),
        callback_path: provider_auth_path(conn, :callback, provider_name)
      ]}
  end
  conn
  |> Ueberauth.run_request(provider_name, provider_config)
end
```

--------------------------------

### Define Ueberauth.Failure.Error Struct

Source: https://hexdocs.pm/ueberauth/Ueberauth.Failure

Defines the structure for a Ueberauth.Failure.Error, used to represent authentication failures. It includes a human-readable message and a machine-interpretable message key.

```Elixir
@type t() :: %Ueberauth.Failure.Error{message: binary(), message_key: binary()}
```

--------------------------------

### Selective Provider Inclusion

Source: https://hexdocs.pm/ueberauth/Ueberauth

How to include only specific providers in your Ueberauth plug configuration.

```APIDOC
## Selective Provider Inclusion
```elixir
defmodule MyApp.Admin.AuthController do
  use MyApp.Web, :controller
  plug Ueberauth, providers: [:identity], base_path: "/admin/auth"
end
```
This allows for different login points in your application by selectively using some or all providers.
```

--------------------------------

### Add State Parameter to Options - Elixir

Source: https://hexdocs.pm/ueberauth/Ueberauth.Strategy

This function adds a state parameter to the provided options. This is crucial for OAuth 2.0 flows to prevent CSRF attacks by ensuring the request originated from the user. It takes a keyword list of options and a Plug.Conn object, returning the modified options.

```elixir
def with_state_param(opts, conn) do
  state = :crypto.strong_rand_bytes(16) |> Base.url_encode64()
  Keyword.put_new(opts, :state, state)
end
```

--------------------------------

### Ueberauth Routes Type Definition

Source: https://hexdocs.pm/ueberauth/Ueberauth

Defines the `routes()` type as a list of `route()` tuples, representing all available routes for Ueberauth.

```elixir
@type routes() :: [route()]
```

--------------------------------

### Configure Ueberauth JSON Serializer in Elixir

Source: https://hexdocs.pm/ueberauth/readme

Specifies the JSON serialization library to be used by Ueberauth. Defaults to Jason, but can be changed to other libraries like Poison for flexibility.

```elixir
config :ueberauth, Ueberauth,
  json_library: Poison # default is Jason
```

--------------------------------

### Customize Ueberauth Paths in Elixir

Source: https://hexdocs.pm/ueberauth/readme

Allows customization of the base path for authentication requests and specific request/callback paths for individual providers. This is useful for organizing authentication routes within the application.

```elixir
config :ueberauth, Ueberauth,
  base_path: "/login", # default is "/auth"
  providers: [
    identity: {Ueberauth.Strategies.Identity, [request_path: "/login/identity",
                                               callback_path: "/login/identity/callback"]}
  ]
```

--------------------------------

### Ueberauth Types

Source: https://hexdocs.pm/ueberauth/Ueberauth

Defines the types used within the Ueberauth library.

```APIDOC
## Types
### method()
```elixir
@type method() :: String.t()
```

### path()
```elixir
@type path() :: String.t()
```

### route()
```elixir
@type route() :: {{path(), method()}, mfa()}
```

### routes()
```elixir
@type routes() :: [route()]
```
```

--------------------------------

### Ueberauth Route Type Definition

Source: https://hexdocs.pm/ueberauth/Ueberauth

Defines the `route()` type, which is a tuple containing a path, method, and an MFA (Module, Function, Arity) tuple, used for routing Ueberauth requests.

```elixir
@type route() :: {{path(), method()}, mfa()}
```

--------------------------------

### Ueberauth Path Type Definition

Source: https://hexdocs.pm/ueberauth/Ueberauth

Defines the `path()` type used in Ueberauth, representing a String which is a URL path.

```elixir
@type path() :: String.t()
```

--------------------------------

### Ueberauth Auth Type Definition

Source: https://hexdocs.pm/ueberauth/Ueberauth

Defines the `method()` type used in Ueberauth, representing a String which is typically an HTTP method.

```elixir
@type method() :: String.t()
```
Tokens:
Raw