Using the Identity Management Mobile Service

The Identity Management service allows you to add authentication and authorization to your mobile app.

  • Secure your mobile app using the industry standard OpenID Connect protocol

  • Add access control to your app based on user’s group membership

  • Easily implement SSO, multi-factor authentication and Social Login support

  • Back-end support for identity brokering and user federation

Identity Management Service terminology

This section describes terminology that is associated with Identity Management.

Identity Management Terminology
SSO

Single Sign On, the ability to share a login between multiple services

OpenID Connect

A standard for providing identity on top of OAuth 2.0

Keycloak

Red Hat’s implementation of SSO and OpenID used as the identity provider

Client ID

Is the client identifier for OpenID Connect requests, a simple alpha-numeric string

User Attributes

Additional properties for user accounts (besides name and email) managed by Keycloak

Prerequisites

Setting Up the Identity Management Service

Provisioning the Identity Management Service

This section describes how to set up the IDM Mobile Service.

Prerequisites

  • You understand identity management, and have a mobile app you want to protect.

  • You have logged into the OpenShift console and the Mobile Developer Console.

Procedure

  1. Log into the OpenShift console.

  2. Create a new project or choose an existing project.

  3. Click Add to Project and choose Browse Catalog from the options.

    You can filter the catalog items to only show mobile specific items by clicking the Mobile tab.

  4. Click Services and choose the service.

    catalog mobile services

  5. Follow the wizard for provisioning that service.

    If prompted to Create a Binding, choose Do not bind at this time

    When provisioning an Identity Management service, you are prompted to set the following configuration:

    • Keycloak admin username: Username for Keycloak administration

    • Keycloak admin password: Password for the Keycloak admin user

    • Name of the Keycloak realm: Name of the Keycloak realm. (defaults to current namespace)

      A realm manages a set of users, credentials, roles, and groups. A user belongs to and logs into a realm. Realms are isolated from one another and can only manage and authenticate the users that they control.

    • Connect to an existing shared service: Select if you want to use an existing service and you have the URL and credentials to use that service.

    • URL of the shared service: Enter a value if you want to use an existing shared service.

Once the wizard steps are completed, navigate to the Project Overview in OpenShift to see the newly provisioned service. Provisioning a service may take some time.

Binding a Mobile App with the Identity Management Service

To use mobile services, you must represent your mobile app in Mobile Developer Console, and that app must be associated with the mobile service. This association is called binding and it is necessary for your mobile app to use that service.

This section describes how to set up the Identity Management service.

Prerequisites

  • You have created a Mobile App.

Procedure

To bind a Mobile App with a mobile service:

  1. Launch Mobile Developer Console.

  2. Click on the Mobile App on the Overview screen.

  3. Navigate to Mobile Services tab.

    mobile clients services all unbound
    It is possible to bind a Mobile App with a mobile service in the OpenShift console, however such bindings are not valid for the purposes of this procedure.

  4. Click Bind to App for Identity Management.

  5. Fill out the binding parameters required by the Identity Management Service.

    mobile clients services idm parameters
    Use Public when binding a Mobile App to a Identity Management. When binding mobile services to each other, use Bearer.

The Identity Management service will now be expandable, details about the service can be viewed.

mobile clients services all idm provisioned

Configuring the Identity Management Service

This section guides you through configuring 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.

Prerequisites
Procedure

  1. Log into the Mobile Developer Console and navigate to the Mobile App screen.

  2. Select the Mobile Services tab.

  3. 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.

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

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

  6. Log in to the Administration console using the credentials you specified when Provisioning the service (defaults to admin/admin).

  7. Select Clients from the left navigation menu.

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

  9. Add an additional entry to Valid Redirect URIs.

    • Android

    • iOS

    • Cordova

    • Xamarin

    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)

    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)

    Set the additional value to http://localhost*.

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

  10. Add an additional entry to Web Origins.

    • Android

    • iOS

    • Cordova

    • Xamarin

    Use the package name of the Android app to avoid conflicts. (e.g. com.aerogear.androidshowcase)

    Use the Bundle Identifier of the iOS app. (e.g. org.aerogear.ios-showcase-template)

    Set additional value to http://localhost*.

    Depending on the target platform, set the additional value as described in either the Android or the iOS tab.

  11. Save your changes.

  12. Creating a new user account as described in Creating a New User.

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

Configuring your development environment for the Identity Management Service

Downloading the Configuration File

The mobile-services.json file provides the information for your mobile app to communicate with services. After you change any configuration in the Mobile Developer Console, it is important to update that file in your IDE.

