From 1b28e6a5565b6c03e131609034c20c3083fead5e Mon Sep 17 00:00:00 2001 From: Peter Boling Date: Mon, 3 Feb 2025 00:41:14 +0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index eb81094..f04eeab 100644 --- a/README.md +++ b/README.md @@ -42,15 +42,30 @@ [đŸ–‡patreon-img]: https://img.shields.io/badge/patreon-donate-yellow.svg [đŸ–‡patreon]: https://patreon.com/galtzo -Provides a thin wrapper around [`ruby-openid2`](https://github.com/oauth-xx/ruby-openid2), a modernized fork of the -ancient-and-archived `ruby-openid` gem from JanRan. - -To understand what OpenID is about and how it works, it helps to read the documentation for lib/openid/consumer.rb -from that gem. - -The specification used is http://openid.net/specs/openid-authentication-2_0.html. - -In the early days of Rails, this was an official Rails' plugin, written by DHH. See [Credits](#credits) for more information. +Provides a thin wrapper around _[rack-openid2](https://github.com/oauth-xx/rack-openid2)_, +which itself is a thin wrapper around _[ruby-openid2](https://github.com/oauth-xx/ruby-openid2)_. +These are modernized forks of the +ancient-and-archived `rack-openid` and `ruby-openid` gems from JanRain, +an [early sponsor](https://en.wikipedia.org/wiki/OpenID#History) of OpenID standards. + +To understand what OpenID is about and how it works, +it helps to read the documentation for [lib/openid/consumer.rb](https://github.com/oauth-xx/ruby-openid2/blob/main/lib/openid/consumer.rb) +from the `ruby-openid2` gem. + +The specifications used are [OpenID Authentication 2.0](http://openid.net/specs/openid-authentication-2_0.html), +and [OpenID Attribute Exchange 1.0](http://openid.net/specs/openid-attribute-exchange-1_0.html). +These are considered [obsolete standards](https://openid.net/developers/specs/), +having been super-ceded by OpenID Connect. +In general, if you have a choice, a solution based on OpenID Connect, +which is itself based on the modern OAuth 2.0 specification, will be a better choice. + +This library is mature, and used in production. Maintenance should be expected for security issues and some bugfixes. + +In the early days of Rails, this was an official Rails plugin, written by DHH. See [Credits](#credits) for more information. + +NOTE: This gem does not implement OpenID Connect, which is effectively version 3.0 of the OpenID standard. +This gem is _not_ based on OAuth 2.0 as OpenID 2.0 was developed before OAuth existed. +OTOH, OpenID Connect is based on OAuth 2.0, but you'll need a different library for that. ## Installation