High-level description of the Server Side Library calls

Server Side Library 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

High-level description of the SDK calls

Step 1: Discovery request

  • The attemptDiscovery method is used for the Discovery request and Provider Metadata request.
  • Discovery Service returns DiscoveryResponse and ProviderMetadata

Note: if you operate in the EU then you should use EU Discovery Service domain: eu.discover.mobileconnect.io

Step 2: Create Authorization requests

  • The startAuthentication method is used to create Authentication and Authorisation requests
  • The method returns a URL with required and optional parameters

Step 3: Authentication, Authorization, RequestToken, JWKS requests

  • Application should redirect user to the URL, generated on Step 2

Step 4: Identity and UserInfo request - optional

  • The requestIdentity and requestUserInfo methods are used for Identity and UserInfo requests
  • Identity and Userinfo services return IdentityResponse/Userinfo responses

 

Function calls to Native API calls

 

The attemptDiscovery call

 

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 call

 

startAuthentication 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

 

requestIdentity / requestUserInfo

 

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
}