component docs added

component/Details.md

@@ -1,76 +1,27 @@
-# Details
+Xamarin.Auth helps you authenticate users via standard authentication mechanisms 
+(e.g. OAuth 1.0 and 2.0), and store user credentials. It's also straightforward 
+to add support for non-standard authentication schemes. The library is cross-platform, 
+so once you learn it on iOS, you're all set on Android.
 
-## JSch Using
+```csharp
+using Xamarin.Auth;
 
-Simple method to start SSH shell and execute command:
+var auth = new OAuth2Authenticator (
+	clientId: "App ID from https://developers.facebook.com/apps",
+	scope: "",
+	authorizeUrl: new Uri ("https://m.facebook.com/dialog/oauth/"),
+	redirectUrl: new Uri ("http://www.facebook.com/connect/login_success.html"));
 
-        private void Execute (string command)
-		{
-			string value = null;
+auth.Completed += (sender, eventArgs) => {
+	DismissViewController (true, null);
+	if (eventArgs.IsAuthenticated) {
+		// Use eventArgs.Account to do wonderful things
+	}
+}
 
-			System.Threading.Tasks.Task<string> t = null;
-			t = System.Threading.Tasks.Task.Run
-            (
-            	()
-            	=>
-				{
-					jsch = new JCraft.JSch.JSch();
-		
-				
-					config = new Java.Util.Properties();
-					// Avoid asking for key confirmation
-					config.SetProperty("StrictHostKeyChecking", "no");
-					config.SetProperty("compression.s2c", "zlib,none");
-					config.SetProperty("compression.c2s", "zlib,none");
+PresentViewController (auth.GetUI (), true, null);
+```
 
-					string OnProvideAssistData = null;
-					JCraft.JSch.Session session = null;
-					try 
-					{
-						session = jsch.GetSession(username, ip_address, port);
-						session.SetConfig(config);
-						session.SetPassword(pwd);
-						session.Connect();
-					} 
-					catch (JCraft.JSch.JSchException e) 
-					{
-						asd = "NOT_Executed";
-						System.Console.WriteLine("NOT_executed");
-						System.Console.WriteLine(e.Message);
-						value = asd;
-
-						return value;
-					}          
-
-					JCraft.JSch.ChannelExec channel = null;
-					channel = (JCraft.JSch.ChannelExec)session.OpenChannel("exec");
-					channel.SetCommand(command);
-					channel.Connect();
-
-					//InputStream input = channel.getInputStream();
-					System.IO.Stream input = channel.InputStream;
-
-					using (var reader = new System.IO.StreamReader(input, System.Text.Encoding.UTF8))
-					{
-						value = reader.ReadToEnd();
-						// Do something with the value
-					}
-					channel.Disconnect();
-
-					return value;
-				}
-			);
-
-			value = t.Result;
-
-			editTextCommandOutput.Text = value;
-
-			return;
-		}
-
-
-Note: JSch usage on UI thread will cause exception, thus async/await Task.Run();
-
-
-###
+It's that easy to authenticate users!
 
