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.

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

The schema of the redirect url should be http://localhost/*.

Xamarin

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

Configuring Keycloak

  1. Expand the Identity Management Service by clicking the > icon.

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

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

  4. Open Clients from the menu.

  5. Open your client. 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.

  6. Add <schema>:/callback to Valid Redirect URIs.

  7. Add <schema> to Web Origins.

  8. Save your changes.

You must create a new user account before you can log into the Showcase App. To create a new user, follow the steps here and to setup a new users credentials, follow the steps here.

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

Cordova

Locate this file in your application project and import it using require.

const aerogearConfig = require("./mobile-services.json");

Alternatively you can create a JavaScript object and use directly:

const aerogearConfig = /* Paste here the contents of the clipboard */;
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
    
    let 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
  4. For iOS run:

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

Initializing the SDK

Android
  1. Retrieve the auth service:

    AuthService authService = MobileCore.getInstance().getService(AuthService.class);
  2. 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();
  3. Before the auth service can be used init must be invoked once in an app

    authService.init(context, 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 (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);