Skip to content
This repository was archived by the owner on May 1, 2024. It is now read-only.

Commit a8c3cee

Browse files
moljacmoljac
committed
component docs added
1 parent f614479 commit a8c3cee

File tree

3 files changed

+310
-104
lines changed

3 files changed

+310
-104
lines changed

‎component/Details.md

+21-70
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,27 @@
1-
# Details
1+
Xamarin.Auth helps you authenticate users via standard authentication mechanisms
2+
(e.g. OAuth 1.0 and 2.0), and store user credentials. It's also straightforward
3+
to add support for non-standard authentication schemes. The library is cross-platform,
4+
so once you learn it on iOS, you're all set on Android.
25

3-
## JSch Using
6+
```csharp
7+
using Xamarin.Auth;
48

5-
Simple method to start SSH shell and execute command:
9+
var auth = new OAuth2Authenticator (
10+
clientId: "App ID from https://developers.facebook.com/apps",
11+
scope: "",
12+
authorizeUrl: new Uri ("https://m.facebook.com/dialog/oauth/"),
13+
redirectUrl: new Uri ("http://www.facebook.com/connect/login_success.html"));
614

7-
private void Execute (string command)
8-
{
9-
string value = null;
15+
auth.Completed += (sender, eventArgs) => {
16+
DismissViewController (true, null);
17+
if (eventArgs.IsAuthenticated) {
18+
// Use eventArgs.Account to do wonderful things
19+
}
20+
}
1021

11-
System.Threading.Tasks.Task<string> t = null;
12-
t = System.Threading.Tasks.Task.Run
13-
(
14-
()
15-
=>
16-
{
17-
jsch = new JCraft.JSch.JSch();
18-
19-
20-
config = new Java.Util.Properties();
21-
// Avoid asking for key confirmation
22-
config.SetProperty("StrictHostKeyChecking", "no");
23-
config.SetProperty("compression.s2c", "zlib,none");
24-
config.SetProperty("compression.c2s", "zlib,none");
22+
PresentViewController (auth.GetUI (), true, null);
23+
```
2524

26-
string OnProvideAssistData = null;
27-
JCraft.JSch.Session session = null;
28-
try
29-
{
30-
session = jsch.GetSession(username, ip_address, port);
31-
session.SetConfig(config);
32-
session.SetPassword(pwd);
33-
session.Connect();
34-
}
35-
catch (JCraft.JSch.JSchException e)
36-
{
37-
asd = "NOT_Executed";
38-
System.Console.WriteLine("NOT_executed");
39-
System.Console.WriteLine(e.Message);
40-
value = asd;
41-
42-
return value;
43-
}
44-
45-
JCraft.JSch.ChannelExec channel = null;
46-
channel = (JCraft.JSch.ChannelExec)session.OpenChannel("exec");
47-
channel.SetCommand(command);
48-
channel.Connect();
49-
50-
//InputStream input = channel.getInputStream();
51-
System.IO.Stream input = channel.InputStream;
52-
53-
using (var reader = new System.IO.StreamReader(input, System.Text.Encoding.UTF8))
54-
{
55-
value = reader.ReadToEnd();
56-
// Do something with the value
57-
}
58-
channel.Disconnect();
59-
60-
return value;
61-
}
62-
);
63-
64-
value = t.Result;
65-
66-
editTextCommandOutput.Text = value;
67-
68-
return;
69-
}
70-
71-
72-
Note: JSch usage on UI thread will cause exception, thus async/await Task.Run();
73-
74-
75-
###
25+
It's that easy to authenticate users!
7626

