OMH Auth Client Library

Overview

The OMH Auth Client Library simplifies authentication integration for Android developers across devices, supporting both Google Mobile Services (GMS) and non-GMS configurations. With a unified interface, it enables easy incorporation of Google Sign-in and other third-party authentication providers without maintaining separate codebases.

This README serves as a valuable learning resource, providing step-by-step instructions for setting up an Android Studio project and effectively implementing the OMH Auth Client Library. Whether you are new to Android development or an experienced programmer, this guide equips you with the knowledge to seamlessly integrate authentication features into your applications. For a broader understanding of OMH's philosophy and comprehensive capabilities, visit the official website at https://www.openmobilehub.com.

A single codebase, running seamlessly on any device

For instance, the following screenshots showcase multiple devices with Android, both with GMS and Non-GMS. The same app works without changing a single line of code, supporting multiple auth provider implementations.

Non-GMS Pixel 6	GMS Pixel 6

Getting started

This section describes how to setup an Android Studio project to use the OMH Auth SDK for Android. For greater ease, a base code will be used within the repository.

Note: To quickly run a full-featured app with all OMH Auth functionality, refer to the Sample App section and follow the provided steps.

Set up the development environment

Android Studio is required. If you haven't already done so, download and install it.
Ensure that you are using the Android Gradle plugin version 7.0 or later in Android Studio.

Clone the repository

Go to the branch "starter-code". The easiest way is cloning the repository.

Open Terminal.

Type git clone, and then paste the URL:

git clone --branch code-starter https://github.com/openmobilehub/omh-auth.git

Press "Enter" to create your local clone.

You can always check what the final result should be in the module sample-app in the main or develop branches.

Set up your Google Cloud project for applications with Google Services (Google Auth)

To access Google APIs, generate a unique client_id for your app in the Google API Console. Add the client_id to your app's code and complete the required Cloud Console setup steps:

Steps

Go to the Google Cloud Console and open the project selector page.
Click on "Create Project" to start creating a new Cloud project.
Go to the Credentials page.
On the Credentials page, click on "Create credentials" and choose "OAuth Client ID".
In the "Application Type" option, select "Android".
Set your application package name (Use "com.omh.android.auth.sample" if you are following the starter-code)
Update the debug/release SHA-1 certificate fingerprint for Android's Client ID.

Note: The debug build is automatically signed with the debug keystore. Obtain the certificate fingerprint from it by following the guidelines in the official Google Developers documentation: "Using keytool on the certificate".
In the OAuth consent screen add the test users that you will be using for QA and development. Without this step you won't be able to access the application while it's in testing mode.
You're all set!

Add the Client ID to your app

You should not check your Client ID into your version control system, so it is recommended storing it in the local.properties file, which is located in the root directory of your project. For more information about the local.properties file, see Gradle properties files.

Open the local.properties in your project level directory, and then add the following code. Replace YOUR_CLIENT_ID with your API key. CLIENT_ID=YOUR_CLIENT_ID
Save the fileand sync your project with Gradle.

Gradle configuration

To incorporate OMH Auth into your project, you have two options: utilize the OMH Core Plugin or directly include the OMH Client libraries dependencies. This plugin simplifies the addition of Gradle dependencies, allowing you to effortlessly manage and include the necessary dependencies for seamless integration.

Add OMH Core plugin

The subsequent instructions will outline the necessary steps for including the OMH Core Plugin as a Gradle dependency.

In your "auth-starter-sample" module-level build.gradle under the plugins element add the plugin id.
```
plugins {
   ...
   id("com.openmobilehub.android.omh-core")
}
```
Save the file and sync Project with Gradle Files.

Configure the OMH Core plugin

In your auth-starter-sample module-level build.gradle file add the following code at the end of the file.

