d4l-data4life/hc-auth-sdk-kmp

Data4Life Auth SDK

Authorization SDK for communicating with PHDC using OAuth 2.0

Explore the docs »

Report Bug · Request Feature

Table Of Contents

• About The Project
  • Features
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Changelog
• Versioning
• Contributing
• Copyright and License

About The Project

Authorization SDK for communicating with PHDC using OAuth 2.0. For Android it implements RFC 8252 - OAuth 2.0 for Native Apps using AppAuth. Java is supporting the OAuth 2.0 Code Grant using ScribeJava.

Features

• Android: OAuth 2.0 - Native App flow

• Java: OAuth 2.0 - Code Grant flow

Built With

• Kotlin Multiplatform

Getting Started

Instructions how to get software up and running.

Prerequisites

• Android Studio - Chipmunk - 2021.2.1

• Java 11 | Limitations of Java language features and APIs | Desugaring

• Kotlin 1.7.10

• Android 6.0 (API 23) to Android 13 (API 33)

Installation

A step by step series of examples that tell you how to get it running.

Consume GitHub Packages

We use GitHub Packages to distribute the SDK. In order to consume our dependencies you need to generate a GitHub Personal Access Token. Please follow the how to authenticate to GitHub Packages.

NOTICE

You need to have read access to this repository and generate a personal access token with repo and read:packages scope.

Token

The token needs to be made available.

1. Add gpr.user = {GitHub username} and gpr.key = {GitHub Personal Access Token} to your global Gradle properties ~/.gradle/gradle.properties

   gpr.user=github-username
   gpr.key=github-token

2. Or add following environment variables PACKAGE_REGISTRY_USERNAME={GitHub username} and PACKAGE_REGISTRY_TOKEN={GitHub Personal Access Token}

Setup Maven Repository

Add the following maven repository configuration to your root build.gradle:

    allprojects {
        repositories {
            ...
            maven {
                url = URI("https://maven.pkg.github.com/d4l-data4life/hc-auth-sdk-kmp")
                credentials {
                    username = project.findProperty("gpr.user") as String? ?: System.getenv("PACKAGE_REGISTRY_USERNAME")
                    password = project.findProperty("gpr.key") as String? ?: System.getenv("PACKAGE_REGISTRY_TOKEN")
                }
            }
        }
    }

Java

Add following dependencies to your app build.gradle.

dependencies {
    implementation "care.data4life.hc-auth-sdk-kmp:auth-jvm:$version"
}

Android

dependencies {
    implementation "care.data4life.hc-auth-sdk-kmp:auth-android:$version"
}

In case you target Android 11+ and experience a ActivityNotFoundException. This is caused by the changed package visibility in Android 11. Please ensure that the following is part of your merged AndroidManifest.xml. In case not, add the following to your AndroidManifest.xml file:

<manifest>
    <application>
        ...
    </application>

    <queries>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
        </intent>
    </queries>

</manifest>

Usage

The authorization request is started with the following code sample which launches an Custom Tab to present the login screen to the user for authentication.

Intent authIntent = Data4LifeClient.getInstance().getLoginIntent(null);
startActivityForResult(authIntent,requestCode);

Once the user finished, canceled or an error occurred during the browser login, the SDK sends the response to the integrator application in the onActivityResult(…) method.

The authorization results can be the following:

• Activity.RESULT_OK – when the login is successful.

• Activity.RESULT_CANCELED – when the login fails, with additional payload in data, as shown in the example.

To end the login you need to call finishLogin(authData, callback) with the intent received in onActivityResult(…). The callback will indicate if the authorization successfully finished.

@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == GC_AUTH) {
        if (resultCode == RESULT_OK) {
            client.finishLogin(data,callback);
        } else if (data.getExtras() != null) {
            if (data.getExtras().containsKey("error")) {
                Snackbar.make(mRootCL, "Failed to log in to Data4Life", Snackbar.LENGTH_SHORT).show();
            } else if (data.getExtras().containsKey("canceled")) {
                Snackbar.make(mRootCL, "User canceled authorization request", Snackbar.LENGTH_SHORT).show();
            }
        }
    }
}

Roadmap

This project is work in progress. We are working on adding more functionality, guidelines, documentation and other improvements.

Also see the open issues for a list of proposed features and known issues.

Changelog

See changelog

Versioning

We use Semantic Versioning as a guideline for our versioning.

Releases use this format: {major}.{minor}.{patch}

• Breaking changes bump {major} and reset {minor} & {patch}

• Backward compatible changes bump {minor} and reset {patch}

• Bug fixes bump {patch}

Contributing

You want to help or share a proposal? You have a specific problem? Read the following:

• Code of conduct for details on our code of conduct.

• Contributing for details about how to report bugs and propose features.

• Developing for details about our development process and how to build and test the project.

Copyright and License

Copyright (c) 2022 D4L data4life gGmbH / All rights reserved.

Please refer to our License for further details.