Browse Source

update readme

tags/0.1.0
tobiasKaminsky 1 year ago
parent
commit
5ebec7fce9
No account linked to committer's email address
3 changed files with 38 additions and 44 deletions
  1. 38
    44
      README.md
  2. 0
    0
      doc/NextcloudSingleSignOn.png
  3. 0
    0
      doc/NextcloudSingleSignOn.xml

+ 38
- 44
README.md View File

@@ -4,18 +4,23 @@ Nextcloud Single Sign On
This library allows you to use the network stack provided by the nextcloud app. Therefore you don't need to ask for the users credentials anymore as well as you don't need to worry about self-signed ssl certificates, two factor authentication, etc.



How to use it?
--------------

1) Add this library as a submodule to your project (TODO release this lib on jitpack)
1) Add this library to your project

```gradle
dependencies {
implementation "com.github.nextcloud:android-SingleSignOn:sso-SNAPSHOT"
}
```
2) Add the following permission to your `AndroidManifest.xml`

```xml
<uses-permission android:name="com.owncloud.android.sso"/>
```

2) To choose an account, include the following code in your login dialog:
3) To choose an account, include the following code in your login dialog:

```java
final int CHOOSE_ACCOUNT = 12;
@@ -51,14 +56,15 @@ SingleSignOnAccount ssoAccount = AccountImporter.GetAuthTokenInSeparateThread(ge

// ssoAccount.name // Name of the account used in the android account manager
// ssoAccount.username
// ssoAccount.password
// ssoAccount.token
// ssoAccount.url
// ssoAccount.disableHostnameVerification (TODO remove)
```

4) How to make a network request?

Well.. if you're already using Retrofit, it's plain simple. If you have an interface such as the following:
4.1.1) Retrofit:

If you have an interface such as the following:

```java
public interface API {
@@ -72,11 +78,12 @@ public interface API {
@GET("version")
Observable<NextcloudNewsVersion> version();

...
}
```

// Typical use of API using Retrofit
Typical use of API using Retrofit
```java
public class ApiProvider {

private API mApi;
@@ -87,7 +94,9 @@ public class ApiProvider {
}
```

you can implement that interface and use the nextcloud network stack instead of the retrofit one!
4.1.2) Use Nextcloud network stack:

You can implement that interface and use the nextcloud network stack instead of the retrofit one.

```java
public class API_SSO implements API {
@@ -129,12 +138,13 @@ public class API_SSO implements API {
return nextcloudAPI.performRequestObservable(type, request);
}

...
}
```

4.1.3) Use of new API using the nextcloud app network stack


// Typical use of new API using the nextcloud app network stack (Example)
```java
public class ApiProvider {

private API mApi;
@@ -142,61 +152,45 @@ public class ApiProvider {
public ApiProvider(NextcloudAPI.ApiConnectedListener callback) {
SingleSignOnAccount ssoAccount =
AccountImporter.GetAuthTokenInSeparateThread(context, account);
NextcloudAPI nextcloudAPI =
new NextcloudAPI(ssoAccount, GsonConfig.GetGson());
NextcloudAPI nextcloudAPI = new NextcloudAPI(ssoAccount, GsonConfig.GetGson());
nextcloudAPI.start(context, callback);
mApi = new API_SSO(nextcloudAPI)
mApi = new API_SSO(nextcloudAPI);
}
}
```
Enjoy! If you're already using retrofit, you don't need to modify your application logic. Just exchange the API and you're good to go!

4.2) Without Retrofit

NextcloudAPI provides a method called `performNetworkRequest(NextcloudRequest request)` that allows you to handle the server response yourself.

5) Enjoy! If you're already using retrofit, you don't need to modify your application logic. Just exchange the API and you're good to go!

# But... I don't use retrofit..

Well.. no worries, the NextcloudAPI provides a method called `performNetworkRequest(NextcloudRequest request)` that allows you to handle the server response yourself.


## Example:
```java
// create nextcloudAPI instance
SingleSignOnAccount ssoAccount = AccountImporter.GetAuthTokenInSeparateThread(context, account);
NextcloudAPI nextcloudAPI = new NextcloudAPI(ssoAccount, GsonConfig.GetGson());

private void downloadFile() {
NextcloudRequest nr = new NextcloudRequest.Builder()
NextcloudRequest nextcloudRequest = new NextcloudRequest.Builder()
.setMethod("GET")
.setUrl("/remote.php/webdav/sample.mp4")
.build();

try {
InputStream os = nextcloudAPI.performNetworkRequest(nr);
while(os.available() > 0) {
os.read();
InputStream inputStream = nextcloudAPI.performNetworkRequest(nextcloudRequest);
while(inputStream.available() > 0) {
inputStream.read();
// TODO do something useful with the data here..
// like writing it to a file..?
}
os.close();
inputStream.close();
} catch (Exception e) {
e.printStackTrace();
}
}
```




# Flow Diagram

Note that the "Make network request" section in the diagram only shows the workflow if you use the "retrofit" api.

![](NextcloudSingleSignOn.png)



# TODOs
- [ ] Remove attribute `disableHostnameVerification` from SingleSignOnAccount.java
- Do we need really to know in the client app if ssl hostname verification is disabled? I don't think so.
- [ ] Multi-Account support in client app
- [ ] Review security concerns
- [ ] Handle cases when account permission is revoked etc..
- [ ] Think about other use-cases?
- [ ] Test on real devices (lower api level) - tested only on Android P
![](doc/NextcloudSingleSignOn.png)

NextcloudSingleSignOn.png → doc/NextcloudSingleSignOn.png View File


NextcloudSingleSignOn.xml → doc/NextcloudSingleSignOn.xml View File


Loading…
Cancel
Save