omhConfig {
   bundle("singleBuild") {
      auth {
         gmsService {
            dependency = "com.openmobilehub.android:auth-api-gms:1.0.1-beta"
         }
         nonGmsService {
            dependency = "com.openmobilehub.android:auth-api-non-gms:1.0.1-beta"
         }
      }
   }
   bundle("gms") {
      auth {
         gmsService {
            dependency = "com.openmobilehub.android:auth-api-gms:1.0.1-beta"
         }
      }
   }
   bundle("nongms") {
      auth {
         nonGmsService {
            dependency = "com.openmobilehub.android:auth-api-non-gms:1.0.1-beta"
         }
      }
   }
}

NOTE: This section covers concepts about the core plugin

In your "auth-starter-sample" module-level build.gradle file is required to configure the omhConfig. The omhConfig definition is used to extend the existing Android Studio variants in the core plugin. For more details omhConfig see OMH Core.

Basic configuration

In this step, you will define the OMH Core Plugin bundles to generate multiple build variants with specific suffixes as their names. For example, if your project has release and debug variants with singleBuild, gms, and nonGms OMH bundles, the following build variants will be generated:

releaseSingleBuild, releaseGms, and releaseNonGms
debugSingleBuild, debugGms, and debugNonGms

Variant singleBuild

- Define the `Service`. In this example is auth.
- Define the `ServiceDetails`. In this example are `gmsService` and `nonGmsService`.
- Define the dependency and the path. In this example
  are `com.openmobilehub.android:auth-api-gms:1.0.1-beta"`
  and `com.openmobilehub.android:auth-api-non-gms:1.0.1-beta`.

Note: It's important to observe how a single build encompasses both GMS (Google MobileServices) and Non-GMS configurations.

Variant gms

- Define the `Service`. In this example is auth.
- Define the `ServiceDetails` . In this example is `gmsService`.
- Define the dependency and the path. In this example
  is `com.openmobilehub.android:auth-api-gms:1.0.1-beta"`.

Note: gms build covers only GMS (Google Mobile Services).

Variant nongms

- Define the `Service`. In this example is auth.
- Define the `ServiceDetails` . In this example is `nonGmsService`.
- Define the dependency and the path. In this example
  is `com.openmobilehub.android:auth-api-non-gms:1.0.1-beta`.

Note: nongms build covers only Non-GMS configurations.

Save and sync Project with Gradle Files.
Rebuild the project to ensure the availability of BuildConfig.AUTH_GMS_PATH and BuildConfig.AUTH_NON_GMS_PATH variables.
Now you can select a build variant. To change the build variant Android Studio uses, do one of the following:
- Select "Build" > "Select Build Variant..." in the menu.
- Select "View" > "Tool Windows" > "Build Variants" in the menu.
- Click the "Build Variants" tab on the tool window bar.
You can select any of the 3 variants for the :auth-starter-sample:
- "singleBuild" variant builds for GMS (Google Mobile Services) and Non-GMS devices without changes to the code.(Recommended)
- "gms" variant builds for devices that has GMS (Google Mobile Services).
- "nongms" variant builds for devices that doesn't have GMS (Google Mobile Services).

In the SingletonModule.kt file in the :auth-starter-sample module add the following code to provide the OMH Auth Client.

val omhAuthProvider = OmhAuthProvider.Builder()
    .addNonGmsPath(BuildConfig.AUTH_NON_GMS_PATH)
    .addGmsPath(BuildConfig.AUTH_GMS_PATH)
    .build()
return omhAuthProvider.provideAuthClient(
    scopes = listOf("openid", "email", "profile"),
    clientId = BuildConfig.CLIENT_ID,
    context = context
)

Note: we'd recommend to store the client as a singleton with your preferred dependency injection library as this will be your only gateway to the OMH Auth SDK and it doesn't change in runtime at all.

Adding Auth to your app.

First and foremost, the main interface that you'll be interacting with is called OmhAuthClient. In contains all your basic authentication functionalities like login, sign out and check for a user profile.

Check for an existing user

The snippet below shows how to check if there's a signed in user already in your application. If no one has logged in yet, then it will return a null value. A successful fetch will return an object of the class OmhUserProfile. In the MainActivity.kt, add the following code to the selectStartDestination() function:

omhAuthClient.getUser() == null

Login

