API Reference plugoid v0.6.0

modules
Modules

basic-use
Basic use

defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  use Plugoid.RedirectURI

  pipeline :oidc_auth do
    plug Plugoid,
      issuer: "https://repentant-brief-fishingcat.gigalixirapp.com",
      client_id: "client1",
      client_config: PlugoidDemo.OpenIDConnect.Client
  end

  scope "/private", MyAppWeb do
    pipe_through :browser
    pipe_through :oidc_auth

    get "/", PageController, :index
    post "/", PageController, :index
  end
end

plug-options
Plug options

mandatory-plug-options
Mandatory plug options

:client_id [Mandatory]: the client id to be used for interaction with the OpenID Provider (OP)
:client_config [Mandatory]: a module that implements the OIDC.ClientConfig behaviour and returns the client configuration
:issuer [Mandatory]: the OpenID Provider (OP) issuer. Server metadata and keys are automatically retrieved from it if the OP supports it

additional-plug-options
Additional plug options

:acr_values: one of:
- nil [Default]: no acr values requested
- [String.t()]: a list of acr values
:acr_values_callback: a opt_callback/0 that dynamically returns a list of ACRs. Called only if :acr_values is not set
:claims: the "claims" parameter
:claims_callback: a opt_callback/0 that dynamically returns the claim parameter. Called only if :claims is not set
:display: display parameter. Mostly unused. Defaults to nil
:error_view: the error view to be called in case of error. See the Error handling section bellow. If not set, it will be automatically set to MyApp.ErrorView where MyApp is the base module name of the application
:id_token_iat_max_time_gap: max time gap to accept an ID token, in seconds. Defaults to 30
:login_hint_callback: a opt_callback/0 that dynamically returns the login hint parameter
:max_age: the OIDC max age (non_neg_integer()) parameter
:max_concurrent_state_session: maximum of state sessions stored concurrently. Defaults to 4, set to nil for no limits. See On state cookies
:oauth2_metadata_updater_opts: options that will be passed to Oauth2MetadataUpdater. Some authorization server do not follow standards when forming the metadata's URI. In such a case, you might need to use the :url_construction option of Oauth2MetadataUpdater
:on_unauthenticated: action to be taken when the request is not authenticated. One of:
- :auth [Default]: redirects to the authorization endpoint of the OP
- :fail: returns an HTTP 401 error
- :pass: hands over the request to the next plug. The request is unauthenticated (this can be checked using the authenticated?/1 function)
:on_unauthorized: action to be taken when the user is not authorized, because of invalid ACR. One of:
- :auth [Default]: redirects to the authorization endpoint of the OP
- :fail: returns an HTTP 403 error
:preserve_initial_request: a boolean. Defaults to false. See further Preserving request parameters
:prompt: one of the standard values ("none", "login", "consent", or "select_account")
:prompt_callback: a opt_callback/0 that dynamically returns the prompt parameter. Called only if :prompt is not set
:redirect_uri: the redirect URI the OP has to use for redirect. If not set, defaults to Myapp.Router.Helpers.openid_connect_redirect_uri(Myapp.Endpoint, :call) It asumes that such a route was installed. See also Plugoid.RedirectURI for automatic installation of this route and the available helpers.
:response_mode: one of:
- "query"
- "fragment"
- "form_post"
:response_mode_callback: a opt_callback/0 that dynamically returns the response mode for the request. Called only if :response_mode is not set
:response_type: one of:
- "code" (code flow)
- "id_token" (implicit flow)
- "id_token token" (implicit flow)
- "code token" (hybrid flow)
- "code id_token" (hybrid flow)
- "code id_token token" (hybrid flow)
:response_type_callback: a opt_callback/0 that dynamically returns the response type for the request. Called only if :response_type is not set
:session_lifetime: the local session duration in seconds. After this time interval, the user is considered unauthenticated and is redirected again to the OP. Defaults to 3600
:scope: a list of scopes ([String.t()]) to be requested. The "openid" scope is automatically requested. The "offline_access" scope is to be added here if one wants OAuth2 tokens to remain active after the user's logout from the OP
:server_metadata: a OIDC.server_metadata/0 of server metadata that will take precedence over those of the issuer (published on the "https://issuer/.well-known/openid-configuration" URI). Useful to override one or more server metadata fields
ui_locales: a list of UI locales
:use_nonce: one of:
- :when_mandatory [Default]: a nonce is included when using the implicit and hybrid flows
- :always: always include a nonce (i.e. also in the code flow in which it is optional)