PHP SDK overview

High-level description of the Server Side SDK calls

Calls to the Server side SDK

Client Side Libraries include route /start_discovery, that could be called with following parameters

  • Call with mcc and mnc - this parameters in request leads user to MCC/MNC-based Discovery
    • Server Side should send response 302 Redirect to ID GW auth screen
    • User should enter his MSISDN
    • Server Side receive auth code and automatically send token request
    • User should be authenticated
  • Call with msisdn - this parameters in request leads user to MSISDN-based Discovery
    • Server Side should send response 302 Redirect to ID GW auth request
    • Server Side receive auth code and automatically send token request
    • User should be authenticated
  • Headers X-Forwarded-For, remoteAddr etc - this parameters in request leads user to IP-based Discovery
    • Server Side should send response 302 Redirect to ID GW auth screen
    • User should enter his MSISDN
    • Server Side receive auth code and automatically send token request
    • User should be authenticated
  • No query parameters - should lead user to Discovery UI flow
    • Server Side should send response 302 Redirect to Operator Selection screen
    • User should enter his MSISDN
    • Discovery Service send 302 Redirect to receive Discovery Response
    • Server Side receive Discovery Response and automatically send auth request to ID GW
    • Server Side receive auth code and automatically send token request
    • User should be authenticated

PHP SDK Method calls to Native API calls

The diagram below shows the key components of the Mobile Connect System and how they fit together.

 



The client side app (using client libraries) makes HTTP calls to the PHP Controller / Web Server which then uses the data received from the client to set up the calls to the PHP Server Side SDK methods.
The PHP server side SDK is designed to manage the interaction between the SP server and the Mobile Connect system components, i.e. the API Exchange and the MNOs ID Gateways. The server side SDKs create the API calls and parse the API responses in accordance with the Mobile Connect system requirements. The SP developer does not need to code the calls and response parsing, the complexity of that is done by the SDK.
The SDKs are also designed to handle system errors, store data in cache and clear cache as required for the efficient operation of the Mobile Connect products.

Note: SDKSession - identifier of current sdk deploy session (cache key). Using this parameter you can get cached mobileConnectStatus object.

The attemptDiscovery call

The attemptDiscovery SDK method call takes the data parameter supplied by the client and builds the most appropriate Discovery API request (by msisdn, mcc/mnc pair or sourceIp) and then makes the call to the API Exchange. The method then waits for the Discovery API response, once the response is received, the SDK takes the response parameters and stores them ready for future use.
If the Discovery response includes the MNOs provider metadata endpoint, the SDK method will then call the provider metadata API to retrieve further data required for the use of the MNO identity products.
Finally, the SDK method makes a callback to the client with the data needed for the ID Gateway authentication call.

Note: the authentication product call is made to the authorize endpoint in Mobile Connect.

 

AttemptDiscovery response

class DiscoveryResponse
{
    private $_ttl; - timestamp for Discovery API response expiring
    private $_responseCode; - Discovery API response code
    private $_headers; - Discovery response headers
    private $_errorResponse; - Discovery error response
    private $_responseData; - Discovery response data
    private $_operatorUrls; - Discovery response MNO endpoints
    private $_applicationShortName; - Discovery response client name
    private $_providerMetadata; - ProviderMetadata response (R2 only)
}

 

Discovery Response Caching

Demo Server Side SDK records each successful Discovery Response in Discovery Cache.
Adding, getting and removing records is performing by using a key that includes user MSISDN, MCC, MNC, IP.
Record is removing from cache only in case of expired Discovery Response. Response expiration is determined by “ttl” (time to live) parameter value processing in Discovery Response.
The ‘ttl’ value should be in the following range:

  • more than 5mins;
  • less than 259200mins.

In case of ‘ttl’ value is less than 5mins, Discovery Response’s ‘ttl’ is overwritten with 5mins.
In case of ‘ttl’ value is more than 259200mins, Discovery Response’s ‘ttl’ is overwritten with 259200mins.
There no cache autoremove mechanism or clearing cache based on the Authentication/Authorisation error response. Removing from cache can occur only during an attempt to get a record. Discovery Cache receives request for a record with particular key. Inner mechanism search record in storage and performs verification. If Response is expired, record will be removed and Cache won’t return expired response.

