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
andmnc
- 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
- Server Side should send response
- 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
- Server Side should send response
- 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
- Server Side should send response
- 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
- Server Side should send response
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.