Authorization

Full authorization reference for the MAUI SDK

The SDK exchanges data with the Engagement APIs through authorized HTTP/HTTPS communication. The SDK supports two authorization modes: the default token authorization for public API access and the more secure customer token authorization for private API access. Developers can choose the appropriate authorization mode for the required level of security.

Token authorization

The default token authorization mode provides public API access using an API key as a token.

Token authorization is used for the following API endpoints by default:

POST /track/v2/projects/<projectToken>/customers for tracking of customer data
POST /track/v2/projects/<projectToken>/customers/events for tracking of event data
POST /track/v2/projects/<projectToken>/campaigns/clicks for tracking campaign events
POST /data/v2/projects/<projectToken>/customers/attributes for fetching customer attributes
POST /data/v2/projects/<projectToken>/consent/categories for fetching consents
POST /webxp/s/<projectToken>/inappmessages?v=1 for fetching in-app messages
POST /webxp/projects/<projectToken>/appinbox/fetch for fetching of App Inbox data
POST /webxp/projects/<projectToken>/appinbox/markasread for marking of App Inbox message as read
POST /campaigns/send-self-check-notification?project_id=<projectToken> for part of self-check push notification flow

Developers must set the token using the authorizationToken configuration parameter when initializing the SDK:

var config = new Configuration("YOUR_PROJECT_TOKEN", "YOUR_API_KEY", "YOUR_API_BASE_URL");
Bloomreach.BloomreachSDK.Configure(config);

Customer token authorization

Customer token authorization is optional and provides private API access to select Engagement API endpoints. The customer token contains encoded customer IDs and a signature. When the Bloomreach Engagement API receives a customer token, it first verifies the signature and only processes the request if the signature is valid.

The customer token is encoded using JSON Web Token (JWT), an open industry standard RFC 7519 that defines a compact and self-contained way for securely transmitting information between parties.

The SDK sends the customer token in Bearer <value> format. Currently, the SDK supports customer token authorization for the following Engagement API endpoints:

POST /webxp/projects/<projectToken>/appinbox/fetch for fetching of App Inbox data
POST /webxp/projects/<projectToken>/appinbox/markasread for marking of App Inbox message as read

Developers can enable customer token authorization by setting the AdvancedAuthEnabled configuration parameter to true when initializing the SDK:

var config = new Configuration("YOUR_PROJECT_TOKEN", "YOUR_API_KEY", "YOUR_API_BASE_URL");
config.AdvancedAuthEnabled = true;
Bloomreach.BloomreachSDK.Configure(config);

Additionally, developers must implement an authorization provider that provides a valid JWT token that encodes the relevant customer ID(s) and private API key ID. You must implement a different provider in native code for each platform.

❗️
Customer tokens must be generated by a party that can securely verify the customer's identity. Usually, this means that customer tokens should be generated during the application backend login procedure. When the customer identity is verified (using password, 3rd party authentication, Single Sign-On, etc.), the application backend should generate the customer token and send it to the device running the SDK.

📘
Refer to Generating customer token in the customer token documentation for step-by-step instructions to generate a JWT customer token.

Android authorization provider

First, implement an authorization provider as in the following example:

using Android.Runtime;

namespace YourApplicationNamespace.Droid
{
    [Register("RegisteredClassName")]
    public class ExampleAuthProvider : Java.Lang.Object, IAuthorizationProvider
    {
        public ExampleAuthProvider()
        {
        }

        public string AuthorizationToken => ...
    }
}

❗️
Please note the requirements of the class definition. Your class must be registered with a name (see [Register("RegisteredClassName")]) that will be searched by the SDK. Also, the class must extend Java.Lang.Object and IAuthorizationProvider to support valid communication between native and Xamarin implementations.

Your authorization provider must be registered in the AndroidManifest.xml file as in the following example:

<application
    ...
    <meta-data
        android:name="ExponeaAuthProvider"
        android:value="RegisteredClassName"
        />
</application>

AndroidManifest.xml metadata are typically registered with AssemblyInfo.cs. To register your authorization provider, add the following line:

[assembly: MetaData("ExponeaAuthProvider", Value = "RegisteredClassName")]

Troubleshooting

If your authorization provider is not working correctly, SDK initialization will fail. Check the log for details:

If you enable customer token authorization using the configuration flag AdvancedAuthEnabled but the SDK can't find an authorization provider implementation, you'll see the following message logged:
```
Advanced auth has been enabled but provider has not been found
```
If you register your class in AndroidManifest.xml but the SDK can't find that class, you'll see the following message logged:
```
Registered <your class> class has not been found` with detailed info.
```
If you register your class in AndroidManifest.xml but the class doesn't implement the IAuthorizationProvider interface, you'll see the following message logged:
```
Registered <your class> class has to implement com.exponea.sdk.services.AuthorizationProvider
```

The AuthorizationProvider is loaded during SDK initialization or after calling BloomreachSDK.Configure(). You should see the above log messages at the same time.

iOS authorization provider

Implement the MauiAuthorizationProvider protocol with [Register("MauiAuthProvider")] as in the following example:

using Foundation;

namespace YourApplicationNamespace.iOS
{
    [Register("MauiAuthProvider")]
    public class ExampleAuthProvider : MauiAuthorizationProvider
    {
        public ExampleAuthProvider()
        {
        }

        public override string AuthorizationToken => ...
    }

}

❗️
Please note the requirements of the class definition. Your class must be registered with a name (see [Register("MauiAuthProvider")]) that will be searched by the SDK. Also, the class must extend MauiAuthorizationProvider to support valid communication between native and MAUI implementations.

Troubleshooting

If you define ExponeaAuthProvider but it is not working as expected, check the logs for the following:

If you enable customer token authorization by setting the configuration flag AdvancedAuthEnabled to true but the SDK can't find a provider implementation, it will log the following message:
```
Advanced authorization flag has been enabled without provider
```
The registered class must extend NSObject. If it doesn't, you'll see the following log message:
```
Class MauiAuthProvider does not conform to NSObject
```
The registered class must conform to MauiAuthorizationProvider. If it doesn't, you'll see the following log message:
```
Class MauiAuthProvider does not conform to AuthorizationProviderType
```

Asynchronous authorization provider implementation

The customer token value is requested for every HTTP call at runtime. The value of AuthorizationToken is requires in a background thread. Therefore, you are able to block any asynchronous token retrieval (i.e. other HTTP call) and wait for the result by blocking this thread. If the token retrieval fails, you may return a NULL value but the request will automatically fail.

Customer token retrieval policy

The customer token value is requested for every HTTP call that requires it.

Typically, JWT tokens have their own expiration lifetime and can be used multiple times. The SDK does not store the token in any cache. Developers may implement their own token cache as they see fit. For example:

❗️
Please consider to store your cached token more securely. Android offers multiple options such as KeyStore or Encrypted Shared Preferences.

❗️
A customer token is valid until its expiration and is assigned to the current customer IDs. Bear in mind that if customer IDs change (due to invoking the IdentifyCustomer or Anonymize methods), the customer token may become invalid for future HTTP requests invoked for new customer IDs.

Updated 2 months ago