Secured resource access
Resource calls made with the SDK are always secured with certificate pinning. Payload encryption can be enabled in the Token Server. Debug detection can be configured in the Config Model, if enabled the SDK will verify there is no debugger attached to the app process before fetching the resource. SDK does not perform any mapping or conversion of the response payload. It is up to the App how to process a valid response from the back-end.
Get resource flow:
The SDK can fetch a secure resource in three distinct ways. For a resource that is tied to a user (e.g. account information or transactions), the SDK can execute an Secured resource access. For a resource that is tied to an application but are not unique per user, for example application assets, the SDK can execute an Anonymous request. For a resource that can be fetched without any additional authentication, but for which you would still like to use certificate pinning and jailbreak/debug detection the SDK can execute an Unauthenticated requests.
Authenticated requests
Secure resource access is performed using UserClient
for authorized calls and DeviceClient
for anonymous calls.
Instances can be obtained by using userClient
and deviceClient
respectively, or by calling SharedUserClient.instance
and SharedDeviceClient.instance` respectively. Attempt to obtain clients instances without configuring the SDK first, will result in throwing
NSInternalInconsistencyException` exception.
Performing a resource call
For user specific resources the user needs to be authenticated and a token that is connected to the authenticated user is presented to the back-end when fetching a resource.
The SDK requires that the user is authenticated. Fetching user specific resources using the SDK is done through the following UserClient
method:
Example of an authenticated resource call
Implicit requests
Implicit resource requests are performed using the UserClient
. It can be obtained by using the
userClient
of the Client
object or by calling the SharedUserClient.instance
method.
Performing a resource call
Implicit resource calls are authenticated using an implicit access token. It is obtained by the SDK during implicit user authentication. You can find more information about the process in the Implicit user authentication guide. Fetching implicit resources using the SDK is done through the following ONGUserClient method:
Example of an implicit resource call
Anonymous requests
Secure anonymous resource access is performed using the DeviceClient
. It can be obtained by using the
deviceClient
of the Client
object or by calling the SharedDeviceClient.instance
method. Any
attempt to obtain the DeviceClient
without configuring the SDK first, will result in throwing a NSInternalInconsistencyException
exception.
Performing a resource call
For anonymous resources a token that is connected to this device is presented to the back-end. Anonymous resource calls allow you to fetch data that is not user specific but should not be publicly available to anybody knowing the API.
The SDK requires the device (application) to be registered, valid and authenticated. Fetching anonymous resources using the SDK is done through the
following DeviceClient
method:
Example of an anonymous resource call
Unauthenticated requests
Securing unauthenticated requests is performed using the DeviceClient
. It can be obtained by using the
deviceClient
of the Client
object or by calling the SharedDeviceClient.instance
method.
attempt to obtain the DeviceClient
without configuring the SDK first, will result in throwing a NSInternalInconsistencyException
exception.
Performing a resource call
For unauthenticated requests no token is presented to the back end. Only certificate pinning and jailebreak/debug detection are
used when fetching unauthenticated resources. Fetching unauthenticated resources using the SDK is done through the
following DeviceClient
method:
Example of an unauthenticated resource call
Request Construction
Manual
Both authenticated and anonymous resource calls starts from the ResourceRequest
construction. The request object combines the following properties:
path
- URI path, appended toResourceBaseURL
set within theClient
configuration.method
- HTTP request method, can be one ofget
,post
,put
,patch
,head
anddelete
.parameters
- a dictionary of parameters used for the request. Parameters are appended to the URL or provided within a body depending on the request method (respectivelyget
orpost
).parametersEncoding
- the encoding used for params, possible values arejson
orformUrl
The default value isencodingJSON
.body
- a raw bady of the request. If specified it overwrites theparameters
andparametersEncoding
.multipartData
- the object that represents the multipart data that should be sent. Themultipart/form-data
Content-Type header is added automatically. Only the HTTP POST method is supported for a multipart request. Note that if you add multipart data theparametersEncoding
property is neglected.headers
- additional headers added to the HTTP request. The SDK takes the responsibility of managing theAuthorization
andUser-Agent
headers. These cannot be modified / provided.
path can be set to an absolute URL and can vary from that one set in the model. The domain for a different base URL has to be protected with a valid certificate, otherwise the pinning mechanism will not allow the fetch to be executed.
In order to create an instance of the ResourceRequest
you may use ResourceRequestFactory
:
In addition to ResourceRequest
, which is immutable by design there is a counterpart - MutableResourceRequest
that allows you to modify all of the available properties one by one.
Example of request construction
Request Builder
In order to simplify request construction the SDK offers a ONGRequestBuilder
class, that allow you to build new immutable requests through a set of methods
that reflect ONGResourceRequest
properties and build an actual request instance by calling the -[ONGRequestBuilder build]
method:
Example request construction using the builder
Handling the resource response
The responsibility for handling the fetched resource response belongs to the completion block passed into fetchResource:completion:
. Below
you can find the explanation of the two possible outcomes for fetching resources.
Resource call completion
The completion block will be called whenever a fetch resource call is completed. The following values are provided:
response
- the object containing the status code, headers and the bare data containing the body which needs to be decoded.error
- defines the type of error that occurred. Depending on the error reason the following domains are possible:ONGFetchResourceErrorDomain
(only for authenticated resource requests),ONGFetchAnonymousResourceErrorDomain
(only for anonymous requests),ONGFetchUnauthenticatedResourceDomain
(only for unauthenticated resource requests), theONGGenericErrorDomain
in case of a generic error or theNSURLError
in case of a http related error.
Example resource call implementation with a JSON encoded payload
Handling resource call errors
In case of a resource call failure the SDK will provide an error. Depending on the error reason and resource call type the following domains are possible:
ONGFetchResourceErrorDomain
(only for authenticated requests), ONGFetchAnonymousResourceErrorDomain
(only for anonymous requests), ONGGenericErrorDomain
,
NSUrlError
(in case of http related errors).
Example error handling
Running resource call handling
Both authenticated and anonymous resource calls return an instance of the ONGNetworkTask
. This object allows you to control and observe the execution by
inspecting various properties:
state
- enumONGNetworkTaskState
, describing whether task is running, suspended, cancelled or completed.identifier
- unique task identifier.request
- request with which the resource call has been made.response
- instance ofONGResourceResponse
. This value fulfilled upon request completion and contains useful information likeHTTP Status Code
, response headers and the actual body of the response. For advanced usage it provides a reference to theNSHTTPURLResponse
object.error
- instance ofNSError
fulfilled in case of a request failure. It might be of theNSURLErrorDomain
orONGGenericErrorDomain
.
You can control tasks through the following methods:
cancel
- cancel a running or suspended task.suspend
- suspend a running task.resume
- resume a suspended task.