Performing resource calls
Introduction
Starting from version 6.04.00 the Onegini SDK exposes instances of OkHttp 3 clients that are prepared for making secure resource calls to your backend. The instances are already pre configured and secured by the SDK, so that you do not need to worry about encrypting/decrypting the payload or certificate pinning. The client can be later on used with libraries like Retrofit 1.X and 2.X.
DeviceClient#getOkHttpClient()
returns an instance of the OkHttpClient with security features like certificate pinning, but no user/device authentication.DeviceClient#getAnonymousResourceOkHttpClient()
returns an instance of secured client that also uses device credentials for authentication.UserClient#getResourceOkHttpClient()
returns an instance of secured client that also uses user's credentials for authentication.
Get resource flow
- APP → SDK: Build REST adapter based secured client provided by the SDK.
- SDK → Resource Gateway: Request a resource at the resource gateway.
- Resource Gateway → Token Server: Validate the provided token.
- Token Server → Resource Gateway: Details regarding the access token like scope and user, which will be verified by the resource gateway.
- Resource Gateway → Resource Server: Get the resource.
- Resource Server → Resource Gateway: Return the resource.
- Resource Gateway → App: Return the resource.
Using OkHttp 3 client with Retrofit 1.X and 2.X
The OkHttp 3 clients that are returned by the SDK (DeviceClient#getOkHttpClient()
, DeviceClient#getAnonymousResourceOkHttpClient()
,
UserClient#getResourceOkHttpClient()
, UserClient#getImplicitResourceOkHttpClient()
, DeviceClient#getUnauthenticatedResourceOkHttpClient()
) can be used
with both Retrofit 1.X and 2.X.
In Retrofit 2.X the Retrofit.Builder()
expects that an instance of the OkHttpClient
will be provided with the client
method:
In Retrofit 1.X you need to use additional dependency called retrofit1-okhttp3-client. Then the client can be set with:
We recommend using Retrofit 2.X which is currently supported version by it's creators. Therefore the following examples will only cover usage of Retrofit 2.X.
Fetching resource anonymously
A device can use it's OAuth credentials in order to obtain an Access Token object, which in turn can be used for proofing its authenticity. An anonymous resource call can be typically used in cases where a user does not need to login or register in order to use certain functionality, or access some resource.
Authenticate the device
The SDK gives you the flexibility of being in control over building the requests and handling the responses. Therefore, it is your responsibility to
perform device authentication with DeviceClient#authenticateDevice
whenever the Resource Gateway responds with the 401 unauthorized status code.
Once the device has been authenticated using DeviceClient#authenticateDevice
method, it is possible to start fetching resources.
Example code for authenticating the device
Defining the REST interface
The first step we need to take in order to fetch resources anonymously is to define a REST interface. Please note that the path application-details
is
relative to the endpoint which we need to configure on the HTTP client before making a call. Please follow one of many Retrofit tutorials for details.
Defining the REST Adapter
Next, we need to setup the Retrofit instance by providing the anonymousClient (DeviceClient#getAnonymousResourceOkHttpClient()
), Resource Gateway url and
also REST interface which we have defined in the previous step.
Example code
As you can see in the snippets above, the Resource Gateway url (endpoint) is set explicitly on Retrofit.Builder
. Depending on
your needs you may set additional options, for example add a Gson converter or a RxJava3CallAdapterFactory like in the example above. Please notice that the
client passed to the builder has to come from DeviceClient#getAnonymousResourceOkHttpClient()
as we want to make anonymous resource call.
Performing the anonymous resource call
When we have the Retrofit client defined and instantiated we can proceed and perform the resource call itself. The SDK will not process the response, which means that you need to handle it on our own. This also means that you need to make sure that the device has a valid access token by performing device authentication before making the actual anonymous resource call.
Fetching a resource on behalf of a user
In order to request a resource for a specific user, the client needs to be registered and also the user's access token needs to be present within the
application memory. So it is required to have the authentication flow UserClient#authenticateUser
finished successfully before a resource call on behalf of
user can be made. A resource request can be typically used in cases where usage of certain functionality or accessing resources requires user authentication.
Defining REST interface
The first step we need to take in order to fetch a resource is to define a REST interface. Please note that the path devices
is relative to the endpoint which
we need to configure on the HTTP client before making a call. Please follow one of many Retrofit tutorials for details.
Defining the REST Adapter
Next, we need to setup the retrofit instance by providing the resource client (UserClient#getResourceOkHttpClient()
), Resource Gateway url and also REST
interface which we have defined in previous step.
Example code
As you can see in the snippets above, the Resource Gateway url (endpoint) is set explicitly on Retrofit.Builder
. Depending on
your needs you may set additional options, for example add a Gson converter or a RxJava3CallAdapterFactory like in the example above. Please notice that the
client passed to the builder has to come from UserClient#getResourceOkHttpClient()
as we want to make anonymous resource call.
Performing the resource call
When we have the Retrofit defined and instantiated we can proceed and perform the resource call itself. The SDK will not process the response, which means that you need to handle it on your own. This also means that you need to make sure that the user has a valid access token by triggering user authentication. You don't have to bother about payload encryption because the SDK will take care of that for you. Let's try to send the request and log the answer.
The operation will succeed only in case the user's access token is available. Otherwise, the Resource Gateway will respond with 401 unauthorized, meaning that the provided access token was not valid.
Fetching a resource on behalf of implicitly authenticated user
In order to request a resource for a specific implicitly authenticated user, the client needs to be registered and also the user's implicit access token needs
to be present within application memory. So it is required to have the implicit authentication flow UserClient#authenticateUserImplicitly
finished
successfully before a resource call on behalf of an implicitly authenticated user can be made. A resource request can be typically used in cases where usage
of certain functionality or accessing resources does not require user to explicitly authenticate himself. The implicit authentication can be used for accessing
less sensitive resources.
Defining REST interface
The first step we need to take in order to fetch a resource is to define a REST interface. Please note that the path user-id-decorated
is relative to
the endpoint which we need to configure on the HTTP client before making a call. Please follow one of many Retrofit tutorials for details.
Defining the REST Adapter
Next, we need to setup the retrofit instance by providing the resource client (UserClient#getImplicitResourceOkHttpClient()
, Resource Gateway url
and also REST interface which we have defined in previous step.
Example code
As you can see in the snippets above, the Resource Gateway url (endpoint) is set explicitly on Retrofit.Builder
. Depending on
your needs you may set additional options, for example add a Gson converter or a RxJava3CallAdapterFactory like in the example above. Please notice that the
client passed to the builder has to come from UserClient#getImplicitResourceOkHttpClient()
as we want to make resource call for implicitly authenticated user.
Performing the resource call for implicitly authenticated user
When we have the Retrofit defined and instantiated we can proceed and perform the resource call itself. The SDK will not process the response, which means that you need to handle it on your own. This also means that you need to make sure that the user has a valid access token by triggering implicit user authentication. You don't have to bother about payload encryption because the SDK will take care of that for you. Let's try to send the request and log the answer.
The operation will succeed only in case the user's implicit access token is available. Otherwise, the Resource Gateway will respond with 401 unauthorized, meaning that the provided access token was not valid.
Performing multipart REST request
The Retrofit library also supports multipart requests, simply by adding the proper annotation:
For more details please check the Retrofit site.
Performing modified REST requests
In some cases you may want to add custom headers to all requests made by your RestAdapter. To do so, please create a
requestInterceptor instance and set it in the RestAdapter.Builder
when you are constructing your RestAdapter.
For more information on adding headers or parameters to requests see the following Retrofit tutorial.
Also please note that for Retrofit 2.X you should add OkHttp Interceptor instead.