Tutorial: Login with OAuth2.0

Serverless AuthenticationSigning in and out Login with OAuth2.0

Most end users already have accounts with major worldwide IT service providers such as Google or Facebook. Such actors provide with secure authentication APIs, generally based on the OAuth2.0 framework, aimed at third-party applications to safely identify end users. Webcom SDK comes with APIs that make it easy to integrate authentication delegation to third-party OAuth2.0-compliant identity providers into your applications.

By default all authentication delegation methods are disabled on Webcom applications. Developers have to explicitly enable them for each required provider using the "authentication" tab of the Webcom developer console.

Orange Mobile Connect implements the Mobile Connect standard for most of Orange countries. Orange Mobile Connect consists in authenticating users using their mobile phone equipped with an Orange SIM card.

Note that, prior to use this authentication method, the final users (Orange customers) of your applications must have installed the Mobile Connect SIM application provided by Orange, using the following links:

Webcom can also automatically interact with any identity provider implementing OIDC (OpenID Connect), which is a simple identity layer on top of the OAuth 2.0 framework. For example actors such as Amazon, Microsoft or Yahoo provide a full OIDC support.

Currently, there are two OIDC-based methods to authenticate Orange employees:

  • Orange Connect, which may be accessed from both internet and intranet and implements a very secured two-factors authentication,
  • Orange Employees (full name is Authentication for Orange employees), which may be accessed only from intranet and implements SSO (Single Sign On) through all Orange Corporate applications.

OAuth Applications

OAuth2.0 is actually an authorization framework rather than an authentication framework. Authorizations are granted by end users to entities generally known as applications, let call them here OAuth applications, as opposed to Webcom applications aimed at your end-users and developed using the Webcom SDK. OAuth applications must be created by developers with the OAuth2.0 provider prior to invoking its authorization API. When a Webcom application invokes the authorization method of the OAuth2.0 provider, the end user is first requested to log in on the OAuth2.0 provider portal and is then shown a consent screen to grant or deny authorizations required by the Webcom application. The consent screen is filled with the information set up by the developer within the OAuth application (typically the application name, icon and description).

sequenceDiagram participant U as User participant A as Application participant P as OAuth App participant B as Webcom back end U->>A: Click on "Sign in with ..." A->>P: Redirect to the authentication portal activate A P-->>U: Ask to sign in U-->>P: Validate the consent screen P-->>B: Redirect to B-->>P: Validate the received sign-in code P-->>B: Return identity details B->>A: Return the authentication result deactivate A A->>U: Display messages for the authenticated user

To guarantee an optimal security level, in the OAuth2.0 framework, the interactions between the user and the authentication portal of the 3rd-party provider is performed outside the control of your client application (dashed arrows on the diagram). The Webcom SDK implement them either by redirecting the page of a web application or by opening an independent webview or view controller in a mobile application. In addition, a secured exchange is played in the background between the Webcom and identity provider back ends. All these flows are implemented for you as soon as you use the Webcom SDK.

To create an OAuth application, OAuth2.0 providers supply a web portal generally called “developer console”:

See the technical documentation of your OIDC provider

  • Orange Connect: there is currently no interactive console for developers. You must ask for the creation of an OAuth application using the AVISO portal:
    1. Log in using your usual intranet credentials (CUID and associated password),
    2. Click on the "Créer une tâche" button to create a task,
    3. On the right side, fill in the "services" field with “IAM” and the "category" field with “7-Service Request”,
    4. On the left side, fill in the "subject/title" field with “New OIDC partnership for IAM DIOD” (note that OAuth applications are called here OIDC partnerships),
    5. Fill in the "description" field with something starting with “I would like a new OIDC partnership for IAM DIOD” and complete with the name of your project, and the OAuth2 callback URL to set (see redirect URI below).
  • Orange Employees: Orange Developer Inside

Once created, your OAuth application must be subscribed to the authentication API of the OAuth2.0 provider:

