OpenID Connect

v0.2.2

OpenID Connect

OpenID Connect v0.2.2 OpenIDConnect View Source

Handles a majority of the life-cycle concerns with OpenID Connect

Link to this section Summary

Types

claims()

The payload of user data from the provider

documents()

A provider’s documents

error(name)

An error tuple

jwt()

JSON Web Token

name()

The name of the genserver

params()

Query param map

provider()

The provider name as an atom

reason()

A string reason for an error failure

success(value)

The success tuple

uri()

URI as a string

Functions

authorization_uri(provider, params \\ %{}, name \\ :openid_connect)

Builds the authorization URI according to the spec in the providers discovery document

fetch_tokens(provider, params, name \\ :openid_connect)

Fetches the authentication tokens from the provider

update_documents(config)

Requests updated documents from the provider

verify(provider, jwt, name \\ :openid_connect)

Verifies the validity of the JSON Web Token (JWT)

Link to this section Types

Link to this type claims() View Source 
claims() :: map()

The payload of user data from the provider

Link to this type documents() View Source 
documents() :: %{
  discovery_document: map(),
  jwk: JOSE.JWK.t(),
  remaining_lifetime: integer() | nil
}

A provider’s documents

  • discovery_document: the provider’s discovery document for OpenID Connect
  • jwk: the provider’s certificates converted into a JOSE JSON Web Key
  • remaining_lifetime: how long the provider’s JWK is valid for
Link to this type error(name) View Source 
error(name) :: {:error, name, reason()}

An error tuple

The 2nd element will indicate which function failed The 3rd element will give details of the failure

Link to this type jwt() View Source 
jwt() :: String.t()

JSON Web Token

See: https://jwt.io/introduction/

Link to this type name() View Source 
name() :: atom()

The name of the genserver

This is optional and will default to :openid_connect unless overridden

Link to this type params() View Source 
params() :: map()

Query param map

Link to this type provider() View Source 
provider() :: atom()

The provider name as an atom

Example: :google

This atom should match what you’ve used in your application config

Link to this type reason() View Source 
reason() ::
  String.t()
  | %HTTPoison.Error{__exception__: term(), id: term(), reason: term()}
  | %HTTPoison.Response{
      body: term(),
      headers: term(),
      request: term(),
      request_url: term(),
      status_code: term()
    }

A string reason for an error failure

Link to this type success(value) View Source 
success(value) :: {:ok, value}

The success tuple

The 2nd element will be the relevant value to work with

Link to this type uri() View Source 
uri() :: String.t()

URI as a string

Link to this section Functions

Link to this function authorization_uri(provider, params \\ %{}, name \\ :openid_connect) View Source 
authorization_uri(provider(), params(), name()) :: uri()

Builds the authorization URI according to the spec in the providers discovery document

The params option can be used to add additional query params to the URI

Example:

OpenIDConnect.authorization_uri(:google, %{"hd" => "dockyard.com"})

It is highly suggested that you add the state param for security reasons. Your OpenID Connect provider should have more information on this topic.

Link to this function fetch_tokens(provider, params, name \\ :openid_connect) View Source 
fetch_tokens(provider(), params(), name()) ::
  success(map()) | error(:fetch_tokens)

Fetches the authentication tokens from the provider

The params option should at least include the key/value pairs of the response_type that was requested during authorization. params may also include any one-off overrides for token fetching.

Link to this function update_documents(config) View Source 
update_documents(list()) :: success(documents()) | error(:update_documents)

Requests updated documents from the provider

This function is used by OpenIDConnect.Worker for document updates according to the lifetime returned by the provider

Link to this function verify(provider, jwt, name \\ :openid_connect) View Source 
verify(provider(), jwt(), name()) :: success(claims()) | error(:verify)

Verifies the validity of the JSON Web Token (JWT)

This verification will assert the token’s encryption against the provider’s JSON Web Key (JWK)