document 2FA provider development

developer_manual/app/index.rst

@@ -115,6 +115,9 @@ Creating, deleting, updating, searching, login and logout:
 
 * :doc:`users`
 
+Writing a two-factor auth provider:
+* :doc:`two-factor-provider`
+
 Hooks
 -----
 Listen on events like user creation and execute code:

developer_manual/app/two-factor-provider.rst

@@ -0,0 +1,103 @@
+====================
+Two-factor Providers
+====================
+
+.. sectionauthor:: Christoph Wurst <christoph@owncloud.com>
+
+Two-factor auth providers apps are used to plug custom second factors into the ownCloud core. The following
+code was taken from the `two-factor test app`_.
+
+.. _`two-factor test app`: https://github.com/ChristophWurst/twofactor_test
+
+Implementing a simple two-factor auth provider
+==============================================
+Two-factor auth providers must implement the ``OCP\Authentication\TwoFactorAuth\IProvider`` interface. The
+example below shows a minimalistic example of such a provider.
+
+.. code-block:: php
+
+	namespace OCA\TwoFactor_Test\Provider;
+
+	use OCP\Authentication\TwoFactorAuth\IProvider;
+	use OCP\IUser;
+	use OCP\Template;
+
+	class TwoFactorTestProvider implements IProvider {
+
+	/**
+	 * Get unique identifier of this 2FA provider
+	 *
+	 * @return string
+	 */
+	public function getId() {
+		return 'test';
+	}
+
+	/**
+	 * Get the display name for selecting the 2FA provider
+	 *
+	 * @return string
+	 */
+	public function getDisplayName() {
+		return 'Test';
+	}
+
+	/**
+	 * Get the description for selecting the 2FA provider
+	 *
+	 * @return string
+	 */
+	public function getDescription() {
+		return 'Use a test provider';
+	}
+
+	/**
+	 * Get the template for rending the 2FA provider view
+	 *
+	 * @param IUser $user
+	 * @return Template
+	 */
+	public function getTemplate(IUser $user) {
+		// If necessary, this is also the place where you might want
+		// to send out a code via e-mail or SMS.
+
+		// 'challenge' is the name of the template
+		return new Template('twofactor_test', 'challenge');
+	}
+
+	/**
+	 * Verify the given challenge
+	 *
+	 * @param IUser $user
+	 * @param string $challenge
+	 */
+	public function verifyChallenge(IUser $user, $challenge) {
+		if ($challenge === 'passme') {
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Decides whether 2FA is enabled for the given user
+	 *
+	 * @param IUser $user
+	 * @return boolean
+	 */
+	public function isTwoFactorAuthEnabledForUser(IUser $user) {
+		// 2FA is enforced for all users
+		return true;
+	}
+
+	}
+
+Registering a two-factor auth provider
+======================================
+You need to inform the ownCloud core that the app provides two-factor auth functionality. Two-factor
+providers are registered via ``info.xml``.
+
+.. code-block:: XML
+
+	<two-factor-providers>
+		<provider>OCA\TwoFactor_Test\Provider\TwoFactorTestProvider</provider>
+	</two-factor-providers>