Add the "Facebook Login" product (button "Add Product" at the bottom of the left panel).

In the "Identifiers" section, create a new "OAuth client ID" (dropdown button "Create Identifiers" at the top of the page), and select the "web application" type.

Add a "Service ID" and bind it to your App ID ("Primary App ID" field of the configuration form).

No explicit subscription needed.

No explicit subscription needed.

Subscribe to both "Authentication France" API and "User details France" API (button "Use this API" at the top of the page).

See the technical documentation of your OIDC provider.

  • Orange Connect: nothing special to do, it is part of the created AVISO task,
  • Orange Employees: subscribe to Authentication for Orange employees by clicking on the corresponding "Use this API" button at the top of the page.

Now, you have to configure the OAuth2.0 redirect URI, that is, the URI where clients are redirected to when the authorization request completes (replace “<your-app>” with your actual application identifier):

Click on "Facebook Login" in the developer console of your OAuth application, and fill in the "Valid OAuth redirect URIs" field with:
https://io.datasync.orange.com/auth/v2/<your-app>/facebook/callback

Facebook requires to publish your OAuth application before other users may sign in on behalf of it.

Click on the previously created "OAuth client ID", and fill in the "Authorized redirect URIs" field with:
https://io.datasync.orange.com/auth/v2/<your-app>/google/callback

Google requires to setup additionally the origins from which web applications may sign in on behalf of your OAuth application.

When editing the configuration form of the previously created Service ID, fill in the "Return URLs" field with:
https://io.datasync.orange.com/auth/v2/<your-app>/apple/callback

  • don't forget to click the "Register" button on the Service ID edition screen, in addition to the "Save" button of the configuration form,
  • the "Web Domain" field must be filled although it doesn't need to be verified.

Click on the previously created OAuth application, and fill in the "Authorization callback URL" field with:
https://io.datasync.orange.com/auth/v2/<your-app>/github/callback

When creating your OAuth application, fill the "Redirect URI" field with:
https://io.datasync.orange.com/auth/v2/<your-app>/gitlab/callback

Click on the "Consent screen details" tab in the developer console of your OAuth application, and fill in the "Redirect URL" field with:
https://io.datasync.orange.com/auth/v2/<your-app>/orange/callback

Click on the "Consent screen details" tab in the developer console of your OAuth application, and fill in the "Redirect URL" field with the following values for each subscribed API:

  • Mobile Connect France: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOFR/callback,
  • Mobile Connect Spain: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOES/callback,
  • Mobile Connect Jordan: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOJO/callback,
  • Mobile Connect Madagascar: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOMG/callback,
  • Mobile Connect Morocco: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOMA/callback.
  • Mobile Connect Ivory Coast: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOCI/callback.
  • Mobile Connect Egypt: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOEG/callback.
  • Mobile Connect Congo: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOCG/callback.
  • Mobile Connect Botswana: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOBW/callback.
  • Mobile Connect Guinea Conakry: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOGN/callback.
  • Mobile Connect Tunisia: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOTN/callback.
  • Mobile Connect Senegal: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOSN/callback.
  • Mobile Connect Guinea Bissau: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOGW/callback.
  • Mobile Connect Cameroon: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOCM/callback.
  • Mobile Connect Liberia: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOLR/callback.
  • Mobile Connect Mali: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOML/callback.
  • Mobile Connect Niger: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectONE/callback.
  • Mobile Connect Burkina Faso: https://io.datasync.orange.com/auth/v2/<your-app>/mobileconnectOBF/callback.

See the technical documentation of your OIDC provider to find how to set the redirect URI fill it with:
https://io.datasync.orange.com/auth/v2/<your-app>/oidc.<your-provider>/callback
where <your-provider> must be replaced with the OIDC provider name you defined in the Webcom developer console (see next section).

  • Orange Connect: In the created AVISO task, give the following detail within the "description" field:
    The callback URL is https://io.datasync.orange.com/auth/v2/<your-app>/diod/callback”,
  • Orange Employees: Click on the "Consent screen details" tab in the developer console of your OAuth application, and fill in the "Redirect URL" field with:
    https://io.datasync.orange.com/auth/v2/<your-app>/employee/callback

