Performing resource calls
Starting from version 6.04.00, the Android 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 Android SDK, so that you do not need to worry about encryption or decrypting the payload or certificate pinning. The client can be used later with libraries like Retrofit 1.X and 2.X.
-
DeviceClient#getOkHttpClient()
returns an instance of theOkHttpClient
with security features like certificate pinning, but no user or device authentication. -
DeviceClient#getAnonymousResourceOkHttpClient()
returns an instance of the secured client that also uses device credentials for authentication. -
UserClient#getResourceOkHttpClient()
returns an instance of the secured client that also uses the user's credentials for authentication.
A high level overview of the workflow:
- APP > SDK: Build REST adapter-based, secured client provided by the Android SDK.
- SDK > resource gateway: Request a resource at the resource gateway.
- Resource gateway > IDAAS-core: Validate the provided token.
- IDAAS-core > 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 Android 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. The following examples will only cover usage of Retrofit 2.X.
Fetching resources anonymously
A device can use its OAuth credentials to obtain an access token object, which in turn can be used for proving its authenticity. An anonymous resource call can be typically used in cases where a user does not need to log in or register to use certain functionality or access some resource.
Authenticating the device
It is your responsibility to perform device authentication with DeviceClient#authenticateDevice
whenever the resource gateway responds with the 401 unauthorized status code. After 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
To fetch resources anonymously, you must define a REST interface. The path application-details
is relative to the endpoint that you need to configure on the HTTP client before making a call.
Defining the REST adapter
Set up the retrofit instance by providing the anonymousClient (DeviceClient#getAnonymousResourceOkHttpClient())
resource gateway URL and REST interface.
In the examples below, 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. The client passed to the builder has to come from DeviceClient#getAnonymousResourceOkHttpClient()
.
Performing the anonymous resource call
After the retrofit client is defined and instantiated, you can perform the resource call. The Android 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 device has a valid access token by performing device authentication before making the anonymous resource call.
Fetching a resource on behalf of a user
To request a resource for a specific user, the client needs to be registered and the user's access token needs to be present within the application memory. The UserClient#authenticateUser
authentication flow must complete before a resource call can be made on behalf of the user.
Defining the REST interface
To fetch a resource, you must define a REST interface. The device path is relative to the endpoint, which must be configured on the HTTP client before making a call.
Defining the REST adapter
Set up the retrofit instance by providing the resource client (UserClient#getResourceOkHttpClient()
), resource gateway URL and REST interface.
Performing the resource call
After the retrofit is defined and instantiated, you can proceed and perform the resource call itself. The Android 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.
If the user's access token is available, the operation will succeed. If the resource gateway responds with 401 unauthorized
the access token is invalid.
Fetching a resource on behalf of implicitly authenticated user
To request a resource for an implicitly authenticated user, the client needs to be registered and the user's implicit access token needs to be present within the application memory. You require the implicit UserClient#authenticateUserImplicitly
authentication flow to succeed before a resource call can be made on behalf of an implicitly authenticated user.
An implicit resource request should be used in cases where the usage of certain functionality or access to resources does not require a user to explicitly authenticate themself.
Defining the REST interface
To fetch a resource, you must define a REST interface. The user-id-decorated
path is relative to the endpoint that you need to configure on the HTTP client before making a call.
Defining the REST adapter
Set up the retrofit instance by providing the UserClient#getImplicitResourceOkHttpClient()
resource client, resource gateway URL, and REST interface.
Performing the implicit resource call
When the retrofit is defined and instantiated, you can perform the resource call. The Android 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.
If the user's access token is available, the operation will succeed. If the resource gateway responds with 401 unauthorized
, the access token is invalid.
Performing multipart REST request
The retrofit library also supports multipart requests, simply by adding the proper annotation:
Performing modified REST requests
To add custom headers to all requests made by your RestAdapter, create a requestInterceptor
instance and set it in the RestAdapter.Builder
when you are constructing your RestAdapter.
Perform request to any certified baseUrl
By using the retrofit builder, you are able to send requests to any baseUrl thats certificates have been added to.