High-level description of the Server Side SDK calls

Server Side SDK call

The Client Side Library includes 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 browser or local client 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

DiscoveryResponse {
    DateTime Ttl; - timestamp for Discovery API response expiring
    int ResponseCode; - Discovery API response code
    List<BasicKeyValuePair> Headers; - Discovery response headers
    ErrorResponse ErrorResponse; - Discovery error response
    DiscoveryResponseData ResponseData; - Discovery response data
    OperatorUrls OperatorUrls; - Discovery response MNO endpoints
    string ApplicationShortName; - Discovery response client name
    ProviderMetadata ProviderMetadata; - ProviderMetadata response (R2 only)
}

 

The StartAuthentication call

 

StartAuthentication response

MobileConnectStatus object returned StartAuthentication example:

MobileConnectStatus{
    MobileConnectResponseType ResponseType; - API response type
    string ErrorCode; - null if no error in response, otherwise - contains error code
    string ErrorMessage; - null if no error in response, otherwise - contains error code
    string Url; - authorization url if startAuthentication method call, null in other cases
    string State; - authorization request "state" parameter
    string Nonce;  - authorization request "nonce" parameter
    IEnumerable<string> SetCookie; - response cookies
    string SDKSession; - cache key 
    DiscoveryResponse DiscoveryResponse; - response from Discovery API
    RequestTokenResponse TokenResponse; - response from Token API
    IdentityResponse IdentityResponse; - response from userinfo/identity api
    Exception Exception; - exception details, null if no exception thrown
} 

 

Send authentication request and request token

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

 

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 {
    int ResponseCode; - Identity/Userinfo API response code
    ErrorResponse ErrorResponse; - Identity/Userinfo API error response
    string ResponseJson; - Identity/Userinfo API response as string
    object _convertedResponseData; - Identity/Userinfo API response as object - could be casted to UserinfoData/IdentityData objects
}