Prerequisites

  • The configuration of your Mobile App in Mobile Developer Console is up-to-date.

  • You have set up your mobile app development environment.

Procedure

  1. Open your Mobile App in Mobile Developer Console.

  2. Copy the mobile-services.json configuration to your clipboard.

  3. 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.

  4. Move mobile-services.json to the following location in your application project:

    • Android

    • iOS

    • Cordova

    • Xamarin

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

    <app directory>/mobile-services.json NOTE: Ensure that mobile-services.json is a member of the project in the Xcode Project Navigator.

    src/mobile-services.json

    Resources/mobile-services.json

Setting up the Identity Management Service SDK

This section helps you to set up the Identity Management service SDK in your App. It describes how to set up and initialize the Identity Management service SDK.

Prerequisites

  • Your local mobile-services.json file is up-to-date.

Procedure

  1. Import the libraries.

    • Android

    • iOS

    • Cordova

    • Xamarin

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

      dependencies {
    implementation "org.aerogear:android-auth:1.0.0"
}

    2. To prevent build errors, add the following in your app’s build.gradle:

      compileOptions {
    sourceCompatibility 1.8
    targetCompatibility 1.8
}

    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()

    1. Add the following code to index.html located in src/ :

      <meta http-equiv="Content-Security-Policy" content="default-src * file: 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *; img-src 'self' data: content:;">

    2. Install the AeroGear Auth package from NPM:

      $ npm install @aerogear/auth

    3. Install cordova-plugin-inappbrowser:

      $ cordova plugin add cordova-plugin-inappbrowser

      Use a JavaScript bundler, for example, browserify so that you can use node modules in Cordova. AeroGear recommends using the require statement rather than import for the the @aerogear/auth module as shown below:

    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

  2. Initialize the SDK.

    • Android

    • iOS

    • Cordova

    • Xamarin

    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);

    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)

    1. Import and initialize Auth.

      const Auth = require('@aerogear/auth').Auth;
const authService = new Auth(app.config);
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 also enables authentication.

    To use self-signed certificates with your Cordova application, complete the following instructions here.

    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);

Adding User Authentication to your Mobile App

Implementing authentication

Prerequisites

  • The mobile-services.json file is up-to-date in your development environment.

Procedure

To implement authentication using the Aerogear SDK:

  • Android

  • iOS

  • Cordova

  • Xamarin

  1. Provide an implementation of Callback which is defined in the Aerogear SDK and used to handle asynchronous results:

    Callback authCallback = new Callback<UserPrincipal>() {
    @Override
    public void onSuccess(UserPrincipal principal) {
        ...
    }

    @Override
    public void onError(Throwable error) {
        ...
    }
};

  2. Use the login method to hand over to the login browser:

    // Build the options object and start the authentication flow
DefaultAuthenticateOptions options = new DefaultAuthenticateOptions(myActivity, LOGIN_RESULT_CODE);

authService.login(options, authCallback);

  3. Override onActivityResult to handle the result from the browser. It’s important to pass the intent back to the Auth service:

    @Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == LOGIN_RESULT_CODE) {
        authService.handleAuthResult(data);
    }
}
    This handler should always invoke handleAuthResult, providing the Intent. This will exchange the temporary tokens returned from login for long-lived tokens and will provide a UserPrincipal which can be used to access a users details. If this is not invoked you will not have access to the UserPrincipal.

  4. The callback provided to login will be invoked.

  1. Use the login method to hand over to the login browser:

    AgsAuth.instance.login(presentingViewController: self, onCompleted: onLoginComplete)

func onLoginComplete(user: User?, err: Error?) {
    if let error = err {
        return
    }

    let currentUser = user
}

  2. Allow your application to handle the redirect in AppDelegate:

    func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey: Any] = [:]) -> Bool {
    do {
        return try AgsAuth.instance.resumeAuth(url: url as URL)
    } catch AgsAuth.Errors.serviceNotConfigured {
        print("AeroGear auth service is not configured")
    } catch {
        fatalError("Unexpected error: \(error).")
    }
    return false
}

Authentication is enabled during initialization as described in the section Setting up the Identity Management Service SDK. To manually redirect to the login screen, use:

authService.login().then(() => {
    // Login success
}).catch(() => {
    // Login error
});;

  1. Use the Authenticate method to hand over to the login browser:

    IAuthService authService = MobileCore.Instance.GetService<IAuthService>();

var authOptions = DependencyService.Get<IAuthenticateOptionsProvider>().GetOptions();
var user = await authService.Authenticate(authOptions);

Refreshing the authentication token

