Browse Source

update readme

tobiasKaminsky 11 months 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
4 4
 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.
5 5
 
6 6
 
7
-
8 7
 How to use it?
9 8
 --------------
10 9
 
11
-1) Add this library as a submodule to your project (TODO release this lib on jitpack)
10
+1) Add this library to your project
11
+
12
+```gradle
13
+dependencies {
14
+    implementation "com.github.nextcloud:android-SingleSignOn:sso-SNAPSHOT"
15
+}
16
+```
12 17
 2) Add the following permission to your `AndroidManifest.xml` 
13 18
 
14 19
 ```xml
15 20
 <uses-permission android:name="com.owncloud.android.sso"/>
16 21
 ```
17 22
 
18
-2) To choose an account, include the following code in your login dialog:
23
+3) To choose an account, include the following code in your login dialog:
19 24
 
20 25
 ```java
21 26
 final int CHOOSE_ACCOUNT = 12;
@@ -51,14 +56,15 @@ SingleSignOnAccount ssoAccount = AccountImporter.GetAuthTokenInSeparateThread(ge
51 56
 
52 57
 // ssoAccount.name // Name of the account used in the android account manager
53 58
 // ssoAccount.username
54
-// ssoAccount.password
59
+// ssoAccount.token 
55 60
 // ssoAccount.url 
56
-// ssoAccount.disableHostnameVerification (TODO remove)
57 61
 ```
58 62
 
59 63
 4) How to make a network request?
60 64
 
61
-Well.. if you're already using Retrofit, it's plain simple. If you have an interface such as the following: 
65
+4.1.1) Retrofit: 
66
+
67
+If you have an interface such as the following: 
62 68
 
63 69
 ```java
64 70
 public interface API {
@@ -72,11 +78,12 @@ public interface API {
72 78
     @GET("version")
73 79
     Observable<NextcloudNewsVersion> version();
74 80
 
75
-    ...
81
+    
76 82
 }
83
+```
77 84
 
78
-
79
-// Typical use of API using Retrofit
85
+Typical use of API using Retrofit
86
+```java
80 87
 public class ApiProvider {
81 88
 
82 89
     private API mApi;
@@ -87,7 +94,9 @@ public class ApiProvider {
87 94
 }
88 95
 ```
89 96
 
90
-you can implement that interface and use the nextcloud network stack instead of the retrofit one!
97
+4.1.2) Use Nextcloud network stack:
98
+
99
+You can implement that interface and use the nextcloud network stack instead of the retrofit one.
91 100
 
92 101
 ```java
93 102
 public class API_SSO implements API {
@@ -129,12 +138,13 @@ public class API_SSO implements API {
129 138
         return nextcloudAPI.performRequestObservable(type, request);
130 139
     }
131 140
 
132
-    ...
141
+    
133 142
 }
143
+```
134 144
 
145
+4.1.3) Use of new API using the nextcloud app network stack
135 146
 
136
-
137
-// Typical use of new API using the nextcloud app network stack (Example)
147
+```java
138 148
 public class ApiProvider {
139 149
 
140 150
     private API mApi;
@@ -142,61 +152,45 @@ public class ApiProvider {
142 152
     public ApiProvider(NextcloudAPI.ApiConnectedListener callback) {
143 153
         SingleSignOnAccount ssoAccount = 
144 154
             AccountImporter.GetAuthTokenInSeparateThread(context, account);
145
-        NextcloudAPI nextcloudAPI = 
146
-            new NextcloudAPI(ssoAccount, GsonConfig.GetGson());
155
+        NextcloudAPI nextcloudAPI = new NextcloudAPI(ssoAccount, GsonConfig.GetGson());
147 156
         nextcloudAPI.start(context, callback);
148
-        mApi = new API_SSO(nextcloudAPI)
157
+        mApi = new API_SSO(nextcloudAPI);
149 158
     } 
150 159
 }
151 160
 ```
161
+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!
152 162
 
163
+4.2) Without Retrofit
153 164
 
165
+NextcloudAPI provides a method called `performNetworkRequest(NextcloudRequest request)` that allows you to handle the server response yourself.
154 166
 
155
-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!
156
-
157
-# But... I don't use retrofit..
158
-
159
-Well.. no worries, the NextcloudAPI provides a method called `performNetworkRequest(NextcloudRequest request)` that allows you to handle the server response yourself.
160
-
161
-
162
-## Example: 
163 167
 ```java
168
+// create nextcloudAPI instance
169
+SingleSignOnAccount ssoAccount = AccountImporter.GetAuthTokenInSeparateThread(context, account);
170
+NextcloudAPI nextcloudAPI = new NextcloudAPI(ssoAccount, GsonConfig.GetGson());
171
+
164 172
 private void downloadFile() {
165
-    NextcloudRequest nr = new NextcloudRequest.Builder()
173
+    NextcloudRequest nextcloudRequest = new NextcloudRequest.Builder()
166 174
             .setMethod("GET")
167 175
             .setUrl("/remote.php/webdav/sample.mp4")
168 176
             .build();
169 177
 
170 178
     try {
171
-        InputStream os = nextcloudAPI.performNetworkRequest(nr);
172
-        while(os.available() > 0) {
173
-            os.read();
179
+        InputStream inputStream = nextcloudAPI.performNetworkRequest(nextcloudRequest);
180
+        while(inputStream.available() > 0) {
181
+            inputStream.read();
174 182
             // TODO do something useful with the data here..
175 183
             // like writing it to a file..?
176 184
         }
177
-        os.close();
185
+        inputStream.close();
178 186
     } catch (Exception e) {
179 187
         e.printStackTrace();
180 188
     }
181 189
 }
182 190
 ```
183 191
 
184
-
185
-
186
-
187 192
 # Flow Diagram
188 193
 
189 194
 Note that the "Make network request" section in the diagram only shows the workflow if you use the "retrofit" api. 
190 195
 
191
-![](NextcloudSingleSignOn.png)
192
-
193
-
194
-
195
-# TODOs
196
-- [ ] Remove attribute `disableHostnameVerification` from SingleSignOnAccount.java
197
-    - Do we need really to know in the client app if ssl hostname verification is disabled? I don't think so.
198
-- [ ] Multi-Account support in client app
199
-- [ ] Review security concerns
200
-- [ ] Handle cases when account permission is revoked etc..
201
-- [ ] Think about other use-cases? 
202
-- [ ] Test on real devices (lower api level) - tested only on Android P
196
+![](doc/NextcloudSingleSignOn.png)

NextcloudSingleSignOn.png → doc/NextcloudSingleSignOn.png View File


NextcloudSingleSignOn.xml → doc/NextcloudSingleSignOn.xml View File