Webcom application settings

Now, you have to configure your Webcom application within the "authentication" tab of the Webcom developer console.

First, the appropriate OAuth2.0 provider(s) must be enabled.

Next, the “client ID” and “client Secret” fields must be filled in with the corresponding values of your OAuth application:

Click on "Dashboard" in the developer console of your OAuth application, and pick up the values of the "App ID" and "App Secret" fields.

Click on the previously created "OAuth client ID" in the "Identifiers" section, and pick up the values of the "Client ID" and "Client Secret" fields.

Apple uses slightly different settings:

  1. In the Apple Developer Console, generate a key with the "Sign In with Apple" service enabled,
  2. In the Webcom developer console:
    • fill in the "Service ID" identifier (created at the previous step), your "Team ID" (it is generally displayed in the top right corner of the Apple Developer Console), and the "Key ID" of the just generated key,
    • Paste the content of the just generated key into the "private key" field (warning: the key content can be downloaded from the Apple Developer Console just once).

Click on the previously created OAuth application, and pick up the values of the "Client ID" and "Client Secret" fields.

Click on the previously created OAuth application, and pick up the values of the "Application Id" and "Secret" fields.

Click on the "Summary" tab in the developer console of your OAuth application, and pick up the values of the "Client ID" and "Client Secret" fields.

Click on the "Summary" tab in the developer console of your OAuth application, and pick up the values of the "Client ID" and "Client Secret" fields.

For OIDC providers, you have first to define a customized OIDC provider by clicking on the "+" (add new OIDC provider) button of the "OIDC" cartridge. Use a simple but expressive lowercase provider ID (eg. amazon, yahoo, diod...).

