/active-openid

Utilities and ring-/reitit middleware to talk to an Openid-connect idetity provider.

Primary LanguageClojureEclipse Public License 2.0EPL-2.0

This library provides utilities to interact with an OpenID identity provider (idp) via Clojure.

Description

active-openid will try to discover Openid-endpoints at configured identity providers. Multiple identity providers can be configured.

Installation

Include the following in your project’s deps.edn file (or leiningen, boot, … Clojars):

https://img.shields.io/clojars/v/de.active-group/active-openid.svg

{:deps {...
        de.active-group/active-openid {:git/tag "0.2.4" :git/sha "<sha256>"}
        ...}}

Configuration

… via active.clojure.config

active-openid provides a configuration section for projects using active.clojure.config from =active-clojure=. Below is the configuration schema. An example configuration file can be found here.



Include the schema openid-schema via a section in your code like this


(ns your.ns
  (:require [active.clojure.config :as active-config]
            [active.clojure.openid.config :as openid-config]))

(def openid-section
  (config/section
    :openid
    openid-config/openid-schema))


Usage


Add active.clojure.openid/wrap-openid-authentication to your middleware stack.
  That guards your routes from unauthenticted users and offers authentication.


Use active.clojure.openid/user-info-from-request to obtain information about
  the logged-in user in your handlers from the current request.  If the user is
  logged in, it returns an active.clojure.openid/UserInfo record with ID,
  display name, email, groups and additional information.


The data structure that represents a logged-in user also contains information on
  how to logout the user, i.e. the URI and parameters needed to submit to the
  logout endpoint.  See active.clojure.openid/logout-link-hiccup and
  active.clojure.openid/logout-form-hiccup how to use and render it.


To support logout, wrap your logout handler with
  active.clojure.openid/wrap-openid-logout on the same route that
  wrap-openid-authentication uses as its logout-endpoint.


See ./example for details.


Authorization Code Flow


This library implements OpenID’s [Authorization Code
  Flow](https://tools.ietf.org/html/rfc6749#section-4.1).  This works for regular
  web apps and server-side apps where the source code is not publicly exposed.
  The exchange must happen server-side because during this exchange the server
  must also pass along your application’s Client Secret, which must always be kept
  secure.


This also works for single-page applications when we guard the route that serves
  the application since the authentication then happens not in the application
  itself but beforehand on the server side.  So we are fine.


When we serve a single-page application without such a guard, this library is
  not sufficient.  Then we need to implement [Authorization Code Flow with Proof
  Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) in the
  client, so we need to implement it in ClojureScript.  For that we should
  abstract a lot of the code in this library that takes care of building and
  parsing the various requests and replies into cljc namespaces that we can then
  use in both Clojure- and ClojureScript-specific implementations.  Of course,
  doing the actual requests will differ.  But this could probably also be
  abstracted with a monadic implementation with different monad runners.


Here are some useful links:



Note on IDP configuration


    
  
  • If the IDP does not use wildcards in redirect uris, they should use the one
    that the application uses as its `:base-uri` in the configuration.
    • 



Development


For your convenience, this project includes a minimal shell.nix file.
  Just run


nix-shell --pure



and you should be good to go.


Running tests


active-openid provides a Makefile with a test target.  To run
  the tests:


make test



Deploy a new release


active-openid provides a Makefile with a deploy target.  To
  Release a new version to Clojars, the deploy target relies on two
  environment variables


    
  
  • CLOJARS_USERNAME:  Your clojars username.
    • 
  
  • CLOJARS_PASSWORD:  Your clojars cli token.
    
    To publish a new release, run:
    
    
    CLOJARS_USERNAME=<username> CLOJARS_PASSWORD=<cli-token> make deploy
    
    
  
    • 



License


Copyright © 2022-2023 Active Group GmbH


Distributed under the Eclipse Public License either version 2.0 or (at your option) any later version. (see LICENSE)


[0/3]


Some of the todos for this project.