Lightning.AuthProviders.OauthHTTPClient (Lightning v2.13.5)

Handles OAuth interactions for generic providers, including token fetching, refreshing, and user information retrieval. This module uses Tesla to make HTTP requests configured with middleware appropriate for OAuth specific tasks.

Returns structured error responses that integrate well with the audit system.

Summary

Types

option()

Options that may be passed to a request function. See request/2 for detailed descriptions.

Functions

delete(client, url, opts)

Perform a DELETE request.

delete!(client, url, opts)

Perform a DELETE request.

fetch_token(client, code)

Fetches a new token using the authorization code provided by the OAuth provider.

fetch_userinfo(client, token)

Fetches user information from the OAuth provider using a valid access token.

generate_authorize_url(client, params)

Generates an authorization URL with specified parameters.

get(client, url, opts)

Perform a GET request.

get!(client, url, opts)

Perform a GET request.

head(client, url, opts)

Perform a HEAD request.

head!(client, url, opts)

Perform a HEAD request.

options(client, url, opts)

Perform a OPTIONS request.

options!(client, url, opts)

Perform a OPTIONS request.

patch(client, url, body, opts)

Perform a PATCH request.

patch!(client, url, body, opts)

Perform a PATCH request.

post(client, url, body, opts)

Perform a POST request.

post!(client, url, body, opts)

Perform a POST request.

put(client, url, body, opts)

Perform a PUT request.

put!(client, url, body, opts)

Perform a PUT request.

refresh_token(client, token)

Refreshes an existing token using the refresh token.

request(client \\ %Tesla.Client{}, options)

Perform a request.

request!(client \\ %Tesla.Client{}, options)

Perform request and raise in case of error.

revoke_token(client, token)

Revokes an OAuth token.

trace(client, url, opts)

Perform a TRACE request.

trace!(client, url, opts)

Perform a TRACE request.

Types

option()

@type option() ::
  {:method, Tesla.Env.method()}
  | {:url, Tesla.Env.url()}
  | {:query, Tesla.Env.query()}
  | {:headers, Tesla.Env.headers()}
  | {:body, Tesla.Env.body()}
  | {:opts, Tesla.Env.opts()}

Options that may be passed to a request function. See request/2 for detailed descriptions.

Functions

delete(client, url, opts)