Then, you must find out the OAuth2.0 authorize endpoint and token endpoint implemented by your OIDC provider (these can be found in the provider technical documentation or at the OIDC discovery endpoint of your provider, which should look like https://my.provider.com/.well-known/openid-configuration) and fill the corresponding fields on the Webcom developer console. Note that these fields must be complete URLs (eg. https://my.provider.com/oauth/authorize).

Optionally, you can also specify the user-info endpoint, if your provider implements one. When specified, it makes the Webcom back end retrieve a generally richer profile for the authenticated user (which can be accessed within the resulting authentication state).

Finally, like with any other OAuth2.0 provider, you must fill in the client ID and client Secret fields with the corresponding values of your OAuth application. See the technical documentation of your OIDC provider to know where to find them.

  • Orange Connect: You will receive the client ID and client Secret of your OAuth application in response to the previously created AVISO task.
  • Orange Employees: Click on the "Summary" tab in the developer console of your OAuth application, and pick up the values of the "Client ID" and "Client Secret" fields.

Finally, you have to fill in the “authorized domains” cartridge with the domains from which your Webcom application is allowed to invoke the OAuth2.0 authentication delegation API of Webcom. These domains are divided into 2 parts:

  • the web domains, which constraint the hosts from which a web app is allowed to authenticate within your Webcom application,
  • the Android apps, which constraint the Android application id of the Android apps that are allowed to authenticate within your Webcom application.

iOS apps require the web domain webcom.orange.com to be authorized. Their application id are currently not controlled, so that any iOS app can authenticate on your Webcom application whatever its origin.

By default, no Android app is authorized and only 127.0.0.1 and localhost web domains are allowed for debug purposes. Don't forget to add your mobile apps id and the actual web domain(s) of your application servers before running in production.

Login with an OAuth2.0 provider

Once your OAuth application is properly configured with a given OAuth2.0 provider, you can use the following snippet in your Webcom application to sign a user in (replace “<your-app>” with your actual application identifier). If the identity used to sign in is not bound to any Webcom account, then a new account is automatically created and the identity is bound to it (see Signing up using third-party login).

var ref = new Webcom("<your-app>");
// Sign in (uncomment the appropriate OAuth2.0 provider)
ref.authWithOAuth('facebook')
    .then(auth => console.log("Authentication succeeded", auth))
    .catch(error => {
        if (error) {
          switch (error.code) {
            case "UNAUTHORIZED_REQUEST_ORIGIN":
              console.log("The domain of the application page is not properly registered in the Webcom developer console.");
              break;
            case "PROVIDER_DISABLED":
              console.log("The OAuth2 login method is disabled for the requester provider in the application.");
              break;
            default:
              console.log("An unexpected error occurs, please retry and contact your administrator.", error);
          }
        } else {
          console.log("Authentication succeeded", auth);
        }
    });
//ref.authWithOAuth('google', ...);
//ref.authWithOAuth('apple', ...);
//ref.authWithOAuth('github', ...);
//ref.authWithOAuth('gitlab', ...);
//ref.authWithOAuth('orange', ...);
//ref.authWithOAuth('diod', ...); // Orange Connect
//ref.authWithOAuth('employee', ...); // Orange Employees
//ref.authWithOAuth('mobileconnectOFR', ...); // Mobile Connect Orange France
//ref.authWithOAuth('mobileconnectOES', ...); // Mobile Connect Orange Spain
//ref.authWithOAuth('mobileconnectOJO', ...); // Mobile Connect Orange Jordan
//ref.authWithOAuth('mobileconnectOMG', ...); // Mobile Connect Orange Madagascar
//ref.authWithOAuth('mobileconnectOMA', ...); // Mobile Connect Orange Morocco
//ref.authWithOAuth('mobileconnectOCI', ...); // Mobile Connect Orange Ivory Coast
//ref.authWithOAuth('mobileconnectOEG', ...); // Mobile Connect Orange Egypt
//ref.authWithOAuth('mobileconnectOCD', ...); // Mobile Connect Orange Congo
//ref.authWithOAuth('mobileconnectOBW', ...); // Mobile Connect Orange Botswana
//ref.authWithOAuth('mobileconnectOGN', ...); // Mobile Connect Orange Guinea Conakry
//ref.authWithOAuth('mobileconnectOTN', ...); // Mobile Connect Orange Tunisia
//ref.authWithOAuth('mobileconnectOSN', ...); // Mobile Connect Orange Senegal
//ref.authWithOAuth('mobileconnectOGW', ...); // Mobile Connect Orange Guinea Bissau
//ref.authWithOAuth('mobileconnectOCM', ...); // Mobile Connect Orange Cameroon
//ref.authWithOAuth('mobileconnectOLR', ...); // Mobile Connect Orange Liberia
//ref.authWithOAuth('mobileconnectOML', ...); // Mobile Connect Orange Mali
//ref.authWithOAuth('mobileconnectONE', ...); // Mobile Connect Orange Niger
//ref.authWithOAuth('mobileconnectOBF', ...); // Mobile Connect Orange Burkina Faso
//ref.authWithOAuth('oidc.<provider-identifier>', ...); // OIDC providers

The authWithOAuth method takes the name of the OAuth provider as first parameter. Possible values are : facebook, google, apple, orange, diod (Orange Connect), employee (Orange Employees), mobileconnectOXX (Mobile Connect Orange, replace XX with the targeted country code), github or gitlab. For OIDC providers, the name equals "oidc." plus the provider identifier assigned in the Webcom developer console.
Also, the method admits an optional JSON structure with the following attributes (see Reference):

  • mode (string, optional, defaults to "popup"): authentication mode, among "redirect" (the authorization call-flow to the OAuth2.0 provider is invoked from the current window), "popup" (from a pop-up window) or "code" (no authorization call-flow is played).
  • scope (string, optional, defaults to ""): OAuth2.0 scope used during the authorization call-flow. If not set, an appropriate value is used, which asks the end user for the minimal required grant (see default scope). The allowed values depend on the OAuth2.0 providers, you have to consult their developer documentation for more details.

The auth parameter returned by the promise is a JSON object representing the signed in identity, which directly feeds the current authentication state. The following properties are specialized this way:

Property Type Description
provider string Equals "facebook", "google", "apple", "github", "gitlab", "orange", "diod", "employee", "mobileconnect" or "oidc.<your-provider-name>" (lowercase).
Note that all Mobile Connect providers receive the same identifier, namely mobileconnect.
providerUid string The internal identifier of the authenticated end user used by the OAuth2.0 provider.
providerProfile object (optional) An OAuth2.0 provider-specific structure providing some information about the authenticated end user. It generally includes her/his name and email address.
displayName string (optional) A human-readable description of the authenticated end user extracted from the previous profile data. It can be missing if no description can be found.
extra object A list of values returned by the underlying OAuth2.0 call-flow, including at least the access token got from the provider, which may be further used by your application to invoke some provider's APIs. Note that this property is not saved into the authentication state.
try{
    Webcom ref = new Webcom(new WebcomApp("<your-app>"));
    // OAuth listener definition
    final OnOAuth listener = new OnAuthWithOAuth() {
        @Override
        public void onCancel( WebcomError error) {
            Log.d(TAG, "User cancels authentication");
        }
        @Override
        public void onComplete(AuthResponse response) {
            if (response == null) Log.d(TAG, "Logged out!")
            else Log.d(TAG, "Logged in: " + response.getIdentity().getDisplayName());
        }
        @Override
        public void onError(WebcomError error) {
            Log.e(TAG, "Authentication error: " + error.getMessage());
        }
    };
    // Sign in (uncomment the appropriate OAuth2.0 provider)
    ref.authWithOAuth(context, "orange", listener);
    //ref.authWithOAuth(context, "google", listener);
    //ref.authWithOAuth(context, "facebook", listener);
    //ref.authWithOAuth(context, "apple", listener);
    //ref.authWithOAuth(context, "github", listener);
    //ref.authWithOAuth(context, "gitlab", listener);
    //ref.authWithOAuth(context, "diod", listener); // Orange Connect
    //ref.authWithOAuth(context, "employee", listener); // Orange Employees
    //ref.authWithOAuth(context, "mobileconnectOFR", listener); // Mobile Connect Orange France
    //ref.authWithOAuth(context, "mobileconnectOES", listener); // Mobile Connect Orange Spain
    //ref.authWithOAuth(context, "mobileconnectOJO", listener); // Mobile Connect Orange Jordan
    //ref.authWithOAuth(context, "mobileconnectOMG", listener); // Mobile Connect Orange Madagascar
    //ref.authWithOAuth(context, "mobileconnectOMA", listener); // Mobile Connect Orange Morocco    
    //ref.authWithOAuth(context, "mobileconnectOCI", listener); // Mobile Connect Orange Ivory Coast
    //ref.authWithOAuth(context, "mobileconnectOEG", listener); // Mobile Connect Orange Egypt
    //ref.authWithOAuth(context, "mobileconnectOCD", listener); // Mobile Connect Orange Congo
    //ref.authWithOAuth(context, "mobileconnectOBW", listener); // Mobile Connect Orange Botswana
    //ref.authWithOAuth(context, "mobileconnectOGN", listener); // Mobile Connect Orange Guinea Conakry
    //ref.authWithOAuth(context, "mobileconnectOTN", listener); // Mobile Connect Orange Tunisia
    //ref.authWithOAuth(context, "mobileconnectOSN", listener); // Mobile Connect Orange Senegal
    //ref.authWithOAuth(context, "mobileconnectOGW", listener); // Mobile Connect Orange Guinea Bissau
    //ref.authWithOAuth(context, "mobileconnectOCM", listener); // Mobile Connect Orange Cameroon
    //ref.authWithOAuth(context, "mobileconnectOLR", listener); // Mobile Connect Orange Liberia
    //ref.authWithOAuth(context, "mobileconnectOML", listener); // Mobile Connect Orange Mali
    //ref.authWithOAuth(context, "mobileconnectONE", listener); // Mobile Connect Orange Niger
    //ref.authWithOAuth(context, "mobileconnectOBF", listener); // Mobile Connect Orange Burkina Faso
    //ref.authWithOAuth(context, "oidc.<provider-identifier>", listener); // OIDC providers
} catch (Exception e) {
    Log.e(TAG, e.getMessage(), e);
}    

The authWithOAuth method takes an activity context as first argument. This context is used by the SDK for opening a Web view displaying the authentication page of the targeted provider.
The second argument is the name of the OAuth provider. Possible values are : "facebook", "google", "apple", "orange", "diod" (Orange Connect), "employee" (Orange Employees), "mobileconnectOXX" (Mobile Connect Orange, replace XX with the targeted country code), "github" or "gitlab". For OIDC providers, the name equals "oidc." plus the provider identifier assigned in the Webcom developer console.
The last argument is a listener in charge of handling events from authentication.

Authentication events can be :

  • onCancel: when the user cancels the authentication (typically closes the authentication view by clicking the "back" button).
  • onComplete: when the user successfully logs in.
  • onError: when the authentication fails.

See the API reference for more details.

// Instantiate an authentication method (uncomment the line corresponding to the appropriate OAuth 2.0 provider):
let oAuth2Method = AuthenticationMethodOAuth2(provider: .orangeFrance, presentingViewController: self)
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .google, presentingViewController: self)
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .facebook, presentingViewController: self)
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .apple, presentingViewController: self)
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .gitHub, presentingViewController: self)
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .gitLab, presentingViewController: self)
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .orangeConnect, presentingViewController: self)
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .orangeEmployees, presentingViewController: self)
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .orangeMobileConnect(countryCode: "FR"), presentingViewController: self) // France
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .orangeMobileConnect(countryCode: "ES"), presentingViewController: self) // Spain
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .orangeMobileConnect(countryCode: "JO"), presentingViewController: self) // Jordan
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .orangeMobileConnect(countryCode: "MG"), presentingViewController: self) // Madagascar
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .orangeMobileConnect(countryCode: "MA"), presentingViewController: self) // Morocco
// let oAuth2Method = AuthenticationMethodOAuth2(provider: .openIDConnect(identifier: "<provider-identifier>"), presentingViewController: self)

// Process authentication:
let authenticationService = Webcom.defaultApplication.authenticationService
authenticationService.authenticate(with: oAuth2Method) { result in
    switch result {
    case let .success(details):
        print("Logged in:", details.displayName ?? details.uid)
    case let .failure(error):
        if error.code == .sdk(.canceledByUser) {
            print("User cancels authentication")
        } else {
          print("Authentication error:", error.message ?? "(unknown)")
        }
    }
}

To authenticate, you must first instantiate an authentication method. For OAuth 2.0, the initializer needs two arguments:

  • the authentication provider to use,
  • the view controller on which present the view controller in charge of the delegated authentication.

Then, you must call the authenticate() method of the AuthenticationService instance of the application.

That methods take a completion handler argument. In case of success, it is called with the authenticated user details. In case of error (including cancellation), it is called with a WebcomError value indicating the reason of the failure.

Default scope used for each provider

Here is the default scope used with the authWithOAuth method when no scope parameter is specified. When you need a specific scope, don't forget to keep the default value appended to it.

"public_profile,email"

"email profile"

"email name"

"openid"

"openid"

"openid profile_limited"

"openid"

"openid"

"openid"