Bundling of Products
This tutorial will explain what product bundling is and how to use it.
At first, we will however explain how this fits in with our current authentication and authorization.
Flows for enabling products
A product can be enabled for a subscription either by the subscriber adding the product themselves or by the operator adding the product on behalf of their subscribers.
Client Credentials FLow
For operators adding a product to one of its subscriptions, authorization will be done via the OAuth 2.0 Credentials Client Flow.
In this flow the token authenticates and authorizes the product, and not the subscriber. Access will therefore depend on there being a stored consent in our system which grants access to the product for the given subscriber.
We have three different ways of adding such a consent:
Operator Products
Creates a consent that covers all subscriptions belonging to an operator.
This is done by enabling the product in console.wgtwo.com.
Typical usage is granting your BSS system access to all of your subscribers.
Developer access
Creates a consent for a single subscription. Also applicable for unverified products.
A product will not be shown to an operator before we have manually approved the product. This is to ensure our marketplace is safe and that the products are legit.
Using this consent, a product may be granted access to a subscription while the product is still a draft.
Please contact us at mobility-services-developer@cisco.com, and we may grant access in cooperation with the operator.
Product bundling
Creates a consent for a single subscription.
This is done through the provisioning API, where the BSS system may provide a list of products that should be enabled for the subscription.
This will be covered in details in this document.
The product bundling flow
We support the use-case of an operator granting access to a product for one of its subscriptions.
In this case, the operator grants access without any user interaction or browser, so there is no redirect back to the product.
How to use as an operator
An operator will configure product bundling by making a request to our Provisioning API. This is typically handled by the operator's BSS system, which will provide a list of the product that should be bundled for the subscription.
This may be configured when activating the subscription or as a update for existing subscriptions.
Example: Bundle security-notification and webfilter-for-kids
curl \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-d '
{
"bssid": "wotel",
"msisdn": "46999999999",
"services": {
"add": [
{
"servicename": "PRODUCT_BUNDLING",
"config": {
"products": [
"security-notification",
"webfilter-for-kids"
]
}
}
]
}
}
' \
https://sandbox.api.shamrock.wgtwo.com/provision/v2/update
Providing a list of bundled products will overwrite any previous value.
A product is removed by doing a new request with full list of products except the one to be removed.
Operator api.shamrock.wgtwo.com Consents
│ │ │
│ 1. Bundle product │ │
│──────────────────►│ │
│ │ 2. Lookup scopes │
│ │ ╮ │
│ │◄╯ │
│ │ 3. Store consent │
│ │─────────────────►│
│ │ │
The flow
- The operator bundles a product for a subscription.
- There will be a lookup for what scopes this product should have access to.
The access required by the product is displayed at console.wgtwo.com. - The consent is stored, and the product now has the given access to the subscription.
How to use as a product developer
Once the consent has been created by the operator, the product has been granted the agreed access to the given subscription.
The product may initiate a gRPC server-side stream to receive notifications for when a consents are added, updated, or revoked.
Operator api.shamrock.wgtwo.com Consents Product
│ │ │ │
│ 1. Bundle product │ │ │
│──────────────────►│ │ │
│ │ 2. Lookup scopes │ │
│ │ ╮ │ │
│ │◄╯ │ │
│ │ 3. Store consent │ │
│ │─────────────────►│ 4. Notify │
│ │ │─────────────────►│
The notification stream is initiated by calling the Consent Event gRPC service.
The stream will, with the default configuration, keep all messages until the client sends an explicit ack message.
This notification may be used to send a welcome SMS with instructions on how to use the product, cleanup if consent is revoked and such.
Using the API after receiving a consent
Both setting up the notification stream and actions on behalf of the subscriptions will use the Client Credentials Flow,
as authorization is handled by the stored consents.
As this authenticates the product, and not the subscription, we will do a lookup to see if there are any consents granting the required access to the product.
Example: Listen for consent to send an SMS using gRPCurl
See: Get started
Obtain client credentials
You do not require any scope to initiate the consent stream.
Including phone and sms.text:send_to_subscriber in the example below, as we will include using the client credentials access token to send an SMS.
These scopes would also need to be enabled for the product in https://developer.mobility.cisco.com/, where you also may create a
OAuth 2.0 client to obtain the CLIENT_ID and CLIENT_SECRET.
curl \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data grant_type="client_credentials" \
--data scope="phone sms.text:send_to_subscriber" \
https://id.wgtwo.com/oauth2/token
{
"access_token": "loremipsumdolorsitametconsecteturadipiscing",
"expires_in": 3599,
"scope": "phone sms.text:send_to_subscriber",
"token_type": "bearer"
}
Initiate consent event stream
Using custom configuration for not requiring
ackand not store reading position on server.
This is not recommended for production, but may be useful for testing.
grpcurl \
-d '
{
"stream_configuration": {
"regular": {},
"disable_explicit_ack": {}
}
}
' \
sandbox.api.shamrock.wgtwo.com:443 \
wgtwo.consents.v1.ConsentEventService/StreamConsentChangeEvents
{
"metadata": {
"timestamp": "2022-08-18T09:58:50.144Z",
"identifier": {
"subscriptionIdentifier": {
"value": "f9o8zprqyp889zyia7iretvhtpwbvl3grybfwafv"
}
},
"ackInfo": {
"value": "some-value"
}
},
"consentChangeEvent": {
"added": {
"scopes": [
"offline_access",
"openid",
"phone",
"events.handset_update.subscribe",
"subscription.handset_details:read",
"sms.text:send_to_subscriber"
]
},
"number": {
"e164": "+4799990000"
}
}
}
The response above is a single event in the stream.
You will get the subscriptionIdentifier which is the pairwise pseudonymous identifier for the subscription. This is a unique identifier for the subscription, which may be useful as MSISDNs can be reused.
The event will also include which scopes are granted and the user's phone number.
Send welcome SMS
You may use the same access token as for setting up the consent event stream
Once you have gotten a notification that a new subscription is added, you may send a welcome SMS.
Access is granted by the product now having a consent for the scope sms.text:send_to_subscriber covering the
subscription given in toSubscriber.
grpcurl \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '
{
"content": "My text message",
"fromAddress": "MyProduct",
"toSubscriber": "+4799990000"
}
' \
sandbox.api.shamrock.wgtwo.com:443 \
wgtwo.sms.v1.SmsService/SendTextToSubscriber