1 files changed, 41 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b598e19
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# RedirectAuth
+
+A MediaWiki extension to enable authentication via an external identity provider.
+Note that this extension does not implement any authentication protocol
+but instead provides a simple interface for the extension user to do so.
+
+The extension is [documented on mediawiki.org](https://www.mediawiki.org/wiki/Extension:RedirectAuth).
+
+## Design
+
+This extension was specifically designed for the scenario that a wiki
+already has users using MediaWiki's default authentication mechanism of
+(username, passsword) credentials.
+
+1. Users who don't yet have a wiki account can log in through the
+   external identity provider and create their wiki account with the
+   click of a button.
+2. Users who already have a wiki account can link it with their external
+   account and then use it for logging in going forward.
+
+The extension maintains its own mapping of external user identifiers to
+local user ids (allowing accounts to be linked even when they have
+different usernames). The extension enforces the mapping to be 1:1,
+meaning a wiki account can only be linked to one external identity and
+one external identity can only be linked to one wiki account. Care has
+been taken that existing wiki accounts cannot be maliciously overtaken
+via the 3rd party login (existing wiki accounts can only be linked to an
+external account if you're already logged in as the wiki account).
+
+## Non-goals
+
+* supporting more than one external identity provider per wiki
+* supporting any authentication protocols out of the box
+
+## Credits
+
+Thanks to Florian Schmidt for his [Extension:GoogleLogin] extension.
+Looking at its source code helped me understand MediaWiki's
+`PrimaryAuthenticationProvider` API.
+
+[Extension:GoogleLogin]: https://www.mediawiki.org/wiki/Extension:GoogleLogin