Configuring the Service

The following section will guide you through configuring the schema of the redirect url and web origin for a client in Keycloak. This is required to enable OpenID authentication. For an explanation of these terms, see Keycloak Documentation.

Choose the schema of a redirect url

Android

It is recommended to use the package name of the Android app as the schema of the redirect url to avoid conflicts. (e.g. com.aerogear.androidshowcase)

iOS

It is recommended to use the Bundle Identifier of the iOS app as the schema of the redirect url. (e.g. org.aerogear.ios-showcase-template)

Cordova

Redirect url is http://localhost/*, without :/callback. Web Origin is http://localhost/*.

Xamarin

Depending on the platform, set the redirect as described in either the Android or the iOS tab.

Configuring Keycloak

  1. Log into the OpenShift console and navigate to the Project Overview.

  2. Navigate to the Mobile Client screen.

  3. Select the Mobile Services tab.

  4. If a binding to the Identity Management service is in progress, a spinning icon is displayed to the right of the Identity Management entry. Wait for the binding process to complete.

  5. If the Keycloak Realm URL URL is not visible, expand the Identity Management Service by clicking the > icon.

  6. Click on the Keycloak Realm URL link to open the Keycloak Administration Console.

  7. Log in to the Administration console using the credentials you specified at Provisioning (defaults to admin:admin)

  8. Select Clients from the left navigation menu.

  9. Select your client from the list of clients. The name of your client is derived from the name of the Mobile Client, the name of the mobile development platform and the client type, for example myapp-android-public.

  10. Add <schema>:/callback as an additional entry to Valid Redirect URIs. See Choose the schema of a redirect url to determine the value for <schema>.

  11. Add <schema> as an additional entry to Web Origins. See Choose the schema of a redirect url to determine the value for <schema>.

  12. Save your changes.

  13. Create a new user account as described in Creating a New User.

  14. Set up credentials for the new user as described in User Credentials.

Downloading the Mobile Services Configuration File

  1. Navigate to your project in OpenShift.

  2. On the Overview screen, expand your Mobile Client to view the CLIENT INFO.

  3. Copy the configuration to your clipboard.

  4. Save the contents of the clipboard to a new file called mobile-services.json.

    The mobile-services.json file is the link between your provisioned services on OpenShift and the mobile app you are developing. This file provides all required configuration to initialise the various SDKs and get them hooked up/connected to the back-end services.
  5. Follow the next specific additional instructions depending on your platform:

Android

Locate this file at the following location in your application project:

app/src/main/assets/mobile-services.json

iOS

Locate this file at the following location in your application project:

<app directory>/mobile-services.json

Make sure this file is visible in Xcode, add the file if necessary.
Cordova

Locate this file at the following location in your application project:

src/mobile-services.json

Xamarin

Locate this file at the following location in your application project:

Resources/mobile-services.json

Setting up Identity Management service SDK

This section will help you to set up the Identity Management service SDK in your App.

Importing the libraries

Android
  1. Add the following dependency in your app’s build.gradle:

    dependencies {
        implementation "org.aerogear:android-auth:1.0.0"
    }
iOS
  1. Add the dependency to your Podfile:

    target '[TARGET NAME]' do
        pod 'AGSAuth', '1.0.0'
    end
  2. Update the dependencies:

    $ pod install
  3. Import and instantiate AGSAuth to start using the SDK:

    import AGSAuth
    
    auth = AGSAuth()
Cordova

Install the AeroGear Auth package from NPM:

$ npm install @aerogear/auth
Xamarin
  1. Install NuGet.

  2. Install the AeroGear Core package:

    dotnet add package AeroGear.Mobile.Core --version 1.0.0
  3. For Android run:

    dotnet add package AeroGear.Mobile.Core.Platform.Android --version 1.0.0
    dotnet add package AeroGear.Mobile.Auth.Platform.Android --version 1.0.0
  4. For iOS run:

    dotnet add package AeroGear.Mobile.Core.Platform.iOS --version 1.0.0
    dotnet add package AeroGear.Mobile.Auth.Platform.iOS --version 1.0.0

Initializing the SDK

Android
  1. Specify the redirect URL. It is recommended to use the package name of your app.

    AuthServiceConfiguration authServiceConfig = new AuthServiceConfiguration
        .AuthConfigurationBuilder()
        .withRedirectUri("org.aerogear.mobile.example:/callback")
        .build();
  2. Create the auth service:

    AuthService authService = new AuthService(authServiceConfig);
iOS

Set your custom configuration to the auth service instance, making sure the redirect URL matches the App’s Bundle Id.

// create the authentication config
let authenticationConfig = AuthenticationConfig(redirectURL: "org.aerogear.mobile.example:/callback")
try! AgsAuth.instance.configure(authConfig: authenticationConfig, useExternalUserAgent: false)
Cordova

Import and initialize Auth:

const Auth = require('@aerogear/auth').Auth;

const authService = new Auth();
const initOptions = { onLoad: "login-required" };

authService.init(initOptions)
    .then(() => {
        // successful init & authentication
    })
    .catch((err) => {
        // initialization error
    });

You can pass login-required or check-sso to the init function. login-required will authenticate the client if the user is logged in to Keycloak or display the login page if not. check-sso will only authenticate the client if the user is already logged in. If the user is not logged in the browser will be redirected back to the application and remain unauthenticated. By default, the check-sso option is used.

Initialization will also perform authentication
Xamarin
  1. Create an intent filter for the net.openid.appauth.RedirectUriReceiverActivity activity. This step is required for Xamarin Android and allows the login browser to redirect back to your App. Add this to your AndroidManifest.xml:

    <activity android:name="net.openid.appauth.RedirectUriReceiverActivity" android:exported="true"  android:icon="@mipmap/ic_launcher" android:roundIcon="@mipmap/ic_launcher_round">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="org.aerogear.mobile.example" />
        </intent-filter>
    </activity>
  2. Initialize the Auth module

    1. For an Android app (MainActivity.cs):

      var app = new App();
      MobileCoreAndroid.Init(app.GetType().Assembly,ApplicationContext);
      var authService = AuthService.InitializeService();
      var authConfig = AuthenticationConfig.Builder.RedirectUri("org.aerogear.mobile.example:/callback").Build();
      authService.Configure(authConfig);
      For Android an Intent filter should be configured with the callback URL specified in AuthenticateOptions in the App’s AndroidManifest.xml. See the example app.
    2. For an iOS app (FinishedLaunching method of AppDelegate.cs):

      var app = new App();
      MobileCore core = MobileCoreIOS.Init(app.GetType().Assembly);
      var authService = AuthService.InitializeService();
      var authConfig = AuthenticationConfig.Builder.RedirectUri("org.aerogear.mobile.example:/callback").Build();
      authService.Configure(authConfig);