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

 

Java 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 Java Controller / Web Server which then uses the data received from the client to set up the calls to the Java Server Side SDK methods.
The Java 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.

 

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 {
    Date ttl; - timestamp for Discovery API response expiring
    int responseCode; - Discovery API response code
    List<KeyValuePair> headers; - Discovery response headers
    ErrorResponse errorResponse; - Discovery error response
    DiscoveryResponseData responseData; - Discovery response data
    OperatorUrls operatorUrls; - Discovery response MNO endpoints
    String clientName; - Discovery response client name
    ProviderMetadata providerMetadata; - ProviderMetadata response (R2 only)
}

 

The startAuthentication/startAuthorize call

The startAuthentication/startAuthorize 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/startAuthorize response

mobileConnectStatus object returned startAuthentication example:

MobileConnectStatus{
    MobileConnectStatus.ResponseType 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
    List<String> setCookie; - response cookies
    String sdkSession; - cache key 
    DiscoveryResponse discoveryResponse; - response from Discovery API
    RequestTokenResponse requestTokenResponse; - 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

The client (e.g. browser) sends the authorize request as soon as the SP returns authorize URL. The 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

MobileConnectStatus{
    MobileConnectStatus.ResponseType 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 outcome; - the outcome of the operation if no RequestTokenResponse is to be returned
    String url; - authorization url if startAuthentication method call, null in other cases
    String state; - authorization request "state" parameter
    String nonce;  - authorization request "nonce" parameter
    List<String> setCookie; - response cookies
    String sdkSession; - cache key 
    DiscoveryResponse discoveryResponse; - response from Discovery API
    RequestTokenResponse requestTokenResponse; - response from Token API
    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
    }
    Exception exception; - exception details, null if no exception thrown
}

 

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 makes a call with subscriberID to server side by sending GET request using the web view.
2. Server side gets subscriberID 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 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