+*Some screenshots assembled with [PlaceIt](http://placeit.breezi.com/).*

component/GettingStarted.md

@@ -1,32 +1,136 @@
-# Getting Started
+## 1. Create and configure an authenticator
 
-## JSch - Java/Android SSH2 library
+Let's authenticate a user to access Facebook:
 
-JSch for Xamarin.Android is component with Xamarin.Android bindings for JSch - SSH 
-implementation in Java by JCraft.
+```csharp
+using Xamarin.Auth;
+...
+var auth = new OAuth2Authenticator (
+	clientId: "App ID from https://developers.facebook.com/apps",
+	scope: "",
+	authorizeUrl: new Uri ("https://m.facebook.com/dialog/oauth/"),
+	redirectUrl: new Uri ("http://www.facebook.com/connect/login_success.html"));
+```
 
-JSch is a pure Java implementation of SSH2.
-JSch allows users to 
+Facebook uses OAuth 2.0 authentication, so we create an `OAuth2Authenticator`. 
+Authenticators are responsible for managing the user interface and communicating with 
+authentication services.
 
-	*	connect to an sshd server and use 
-		*	port forwarding, 
-		*	X11 forwarding, 
-		*	file transfer, etc.
+Authenticators take a variety of parameters; in this case, the application's ID, its 
+authorization scope, and Facebook's various service locations are required.
 
-Developers can integrate its functionality into Java (and Android of course) programs
 
 
-## Links/References
 
+## 2. Authenticate the user
 
-More about the library:
+While authenticators manage their own UI, it's up to you to initially present the 
+authenticator's UI on the screen. This lets you control how the authentication UI is 
+displayed–modally, in navigation controllers, in popovers, etc.
 
-*	[http://www.jcraft.com/jsch/](http://www.jcraft.com/jsch/)
+Before we present the UI, we need to start listening to the `Completed` event which fires 
+when the user successfully authenticates or cancels. You can find out if the authentication 
+succeeded by testing the `IsAuthenticated` property of `eventArgs`:
 
-The Java (Android) sample that served as base for Xamarin.Android sample:
+```csharp
+auth.Completed += (sender, eventArgs) => {
+	// We presented the UI, so it's up to us to dimiss it on iOS.
+	DismissViewController (true, null);
 
-*	[http://kennethsfrequency.com/2013/03/19/android-ssh/](http://kennethsfrequency.com/2013/03/19/android-ssh/)
+	if (eventArgs.IsAuthenticated) {
+		// Use eventArgs.Account to do wonderful things
+	} else {
+		// The user cancelled
+	}
+};
+```
 
+All the information gathered from a successful authentication is available in 
+`eventArgs.Account`.
 
+Now we're ready to present the login UI from `ViewDidAppear` on iOS:
 
+```csharp
+PresentViewController (auth.GetUI (), true, null);
+```
+
+The `GetUI` method returns `UINavigationControllers` on iOS, and `Intents` on Android. 
+On Android, we would write the following code to present the UI from `OnCreate`:
+
+```csharp
+StartActivity (auth.GetUI (this));
+```
+
+
+
+## 3. Making requests
+
+Since Facebook is an OAuth2 service, we'll make requests with `OAuth2Request` providing 
+the account we retrieved from the `Completed` event. Assuming we're authenticated, we'll 
+grab the user's info to demonstrate:
+
+```csharp
+var request = new OAuth2Request ("GET", new Uri ("https://graph.facebook.com/me"), null, eventArgs.Account);
+request.GetResponseAsync().ContinueWith (t => {
+	if (t.IsFaulted)
+		Console.WriteLine ("Error: " + t.Exception.InnerException.Message);
+	else {
+		string json = t.Result.GetResponseText();
+		Console.WriteLine (json);
+	}
+});
+```
+
+
+## 4. Store the account
+
+Xamarin.Auth securely stores `Account` objects so that you don't always have to reauthenticate 
+the user. The `AccountStore` class is responsible for storing `Account` information, backed by 
+the [Keychain](https://developer.apple.com/library/ios/#documentation/security/Reference/keychainservices/Reference/reference.html) 
+on iOS and a [KeyStore](http://developer.android.com/reference/java/security/KeyStore.html) on 
+Android:
+
+```csharp
+// On iOS:
+AccountStore.Create ().Save (eventArgs.Account, "Facebook");
+
+// On Android:
+AccountStore.Create (this).Save (eventArgs.Account, "Facebook");
+```
+
+Saved Accounts are uniquely identified using a key composed of the account's 
+`Username` property and a "Service ID". The "Service ID" is any string that is 
+used when fetching accounts from the store.
+
+If an `Account` was previously saved, calling `Save` again will overwrite it. 
+This is convenient for services that expire the credentials stored in the account 
+object.
+
+
+## 5. Retrieve stored accounts
+
+You can fetch all `Account` objects stored for a given service:
+
+```csharp
+// On iOS:
+IEnumerable<Account> accounts = AccountStore.Create ().FindAccountsForService ("Facebook");
+
+// On Android:
+IEnumerable<Account> accounts = AccountStore.Create (this).FindAccountsForService ("Facebook");
+```
+
+It's that easy.
+
+
+
+
+## 6. Make your own authenticator
+
+Xamarin.Auth includes OAuth 1.0 and OAuth 2.0 authenticators, providing support for thousands 
+of popular services. For services that use traditional username/password authentication, you 
+can roll your own authenticator by deriving from `FormAuthenticator`.
+
+If you want to authenticate against an ostensibly unsupported service, fear not – Xamarin.Auth 
+is extensible! It's very easy to create your own authenticators – just derive from any of the 
+existing authenticators and start overriding methods.