See the Demo App Page for more details and code examples.

The startAuthentication/startAuthorisation call

Important. Headless mode is not used any more. Please, use Server Initiated API instead.

The startAuthentication SDK method call takes the input parameters (subscriberID, state, etc) and builds the URL to the authorize endpoint. This URL is then returned to the client application ready for the client to actually make the authorize call, provided there are no errors.

The startAuthorisation SDK method call takes the input parameters (subscriberID, state, etc) and builds the URL to the authorize endpoint. This URL is then returned to the client application ready for the client to actually make the authorize call, provided there are no errors.

 

startAuthentication/startAuthorisation response

MobileConnectStatus object returned StartAuthentication example:

MobileConnectStatus{
    private $_responseType; - API response type
    private $_errorCode; - null if no error in response, otherwise - contains error code
    private $_errorMessage; - null if no error in response, otherwise - contains error code
    private $_url; - authorization url if startAuthentication method call, null in other cases
    private $_state; - authorization request "state" parameter
    private $_nonce;  - authorization request "nonce" parameter
    private $_cookie; - response cookies
    private $_sdkSession; - cache key 
    private $_discoveryResponse; - response from Discovery API
    private $_tokenResponse; - response from Token API
    private $_identityResponse; - response from userinfo/identity api
    private $_exception; - exception details, null if no exception thrown
}

 

Session Data Caching

Demo Server Side SDK records Discovery Response and generated nonce and state to make possible handle Authorisation Request and detect “session” to perform next Token and Resource Endpoint Requests using data that was received on the previous steps.
Session cache records Discovery Response and nonce by “state” parameter value key.
Removing from cache occurs only during an attempt to get a record. Session Cache receives request for a record with particular key. Inner mechanism searches record in storage, returns found data and automatically removes record from Session Cache.

See the Demo App Page for more details and code examples.

Send authentication request and request token

requestToken SDK method is called after successful authentication. The method builds and sends the call to the ID Gateway token endpoint. The response from the token endpoint is stored for future use.

 

PremiumInfo requests are performing for mc_v2.0, mc_di_r2_v2.3 and mc_di_v3.0 api versions and UserInfo for mc_v1.1 only.

RequestIdentity / RequestUserInfo

The SDK methods requestIdentity, requestUserInfo are used to make calls to the Identity and UserInfo endpoints provided by the MNOs in the ID Gateways.
The response data is stored for future use.

 

RequestIdentity/RequestUserinfo response

MobileConnectStatus object returned RequestIdentity/RequestUserinfo

IdentityResponse {
    private $_convertedResponseData;- Identity/Userinfo API response as object - could be casted to UserinfoData/IdentityData objects
    private $_responseCode; - Identity/Userinfo API response code
    private $_errorResponse; - Identity/Userinfo API error response
    private $_responseJson; - Identity/Userinfo API response as string
}

 

High-level description of the Without Discovery mode

Without Discovery mode allows calls to Mobile Connect without first doing a Discovery call. It is a similar process to usual Mobile Connect Authentication/Authorisation. Instead of calls to the Discovery Service a new function is used to load operator endpoints via manual loading (configuration) or via Provider Metadata service if supported.

Steps for ‘Without Discovery’ client-server session:
1. Client side makes a call with MSISDN to server side by sending GET request using the web view.
2. Server side gets MSISDN from client. Then server processes SP data from the configuration and operator data from configuration or using provider metadata (if provider metadata URL is provided).
3. Server side prepares authentication/authorisation URL and returns it to the client side (web view).
4. Client side processes authentication/authorisation URL. After a few redirect ID GW must return authorise callback that must request to the server side (with authorization code in successful authorisation case).
5. Server side makes token and userinfo/premiuminfo requests (regarding configuration).
6. The result returns to client side.

Diagram below shows iterations mechanism for ‘without discovery’ mode.