If no user is found, then we should request a login intent which will redirect the user to the provider's auth screen, be it the Google SignIn UI or a custom tab that redirects the user to Google's Auth page. This should be used to start an activity for result. In the LoginFragment.kt, add the following code to the handleLoginResult(result: ActivityResult):

try {
     omhAuthClient.getAccountFromIntent(result.data)
     navigateToLoggedIn()
} catch (exception: OmhAuthException) {
     handleException(exception)
}

In the LoginFragment.kt, add the following code to the startLogin function:

// This will trigger the login flow.
val loginIntent = omhAuthClient.getLoginIntent()
loginLauncher.launch(loginIntent)

If the returned result contains the account, then you can continue to the logged in activity of your application.

Sign out

To sign-out the SDK provides a straightforward functionality that returns an OmhTask. This is the interface to interact with async functionalities and subscribe to the success or error results. To cancel a running OMH task a cancellable token is provided after the execute() function is called. This can be stored in the CancellableCollector class similar to the CompositeDisposable in RxJava. The sign-out action will removes any and all relevant data to the user from the application storage. In the LoggedInFragment.kt, add the following code to the logout function:

val cancellable = omhAuthClient.signOut()
    .addOnSuccess { navigateToLogin() }
    .addOnFailure(::showErrorDialog)
    .execute()
cancellableCollector.addCancellable(cancellable)

Note: you can cancel all emitted cancellables within the collector running

cancellableCollector.clear()

Revoke token

The SDK also provides a way to revoke the access token provided to the application. This works similar to the sign-out functionality but on top of clearing all local data, this also makes a request to the auth provider to revoke the token from the server. In the LoggedInFragment.kt, add the following code to the revokeToken function:

val cancellable = omhAuthClient.revokeToken()
    .addOnFailure(::showErrorDialog)
    .addOnSuccess { navigateToLogin() }
    .execute()
cancellableCollector.addCancellable(cancellable)

Sample App

This repository includes a auth-sample that demonstrates the functionality of the OMH Auth Client Library. By cloning the repo and executing the app, you can explore the various features offered by the library. However, if you prefer a step-by-step approach to learn the SDK from scratch, we recommend following the detailed Getting Started guide provided in this repository. The guide will walk you through the implementation process and help you integrate the OMH Auth Client Library into your projects effectively.

Note: Before running the sample application, make sure to follow the steps in Setup your Google Cloud project for application with Google Services to configure your Google Cloud project.

Documentation

See example and check the full documentation and add custom implementation at our Wiki.

Additionally for more information about the OMH Auth functions, Docs.

Provider Implementations / Plugins

OMH Auth SDK is open-source, promoting community collaboration and plugin support from other auth providers to enhance capabilities and expand supported auth services. More details can be found at the wiki.

Contributing

Please contribute! We will gladly review any pull requests. Make sure to read the CONTRIBUTING page first though.

License

Copyright 2023 Open Mobile Hub
 
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

OMH Auth Client Library

Overview

A single codebase, running seamlessly on any device

Getting started

Set up the development environment

Clone the repository

Set up your Google Cloud project for applications with Google Services (Google Auth)

Steps

Add the Client ID to your app

Gradle configuration

Add OMH Core plugin

Configure the OMH Core plugin

Basic configuration

Variant singleBuild

Variant gms

Variant nongms

Adding Auth to your app.

Check for an existing user

Login

Sign out

Revoke token

Sample App

Documentation

Provider Implementations / Plugins

Contributing

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

OMH Auth Client Library

Overview

A single codebase, running seamlessly on any device

Getting started

Set up the development environment

Clone the repository

Set up your Google Cloud project for applications with Google Services (Google Auth)

Steps

Add the Client ID to your app

Gradle configuration

Add OMH Core plugin

Configure the OMH Core plugin

Basic configuration

Variant singleBuild

Variant gms

Variant nongms

Adding Auth to your app.

Check for an existing user

Login

Sign out

Revoke token

Sample App

Documentation

Provider Implementations / Plugins

Contributing

License