When a user is authenticated, an access token and a refresh token are generated by the authentication server. See the Keycloak documentation for information about configuring the lifespan of these tokens. If the refresh token is still valid, the authentication token can be refreshed even if the authentication token has expired.

Prerequisites

  • A working mobile app that uses authentication with the Identity Management service.

Procedure

To automatically refresh the authenticate token :

  • Android

  • iOS

  • Cordova

  • Xamarin

Retrieve the current user and refresh the access token when possible and required:

UserPrincipal currentUser = authService.currentUser(true);

Retrieve the current user and refresh the access token when possible and required:

do {
    try AgsAuth.instance.currentUser(autoRefresh: true) { (currentUser, error) in
        // If error is nil, currentUser is now refreshed
    }
} catch {
    // An error has occurred trying to reach the authentication server
}

Retrieve the keycloak adapter object and refresh the access token, when possible and required:

authService.extract().updateToken(30).then(() => {
    // Token has been refreshed
});

More information about the keycloak javascript adapter can be found here

Retrieve the current user and refresh, if needed and still possible, its access token:

var authService = MobileCore.Instance.GetService<IAuthService>();
var currentUser = await authService.CurrentUser(true);

Adding Log Out Option to your Mobile App

The following section describes how to perform a logout.

To perform backchannel or federated logouts, you must enable the Backchannel Logout option for the federated identity provider. More information is available in the Keycloak documentation under OICD Identity Providers.
Prerequisites

  • A working mobile app that uses authentication with the Identity Management service.

Procedure

To enable users of the mobile app log out from the service.

  • Android

  • iOS

  • Cordova

  • Xamarin

  1. Retrieve the current user:

    UserPrincipal currentUser = authService.currentUser();

  2. Implement Callback and call logout:

authService.logout(currentUser, new Callback<UserPrincipal>() {
    @Override
    public void onSuccess() {
        // User Logged Out Successfully and local Auth tokens were Deleted
    }

    @Override
    public void onError(Throwable error) {
        // An error occurred during logout
    }
});

  1. Implement the logout callback:

    func onLogoutComplete(_: Error?) {
    // User Logged Out Successfully and local Auth tokens were Deleted
    ...
}

  2. Call logout and pass the callback:

    do {
    try AgsAuth.instance.logout(onCompleted: self.onLogoutComplete)
} catch {
    fatalError("Error logging out: \(error).")
}

Invoke the logout function:

authService.logout().then(() => {
    // User Logged Out Successfully and local Auth tokens were Deleted
});

To logout invoke the Logout method:

var authService = MobileCore.Instance.GetService<IAuthService>();
var result = await authService.Logout(authService.CurrentUser());

Authenticating with a back end service

In a typical scenario, you not only want the user to authenticate on the mobile app, you also want that user to authenticate with a back end service.

Prerequisites

  • A working mobile app that uses authentication with the Identity Management service.

Procedure

  1. Add an additional token:

    Authorization: BEARER Yourtoken

  2. Add code to authenticate with a back end service:

    • Android

    • iOS

    • Cordova

    • Xamarin

    1. Get the AuthHeaderProvider instance provided by the Aerogear SDK:

      authService.getAuthHeaderProvider()

    2. Plug it into your networking layer. When using the okhttp library, this can be added to the list of request interceptors to automatically supply the required tokens:

      MobileCore.getInstance()
          .getHttpLayer()
          .requestHeaderInterceptor()
          .add(authService.getAuthHeaderProvider());

    1. Get the AuthHeaderProvider instance provided by the Aerogear SDK:

      authService.getAuthHeaderProvider()

    2. Plug it into your networking layer.

    The AeroGear Cordova SDK doesn’t provide an HTTP layer, therefore it cannot provide an Auth Header Provider. You must manually attach the Bearer header to your HTTP requests.

    req.setRequestHeader('Accept', 'application/json');
req.setRequestHeader('Authorization', 'Bearer ' + authService.extract().token);

    1. Get the AuthHeaderProvider instance provided by the Aerogear SDK:

      var authHeaderProvider = authService.AuthHeaderProvider;

    2. Plug it into your networking layer.----

Additional resources

Adding Access Control to your Mobile App

Once a UserPrincipal has been retrieved, the roles of the user can be listed and checked. This can be used to perform client side access control, such as hiding UI components related to actions the user doesn’t have permissions to perform. Roles are divided into two types. Resource roles which belong to the client the user has authenticated against, and Realm roles which belong to the realm the client is in.

Prerequisites

  • A working mobile app that uses authentication with the Identity Management service.

Procedure