27+
*Some screenshots assembled with [PlaceIt](http://placeit.breezi.com/).*

‎component/GettingStarted.md

+120-16
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,136 @@
1-
# Getting Started
1+
## 1. Create and configure an authenticator
22

3-
## JSch - Java/Android SSH2 library
3+
Let's authenticate a user to access Facebook:
44

5-
JSch for Xamarin.Android is component with Xamarin.Android bindings for JSch - SSH
6-
implementation in Java by JCraft.
5+
```csharp
6+
using Xamarin.Auth;
7+
...
8+
var auth = new OAuth2Authenticator (
9+
clientId: "App ID from https://developers.facebook.com/apps",
10+
scope: "",
11+
authorizeUrl: new Uri ("https://m.facebook.com/dialog/oauth/"),
12+
redirectUrl: new Uri ("http://www.facebook.com/connect/login_success.html"));
13+
```
714

8-
JSch is a pure Java implementation of SSH2.
9-
JSch allows users to
15+
Facebook uses OAuth 2.0 authentication, so we create an `OAuth2Authenticator`.
16+
Authenticators are responsible for managing the user interface and communicating with
17+
authentication services.
1018

11-
* connect to an sshd server and use
12-
* port forwarding,
13-
* X11 forwarding,
14-
* file transfer, etc.
19+
Authenticators take a variety of parameters; in this case, the application's ID, its
20+
authorization scope, and Facebook's various service locations are required.
1521

16-
Developers can integrate its functionality into Java (and Android of course) programs
1722

1823

19-
## Links/References
2024

25+
## 2. Authenticate the user
2126

22-
More about the library:
27+
While authenticators manage their own UI, it's up to you to initially present the
28+
authenticator's UI on the screen. This lets you control how the authentication UI is
29+
displayed–modally, in navigation controllers, in popovers, etc.
2330

24-
* [http://www.jcraft.com/jsch/](http://www.jcraft.com/jsch/)
31+
Before we present the UI, we need to start listening to the `Completed` event which fires
32+
when the user successfully authenticates or cancels. You can find out if the authentication
33+
succeeded by testing the `IsAuthenticated` property of `eventArgs`:
2534

26-
The Java (Android) sample that served as base for Xamarin.Android sample:
35+
```csharp
36+
auth.Completed += (sender, eventArgs) => {
37+
// We presented the UI, so it's up to us to dimiss it on iOS.
38+
DismissViewController (true, null);
2739

28-
* [http://kennethsfrequency.com/2013/03/19/android-ssh/](http://kennethsfrequency.com/2013/03/19/android-ssh/)
40+
if (eventArgs.IsAuthenticated) {
41+
// Use eventArgs.Account to do wonderful things
42+
} else {
43+
// The user cancelled
44+
}
45+
};
46+
```
2947

48+
All the information gathered from a successful authentication is available in
49+
`eventArgs.Account`.
3050

51+
Now we're ready to present the login UI from `ViewDidAppear` on iOS:
3152

53+
```csharp
54+
PresentViewController (auth.GetUI (), true, null);
55+
```
56+
57+
The `GetUI` method returns `UINavigationControllers` on iOS, and `Intents` on Android.
58+
On Android, we would write the following code to present the UI from `OnCreate`:
59+
60+
```csharp
61+
StartActivity (auth.GetUI (this));
62+
```
63+
64+
65+
66+
## 3. Making requests
67+
68+
Since Facebook is an OAuth2 service, we'll make requests with `OAuth2Request` providing
69+
the account we retrieved from the `Completed` event. Assuming we're authenticated, we'll
70+
grab the user's info to demonstrate:
71+
72+
```csharp
73+
var request = new OAuth2Request ("GET", new Uri ("https://graph.facebook.com/me"), null, eventArgs.Account);
74+
request.GetResponseAsync().ContinueWith (t => {
75+
if (t.IsFaulted)
76+
Console.WriteLine ("Error: " + t.Exception.InnerException.Message);
77+
else {
78+
string json = t.Result.GetResponseText();
79+
Console.WriteLine (json);
80+
}
81+
});
82+
```
83+
84+
85+
## 4. Store the account
86+
87+
Xamarin.Auth securely stores `Account` objects so that you don't always have to reauthenticate
88+
the user. The `AccountStore` class is responsible for storing `Account` information, backed by
89+
the [Keychain](https://developer.apple.com/library/ios/#documentation/security/Reference/keychainservices/Reference/reference.html)
90+
on iOS and a [KeyStore](http://developer.android.com/reference/java/security/KeyStore.html) on
91+
Android:
92+
93+
```csharp
94+
// On iOS:
95+
AccountStore.Create ().Save (eventArgs.Account, "Facebook");
96+
97+
// On Android:
98+
AccountStore.Create (this).Save (eventArgs.Account, "Facebook");
99+
```
100+
101+
Saved Accounts are uniquely identified using a key composed of the account's
102+
`Username` property and a "Service ID". The "Service ID" is any string that is
103+
used when fetching accounts from the store.
104+
105+
If an `Account` was previously saved, calling `Save` again will overwrite it.
106+
This is convenient for services that expire the credentials stored in the account
107+
object.
108+
109+
110+
## 5. Retrieve stored accounts
111+
112+
You can fetch all `Account` objects stored for a given service:
113+
114+
```csharp
115+
// On iOS:
116+
IEnumerable<Account> accounts = AccountStore.Create ().FindAccountsForService ("Facebook");
117+
118+
// On Android:
119+
IEnumerable<Account> accounts = AccountStore.Create (this).FindAccountsForService ("Facebook");
120+
```
121+
122+
It's that easy.
123+
124+
125+
126+
127+
## 6. Make your own authenticator
128+
129+
Xamarin.Auth includes OAuth 1.0 and OAuth 2.0 authenticators, providing support for thousands
130+
of popular services. For services that use traditional username/password authentication, you
131+
can roll your own authenticator by deriving from `FormAuthenticator`.
132+
133+
If you want to authenticate against an ostensibly unsupported service, fear not – Xamarin.Auth
134+
is extensible! It's very easy to create your own authenticators – just derive from any of the
135+
existing authenticators and start overriding methods.
32136

0 commit comments

Comments
 (0)