update readme

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;

// 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 {

    @GET("version")

    Observable<NextcloudNewsVersion> version();

    ...

    …

}

```

// Typical use of API using Retrofit

Typical use of API using Retrofit

```java

public class ApiProvider {

    private API mApi;

}

```

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 {

        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;

    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

 No newline at end of file

![](doc/NextcloudSingleSignOn.png)

 No newline at end of file