@spec delete(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a DELETE request.

See request/1 or request/2 for options definition.

delete("/users")
delete("/users", query: [scope: "admin"])
delete(client, "/users")
delete(client, "/users", query: [scope: "admin"])
delete(client, "/users", body: %{name: "Jon"})

delete!(client, url, opts)

@spec delete!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a DELETE request.

See request!/1 or request!/2 for options definition.

delete!("/users")
delete!("/users", query: [scope: "admin"])
delete!(client, "/users")
delete!(client, "/users", query: [scope: "admin"])
delete!(client, "/users", body: %{name: "Jon"})

fetch_token(client, code)

Fetches a new token using the authorization code provided by the OAuth provider.

Parameters

client: The client configuration containing client_id, client_secret, and token_endpoint.
code: The authorization code received from the OAuth provider.

Returns

{:ok, token_data} on success
{:error, %{status: integer(), error: term(), details: map()}} on failure

fetch_userinfo(client, token)

Fetches user information from the OAuth provider using a valid access token.

Parameters

client: The client configuration containing userinfo_endpoint.
token: The token configuration containing access_token.

Returns

{:ok, user_info} on success
{:error, %{status: integer(), error: term(), details: map()}} on failure

generate_authorize_url(client, params)

Generates an authorization URL with specified parameters.

Parameters

client: The client configuration containing client_id, and authorization_endpoint.
params: Additional parameters to include in the authorization URL.

Returns

The fully formed authorization URL as a string.

get(client, url, opts)

@spec get(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a GET request.

See request/1 or request/2 for options definition.

get("/users")
get("/users", query: [scope: "admin"])
get(client, "/users")
get(client, "/users", query: [scope: "admin"])
get(client, "/users", body: %{name: "Jon"})

get!(client, url, opts)

@spec get!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a GET request.

See request!/1 or request!/2 for options definition.

get!("/users")
get!("/users", query: [scope: "admin"])
get!(client, "/users")
get!(client, "/users", query: [scope: "admin"])
get!(client, "/users", body: %{name: "Jon"})

head(client, url, opts)

@spec head(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a HEAD request.

See request/1 or request/2 for options definition.

head("/users")
head("/users", query: [scope: "admin"])
head(client, "/users")
head(client, "/users", query: [scope: "admin"])
head(client, "/users", body: %{name: "Jon"})

head!(client, url, opts)

@spec head!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a HEAD request.

See request!/1 or request!/2 for options definition.

head!("/users")
head!("/users", query: [scope: "admin"])
head!(client, "/users")
head!(client, "/users", query: [scope: "admin"])
head!(client, "/users", body: %{name: "Jon"})

options(client, url, opts)

@spec options(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a OPTIONS request.

See request/1 or request/2 for options definition.

options("/users")
options("/users", query: [scope: "admin"])
options(client, "/users")
options(client, "/users", query: [scope: "admin"])
options(client, "/users", body: %{name: "Jon"})

options!(client, url, opts)

@spec options!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a OPTIONS request.

See request!/1 or request!/2 for options definition.

options!("/users")
options!("/users", query: [scope: "admin"])
options!(client, "/users")
options!(client, "/users", query: [scope: "admin"])
options!(client, "/users", body: %{name: "Jon"})

patch(client, url, body, opts)

@spec patch(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a PATCH request.

See request/1 or request/2 for options definition.

patch("/users", %{name: "Jon"})
patch("/users", %{name: "Jon"}, query: [scope: "admin"])
patch(client, "/users", %{name: "Jon"})
patch(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

patch!(client, url, body, opts)

@spec patch!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a PATCH request.

See request!/1 or request!/2 for options definition.

patch!("/users", %{name: "Jon"})
patch!("/users", %{name: "Jon"}, query: [scope: "admin"])
patch!(client, "/users", %{name: "Jon"})
patch!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

post(client, url, body, opts)

@spec post(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a POST request.

See request/1 or request/2 for options definition.

post("/users", %{name: "Jon"})
post("/users", %{name: "Jon"}, query: [scope: "admin"])
post(client, "/users", %{name: "Jon"})
post(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

post!(client, url, body, opts)

@spec post!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a POST request.

See request!/1 or request!/2 for options definition.

post!("/users", %{name: "Jon"})
post!("/users", %{name: "Jon"}, query: [scope: "admin"])
post!(client, "/users", %{name: "Jon"})
post!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

put(client, url, body, opts)

@spec put(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.result()

Perform a PUT request.

See request/1 or request/2 for options definition.

put("/users", %{name: "Jon"})
put("/users", %{name: "Jon"}, query: [scope: "admin"])
put(client, "/users", %{name: "Jon"})
put(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

put!(client, url, body, opts)

@spec put!(Tesla.Env.client(), Tesla.Env.url(), Tesla.Env.body(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a PUT request.

See request!/1 or request!/2 for options definition.

put!("/users", %{name: "Jon"})
put!("/users", %{name: "Jon"}, query: [scope: "admin"])
put!(client, "/users", %{name: "Jon"})
put!(client, "/users", %{name: "Jon"}, query: [scope: "admin"])

refresh_token(client, token)

Refreshes an existing token using the refresh token.

Parameters

client: The client configuration containing client_id, client_secret, and token_endpoint.
token: The token configuration containing refresh_token

Returns

{:ok, refreshed_token_data} on success with preserved refresh_token
{:error, %{status: integer(), error: term(), details: map()}} on failure

request(client \\ %Tesla.Client{}, options)

@spec request(Tesla.Env.client(), [option()]) :: Tesla.Env.result()

Perform a request.

Options

:method - the request method, one of [:head, :get, :delete, :trace, :options, :post, :put, :patch]
:url - either full url e.g. "http://example.com/some/path" or just "/some/path" if using Tesla.Middleware.BaseUrl
:query - a keyword list of query params, e.g. [page: 1, per_page: 100]
:headers - a keyword list of headers, e.g. [{"content-type", "text/plain"}]
:body - depends on used middleware:
- by default it can be a binary
- if using e.g. JSON encoding middleware it can be a nested map
- if adapter supports it it can be a Stream with any of the above
:opts - custom, per-request middleware or adapter options

Examples

ExampleApi.request(method: :get, url: "/users/path")

# use shortcut methods
ExampleApi.get("/users/1")
ExampleApi.post(client, "/users", %{name: "Jon"})

request!(client \\ %Tesla.Client{}, options)

@spec request!(Tesla.Env.client(), [option()]) :: Tesla.Env.t() | no_return()

Perform request and raise in case of error.

This is similar to request/2 behaviour from Tesla 0.x

See request/2 for list of available options.

revoke_token(client, token)

Revokes an OAuth token.

Attempts to revoke both access_token and refresh_token for comprehensive cleanup. Per RFC 7009, providers should invalidate related tokens when one is revoked.

Parameters

client: The client configuration containing client_id, client_secret, and revocation_endpoint.
token: The token data containing access_token and refresh_token.

Returns

:ok on success (any token successfully revoked)
{:error, %{status: integer(), error: term(), details: map()}} on failure

trace(client, url, opts)

@spec trace(Tesla.Env.client(), Tesla.Env.url(), [option()]) :: Tesla.Env.result()

Perform a TRACE request.

See request/1 or request/2 for options definition.

trace("/users")
trace("/users", query: [scope: "admin"])
trace(client, "/users")
trace(client, "/users", query: [scope: "admin"])
trace(client, "/users", body: %{name: "Jon"})

trace!(client, url, opts)

@spec trace!(Tesla.Env.client(), Tesla.Env.url(), [option()]) ::
  Tesla.Env.t() | no_return()

Perform a TRACE request.

See request!/1 or request!/2 for options definition.

trace!("/users")
trace!("/users", query: [scope: "admin"])
trace!(client, "/users")
trace!(client, "/users", query: [scope: "admin"])
trace!(client, "/users", body: %{name: "Jon"})