Identity Management
Introduction
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
See the Keycloak documentation for more info.
Identity Management Terminology
This section describes terminology that is associated with Identity Management.
- 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
-
You are running OpenShift with Mobile Services as described in Setting up AeroGear Mobile Services on OpenShift.
Setting Up the Identity Management Mobile Service
Provisioning the Identity Management Service
-
Log into the OpenShift console.
-
Create a new project or choose an existing project.
-
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.
-
Click Services and choose the Identity Management service.
-
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 Client with the Identity Management Service
To use mobile services, you must represent your mobile app in OpenShift using a Mobile Client, and that Mobile Client must be associated with the mobile service. This association is called binding and it is necessary for your mobile app to use that service.
To bind a Mobile Client with a mobile service:
Procedure
-
Navigate to the Overview of your OpenShift project.
-
Select the Mobile Client name listed in the Mobile Clients section.
-
Navigate to Mobile Services tab.
-
Click Create Binding and follow the Create Binding wizard to associate the Mobile Client with the Identity Management Service.
-
Fill out the binding parameters required by the Identity Management Service.
Use public
when binding a Mobile Client to a Identity Management. When binding mobile services to each other, usebearer
.
The Identity Management service will now be expandable, details about the service can be viewed.

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.
Configuring Keycloak
-
Log into the OpenShift console and navigate to the Project Overview.
-
Navigate to the Mobile Client screen.
-
Select the Mobile Services tab.
-
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.
-
If the Keycloak Realm URL URL is not visible, expand the Identity Management Service by clicking the > icon.
-
Click on the Keycloak Realm URL link to open the Keycloak Administration Console.
-
Log in to the Administration console using the credentials you specified when Provisioning the service (defaults to admin:admin).
-
Select
Clients
from the left navigation menu. -
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
. -
Add
<schema>:/callback
as an additional entry toValid Redirect URIs
. See Choose the schema of a redirect url to determine the value for<schema>
. -
Add
<schema>
as an additional entry toWeb Origins
. See Choose the schema of a redirect url to determine the value for<schema>
. -
Save your changes.
-
Create a new user account as described in Creating a New User.
-
Set up credentials for the new user as described in User Credentials.
Downloading the Mobile Services Configuration File
-
Navigate to your project in OpenShift.
-
On the Overview screen, expand your Mobile Client to view the CLIENT INFO.
-
Copy the configuration to your clipboard.
-
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. -
Follow the platform-specific instructions:
Adding User Authentication to your Mobile App
This section describes how to perform user authentication for the supported platforms. On authentication a browser window will open and prompt the user for login credentials.
Implementing authentication
The following examples show how to implement authentication using the Aerogear SDK on all the supported platforms.
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. The following code shows how the authentication token can be refreshed automatically:
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. |
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. To achieve this, you must add an additional token:
Authorization: BEARER Yourtoken
SDK also provides number of helpers to build authentication headers that will provide way to refresh it once token is outdated.
Additional Information
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.
Adding Single Sign-On (SSO) to your Mobile App
The Auth SDK uses OpenID Connect Authorization Code Flow to achieve SSO via a mobile device browser.
Prerequisites
-
Two Mobile Clients bound to the Identity Management service
-
Two mobile apps built and running on the same device that are using the AeroGear SDK Auth module
Using SSO with the Device Browser
For this guide, assume that your two apps are called Email App and Messaging App.
-
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.
-
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.
-
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.
-
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.
Known Issues
On iOS 11 and above, Apple has introduced SFAuthenticationSession for apps to perform SSO, instead of using the system Safari browser. However, there are a few known issues with this new feature and sometimes user may have to enter their credentials again in other apps, even if they have already logged in once previously in one of the apps.
Monitoring the Identity Management Service
Prerequisites
-
The Mobile Metrics Service and Identity Management Service must be provisioned in the same OpenShift project to access data.
Overview
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 (navigate to Grafana’s exposed URL → Log in → Home → Select Keycloak Metrics).
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.