Secured resource access
Resource calls made with the Onegini 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 ONGUserClient
for authorized calls and ONGDeviceClient
for anonymous calls.
Instances can be obtained by using @property (nonatomic, readonly) ONGUserClient *userClient;
and @property (nonatomic, readonly) ONGDeviceClient *deviceClient;
respectively, or by calling [ONGUserClient sharedInstance]and [ONGDeviceClient sharedInstance]
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 Onegini SDK is done through the following ONGUserClient
method:
Example of an authenticated resource call
Implicit requests
Implicit resource requests are performed using the ONGUserClient
. It can be obtained by using the
@property (nonatomic, readonly) ONGUserClient *userClient;
of the ONGClient
object or by calling the +[ONGUserClient sharedInstance]
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 Onegini SDK is done through the following ONGUserClient method:
Example of an implicit resource call
Anonymous requests
Secure anonymous resource access is performed using the ONGDeviceClient
. It can be obtained by using the
@property (nonatomic, readonly) ONGDeviceClient *deviceClient;
of the ONGClient
object or by calling the +[ONGDeviceClient sharedInstance]
method. Any
attempt to obtain the ONGDeviceClient
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 Onegini SDK is done through the
following ONGDeviceClient
method:
Example of an anonymous resource call
Unauthenticated requests
Securing unauthenticated requests is performed using the ONGDeviceClient
. It can be obtained by using the
@property (nonatomic, readonly) ONGDeviceClient *deviceClient;
of the ONGClient
object or by calling the +[ONGDeviceClient sharedInstance]
method.
attempt to obtain the ONGDeviceClient
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 Onegini SDK is done through the
following ONGDeviceClient
method:
Example of an unauthenticated resource call
Request Construction
Manual
Both authenticated and anonymous resource calls starts from the ONGResourceRequest
construction. The request object combines the following properties:
path
- URI path, appended toONGResourceBaseURL
set within theONGClient
configuration.method
- HTTP request method, can be one of@"GET"
,@"POST"
,@"PUT"
and@"DELETE"
.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 (respectively@"GET"
or@"POST"
).parametersEncoding
- the encoding used for params, possible values areONGParametersEncodingJSON
orONGParametersEncodingFormURL
(seeONGResourceRequest.h
for the declarations). The default value isONGParametersEncodingJSON
.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 Onegini SDK takes the responsibility of managing theAuthorization
andUser-Agent
headers. These cannot be modified / provided.
In order to create an instance of the ONGResourceRequest
you may use one of the built-in initializers:
In addition to ONGResourceRequest
, which is immutable by design there is a counterpart - ONGMutableResourceRequest
that allows you to modify all of the available properties one by one.
Both ONGResourceRequest
and ONGMutableResourceRequest
conform to the NSCopying
and NSMutableCopying
protocols for easier usage.
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.