You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -71,46 +80,67 @@ AuthInterceptor authInterceptor = new AuthInterceptor(
71
80
```
72
81
73
82
Construct an `OkHttpClient` and pass the interceptor and the authenticator:
83
+
74
84
```java
75
85
newOkHttpClient.Builder()
76
86
.authenticator(authenticator)
77
87
.addInterceptor(authInterceptor)
78
88
.build();
79
89
```
80
90
81
-
That's it. When using this `OkHttpClient` instance you'll benefit from fully transparent token handling.
82
-
83
-
__Hint 1:__*If your app uses multiple authentication methods make sure to implement an own subclass of `AuthenticationProvider` for each method and use an own `OkHttpClient` for each!*
84
-
85
-
__Hint 2:__*In case you are using OkHttp/Retrofit to retrieve tokens: As the `Authenticator` locks all other `Authenticators` and `AuthInterceptors` with the same `AuthenticationProvider` it makes sense to provide an own `OkHttpClient` instance (and thus also an own Retrofit instance if you use it) for all calls you need to receive new tokens. If try to serve all calls with the same client instance, it may happen that you run out of connections/threads while trying to get a token because there might be a whole slew of requests already waiting for that token call to succeed. Alternatively you can also try to increase the executor pool size, but this is not recommended as you never know for sure how many requests are executed at a given point in time - and you definitely always want a thread ready for your token request.*
91
+
That's it. When using this `OkHttpClient` instance you'll benefit from fully
92
+
transparent token handling.
93
+
94
+
__Hint 1:__*If your app uses multiple authentication methods make sure to
95
+
implement an own subclass of `AuthenticationProvider` for each method and use
96
+
an own `OkHttpClient` for each!*
97
+
98
+
__Hint 2:__*In case you are using OkHttp/Retrofit to retrieve tokens: As the
99
+
`Authenticator` locks all other `Authenticators` and `AuthInterceptors` with
100
+
the same `AuthenticationProvider` it makes sense to provide an own
101
+
`OkHttpClient` instance (and thus also an own Retrofit instance if you use it)
102
+
for all calls you need to receive new tokens. If try to serve all calls with
103
+
the same client instance, it may happen that you run out of connections/threads
104
+
while trying to get a token because there might be a whole slew of requests
105
+
already waiting for that token call to succeed. Alternatively you can also try
106
+
to increase the executor pool size, but this is not recommended as you never
107
+
know for sure how many requests are executed at a given point in time - and you
108
+
definitely always want a thread ready for your token request.*
86
109
87
110
#### A note on authentication exception handling
88
111
89
-
The library provides an own exception class called `AuthenticationException`. You can listen for this
90
-
class in your Retrofit `Callback.onFailure(Call, Throwable)` to check for authentication related
112
+
The library provides an own exception class called `AuthenticationException`.
113
+
You can listen for this class in your Retrofit
114
+
`Callback.onFailure(Call, Throwable)` to check for authentication related
91
115
errors.
92
116
93
-
However up until now we are not able to fire this exception everywhere - especially the
94
-
`Authenticator` suffers from a likely [okhttp bug](https://github.com/square/okhttp/issues/3872)
95
-
which prevents us from firing exceptions there. In case of errors you will receive a `NullPointerException`
96
-
instead which probably won't help you much for automated handling as this exception is basically
97
-
caused by every interceptor/authenticator returning `null` for the expected Request/Response.
98
-
99
-
For the time being we recommend to take a best effort approach here and additionally check for 401 response code
100
-
in Retrofit's `Callback.onSuccess()` for when an issue in the Authenticator occured (if there was no
101
-
issue you won't get a 401 propagated to `Callback.onSuccess()` as in case of successful authentication
102
-
after receiving a 401 for the initial request your callback will get the response code of the following
103
-
originally intended request).
104
-
105
-
If you're having problems retrieving a token in the `AuthenticationProvider` (e.g. due to an invalid
106
-
refresh token) always try to resolve those issues there as well if possible. Throwing an
107
-
`AuthenticationException` should just be a last resort.
117
+
However up until now we are not able to fire this exception everywhere -
118
+
especially the `Authenticator` suffers from a likely
119
+
[okhttp bug](https://github.com/square/okhttp/issues/3872) which prevents us
120
+
from firing exceptions there. In case of errors you will receive a
121
+
`NullPointerException` instead which probably won't help you much for automated
122
+
handling as this exception is basically caused by every
123
+
interceptor/authenticator returning `null` for the expected Request/Response.
124
+
125
+
For the time being we recommend to take a best effort approach here and
126
+
additionally check for 401 response code in Retrofit's `Callback.onSuccess()`
127
+
for when an issue in the Authenticator occured (if there was no issue you won't
128
+
get a 401 propagated to `Callback.onSuccess()` as in case of successful
129
+
authentication after receiving a 401 for the initial request your callback will
130
+
get the response code of the following originally intended request).
131
+
132
+
If you're having problems retrieving a token in the `AuthenticationProvider`
133
+
(e.g. due to an invalid refresh token) always try to resolve those issues there
134
+
as well if possible. Throwing an `AuthenticationException` should just be a
135
+
last resort.
108
136
109
137
Alternatively you can also subclass the `Authenticator` class and override
110
-
`onAuthenticationFailed()` if you want to trigger special handling for failed authentication from
111
-
which we couldn't recover with our default handling. This usually tends to be a bit harder to get
112
-
right as it expects you to modify the failed request directly without any means of intercepting the
113
-
response. Thus handling token retrieval issues should preferably handled in the `AuthenticationProvider`
114
-
as explained above.
115
-
116
-
We're looking forward to streamlining this as soon as the okhttp bug has been resolved.
138
+
`onAuthenticationFailed()` if you want to trigger special handling for failed
139
+
authentication from which we couldn't recover with our default handling. This
140
+
usually tends to be a bit harder to get right as it expects you to modify the
141
+
failed request directly without any means of intercepting the response. Thus
142
+
handling token retrieval issues should preferably handled in the
143
+
`AuthenticationProvider` as explained above.
144
+
145
+
We're looking forward to streamlining this as soon as the okhttp bug has been
0 commit comments