To add Access Control:

  • Android

  • iOS

  • Cordova

  • Xamarin

  1. Retrieve the authenticated user:

    UserPrincipal currentUser = authService.currentUser();

  2. Use hasRealmRole and hasResourceRole to check for roles:

    boolean hasAdminPermissions = currentUser.hasRealmRole("user_admin");
boolean isModerator = currentUser.hasResourceRole("my_resource", "user_moderator");

  1. Retrieve the authenticated user:

    let currentUser = try AgsAuth.instance.currentUser()

  2. The user roles are available on the authenticated user:

    let clientRoles = currentUser.clientRoles
let realmRoles = currentUser.realmRoles

  3. Use hasRealmRole and hasClientRole to check for roles:

    let hasAdminRole = currentUser.hasRealmRole("admin")
let hasModeratorRole = currentUser.hasClientRole(client: "my_client", role: "moderator")

Get the realm roles from the auth service:

const realmRoles = authService.getRealmRoles();
No function to retrieve the resource roles is currently exported but you can use extract to get a handle to the underlying keycloak-js instance to retrieve the roles from there. Have a look at their documentation here.

  1. Retrieve the authenticated user:

    // auth service is already initialised
var user = MobileCore.Instance.GetService<IAuthService>().CurrentUser();

  2. Use getRoles to retrieve all roles from the user:

    // auth service is already initialised
var roles = user.getRoles();

  3. Use HasRealmRole and HasResourceRole to check for roles:

    bool isAdmin = user.HasRealmRole("user_admin");
bool isModerator = user.HasResourceRole("my_resource", "user_moderator");

Adding SSO to your Mobile App

Using SSO with the Device Browser

The AeroGear mobile SDK uses OpenID Connect Authorization Code Flow to implement SSO using a mobile device browser.

Prerequisites

  • You have completed all steps in Adding Access Control to your Mobile App.

  • Two Mobile Apps bound to the Identity Management service.

  • Two Mobile Apps built and running on the same device that are using the AeroGear SDK Auth module.

Procedure

In the following procedure, the two apps are named Email App and Messaging App. Substitute the appropriate names for your SSO scenario.

  1. Ensure the "Remember Me" option in Keycloak is turned on. In the admin UI click on Realm Settings section on the left hand side, and then click on Login. Turn on Remember Me.

  2. Now that your two apps and Keycloak clients are setup, sign into the Email App with the user you have previously created. You should be redirected to your device browser which should have loaded the Keycloak login page.

  3. Next, enter in your credentials, make sure check the Remember Me option and login. You have now been authenticated on the Email App via the browser.

  4. Finally, try sign into the Messaging App and you should be automatically logged in as you have been previously authenticated in the Email App via the same browser.

Additional resources

With iOS 11 and later, Apple has introduced SFAuthenticationSession for apps to perform SSO, instead of using the system Safari browser and there are known issues with this new feature. Sometimes, the user may have to enter their credentials again, even if they have logged in previously in another app.

Monitoring the Identity Management Service

After the Mobile Metrics Service (includes Grafana for visualization and the Prometheus monitoring system) and Identity Management Service are provisioned, you should be able to see the "Keycloak Metrics" in the list of available dashboards.

Prerequisites

  • The Mobile Metrics Service and Identity Management Service must be provisioned in the same OpenShift project to access data.

Procedure

  1. Navigate to Grafana.

  2. Select Keycloak Metrics.

Additional resources

Dashboard panel descriptions

The Keycloak dashboard consists of several panels which give you an overview of the specific events, such as the number of registered users, memory usage etc.

Below you will find a detailed description of each panel and its values.

Singlestat Panels

Singlestat panels show you the main summary of a single data series.

  • Total Registrations: Total number of registered (non-admin) users. This number comprises all successful registrations made via various providers, e.g. Keycloak, Github, Facebook etc.

  • Total Logins: Total number of successful logins (only non-admin users) over all providers.

  • Total Login Errors: Total number of failed login attempts.

  • Current Memory: The amount of memory currently used by the Identity Management Service

Graph panels

Used to show how certain values change over time, e.g. the number of successful logins.

  • Logins: Overview of the successful logins over time

  • Login Errors: Overview of the failed login attempts over time

  • Memory Usage: The values in this graph represents the following:

    • Used: The amount of memory currently used by the Identity Management Service

    • Commited: The amount of memory that is guaranteed to be available for use (by JVM)

    • Max: The maximum amount of memory that can be used for memory management

Pie Charts

Used to show the distribution of data, e.g. the number of logins per identity provider.

  • Logins Per Provider: Overview of the successful (non-admin) user logins per provider

  • Registrations Per Provider: Overview of the successful (non-admin) user registrations per provider.

Additional resources