Skip to content

Commit

Permalink
alex-fusionauth/android-sdk-blog-update (FusionAuth#3123)
Browse files Browse the repository at this point in the history
* feat(android-sdk): add initial version of SDK doc

* feat(android-sdk): add initial drafts

* feat(android-sdk): blog content placeholder difference AppAuth

* feat(android-sdk): update docs and blog

* feat(android-sdk): update docs and blog

* refactor(android-sdk): Ngrok not required

* feat(android-sdk): update docs and blog

* docs(android-sdk): some changes to "Difference to AppAuth" section

* feat(android-sdk): add blog conclusion

* refactor(quickstart): update content, add RemoteContent

* refactor(quickstart): update RemoteCode and add TODOs

* refactor(android-sdk-beta): update conclusion

* docs(quickstart): extend Quickstart

* refactor(android-sdk-beta): quickstart changes
* change repository name
* change repository structure
* further align quickstart guide to standard

* refactor(android-sdk-beta): reviewdog suggested changes

* refactor(android-sdk-beta): add suggested changes

* refactor(android-sdk-beta): add suggested changes

* Update astro/src/content/quickstarts/quickstart-android-kotlin-native.mdx

Co-authored-by: Alex Patterson <[email protected]>

* Update astro/src/content/blog/android-sdk-beta.mdx

Co-authored-by: Alex Patterson <[email protected]>

* Update astro/src/content/quickstarts/quickstart-android-kotlin-native.mdx

Co-authored-by: Mark Robustelli <[email protected]>

* refactor(android-sdk-beta): add additional clarifications

* include cover

* adjust sentence

---------

Co-authored-by: Aaron-Ritter <[email protected]>
Co-authored-by: Colin Frick <[email protected]>
Co-authored-by: Colin Frick <[email protected]>
Co-authored-by: Mark Robustelli <[email protected]>
Co-authored-by: Alex Patterson <[email protected]>
  • Loading branch information
6 people authored Jun 17, 2024
1 parent 349c71e commit fd8f5d1
Show file tree
Hide file tree
Showing 5 changed files with 324 additions and 1 deletion.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
104 changes: 104 additions & 0 deletions astro/src/content/blog/android-sdk-beta.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
---
publish_date: 2024-06-17
title: Our Beta Android SDK
description: Android SDK make integrating with FusionAuth easier
authors: Colin Frick, Aaron Ritter
excerpt_separator: "{/* more */}"
image: /img/blogs/android-sdk-beta/our-beta-android-sdk.png
categories: Product
tags: sdks, android, kotlin
---
import RemoteContent from 'src/components/RemoteContent.astro';

FusionAuth's new beta SDK streamlines mobile development for iOS and Android, offering powerful backend capabilities and seamless integration with your preferred frameworks.

{/* more */}

Recently, the team released a software development kit (SDK) Beta for [Android](/docs/sdks/android-sdk) which eliminates boilerplate code, leading to cleaner and more efficient applications.

## The Android SDK

The FusionAuth Android SDK aims to provide a simple and trustworthy interface to authenticate mobile users with FusionAuth.

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteOverview" />

### Difference to AppAuth

For OAuth 2.0 authentication, the Authentication Manager uses [AppAuth](https://appauth.io/) to handle the authentication flow. AppAuth is an open-source library that provides a simple interface for authenticating users with OAuth 2.0. It's available for [Android](https://github.com/openid/AppAuth-Android) and [iOS](https://github.com/openid/AppAuth-iOS).

Using AppAuth directly might seem a good idea because it grants more control over the implementation, but there are compelling reasons to use the FusionAuth Android SDK instead.

1. **Simplified Authentication Flow**: The SDK simplifies the process of authenticating users with FusionAuth by providing a simple interface.

2. **Standardized Usage**: The SDK introduces standardized usage with the introduction of the Authorization Manager.

3. **Security**: The SDK handles best practice defaults in the Authorization Configuration.

4. **Time-Saving**: The SDK handles all dependencies and best practice defaults for you.

5. **Maintainability**: The SDK gives us the flexibility to add additional functionality without having to feature creep the AppAuth library, or implement features early until they get added to AppAuth.

### Getting Started

To simplify the experience, our primary goal was to introduce a minimum effort from the start. With a single import and a simple as possible configuration, which handles all dependencies and best practice defaults for you through the [Authorization Configuration](https://github.com/FusionAuth/fusionauth-android-sdk/blob/main/library/docs/library/io.fusionauth.mobilesdk/-authorization-configuration/index.md).

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteGettingStarted" />

### Usage

Our secondary goal with the SDK was the standardization of the usage with, for example, the introduction of the [Authorization Manager](https://github.com/FusionAuth/fusionauth-android-sdk/blob/main/library/docs/library/io.fusionauth.mobilesdk/-authorization-manager/index.md).

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteUsage" />

### Security

With the simplified start in the [Authorization Configuration](https://github.com/FusionAuth/fusionauth-android-sdk/blob/main/library/docs/library/io.fusionauth.mobilesdk/-authorization-configuration/index.md) and standardized usage in the [Authorization Manager](https://github.com/FusionAuth/fusionauth-android-sdk/blob/main/library/docs/library/io.fusionauth.mobilesdk/-authorization-manager/index.md) we now took care of best practice defaults. as well as handling token storage, refresh, and retrieval in the [Token Manager](https://github.com/FusionAuth/fusionauth-android-sdk/blob/main/library/docs/library/io.fusionauth.mobilesdk/-token-manager/index.md).

What we didn't want to change is the AppAuth authentication flow through a browser redirect. When using a browser redirect to the SSO URL, the only application that sees or holds sensitive user credentials is FusionAuth. Your application code never has access to these, which decreases the attack surface area.

In addition, FusionAuth has built-in security features such as:

* the ability to lock user accounts
* password rules
* webhook notifications when a user has failed to login
* breached password notification (with a paid license)
* rate limiting of sensitive security-related actions (with an Enterprise license)
* and more

[FusionAuth takes security seriously](/security); it's our full-time job. By redirecting to FusionAuth, you don't have to worry about any other part of your application getting access to sensitive information or credentials.

### Look and Feel

Do you typically want your login pages to look like your Mobile App? Doesn't a browser redirect make that difficult?

No, FusionAuth allows complete control over the look and feel of the hosted login pages. Learn more about this functionality, which we call [themes](/docs/customize/look-and-feel/), including an [example using Tailwind CSS](/docs/customize/look-and-feel/tailwind).

Being able to make the look and feel the same as your mobile app if your users use the same SSO page design for other use cases, e.g., your online store or portal. It will create more trust because the experience (including design, SSO URL, and authentication process) will be the same on mobile as anywhere else.

### Example

We've built an App for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins.

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteExampleApp" />

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteQuickstart" />

## In Conclusion

With the introduction of the FusionAuth Android SDK Beta, we're eager to finalize the development into a final release and are looking forward to doing this with your feedback.

Especially as the SDK is set to standardize and secure your authorization processes in your mobile application development. We're interested to see if it helps your development, whether you're getting started or looking for a way to standardize and secure your authorization processes in your Android App.

## More details on the SDK and collaboration

We created detailed documentation of the SDK and made it available in the [GitHub repository](https://github.com/FusionAuth/fusionauth-android-sdk/) of the SDK.

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteDocumentation" />

In there, you will find as well how you can [contribute](https://github.com/FusionAuth/fusionauth-android-sdk/?tab=readme-ov-file#contributing) further in the development of the FusionAuth Android SDK.
42 changes: 42 additions & 0 deletions astro/src/content/docs/sdks/android-sdk.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: FusionAuth Android SDK
description: The FusionAuth Android SDK allows you to add different OAuth2 and OpenID Connect functionalities to your Android application. It's a highly standardized and simplified starting point for developers to easily integrate FusionAuth in their own custom mobile apps by taking care of all the dependencies.
navcategory: developer
section: sdks
disableTOC: true
---
import RemoteContent from 'src/components/RemoteContent.astro';

## Overview

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteOverview" />

## Getting Started

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteGettingStarted" />

## Usage

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteUsage" />

## Example App

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteExampleApp" />

## Quickstart

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteQuickstart" />

## Documentation

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/README.md"
tags="forDocSiteDocumentation" />

## Source Code

The source code is available here: https://github.com/FusionAuth/fusionauth-android-sdk/
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Android Java
title: Android Java - AppAuth
description: Quickstart integration of a Java-based Android app with FusionAuth
navcategory: getting-started
prerequisites: Android Studio, Git
Expand Down
177 changes: 177 additions & 0 deletions astro/src/content/quickstarts/quickstart-android-kotlin-native.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
---
title: Android Kotlin - Fusionauth SDK (Beta)
description: Quickstart integration of a Kotlin-based Android app with FusionAuth Android SDK
navcategory: getting-started
prerequisites: Android Studio, Git
section: native
technology: Android
language: Kotlin
icon: /img/icons/android.svg
faIcon: fa-android
color: indigo
cta: EmailListCTA
codeRoot: https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main
---
import Intro from '/src/components/quickstarts/Intro.astro';
import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro';
import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro';
import NextSteps from '/src/components/quickstarts/NextSteps.astro';
import {RemoteCode} from '@fusionauth/astro-components';
import RemoteContent from 'src/components/RemoteContent.astro';
import QuickstartTshirtCTA from '/src/components/quickstarts/QuickstartTshirtCTA.astro'

This quickstart is built on top of [FusionAuth Android SDK](/docs/sdks/android-sdk) demonstrating the different functionalities of the SDK available.

<Intro fulltext="an Android app with Kotlin"
repositoryUrl="https://github.com/FusionAuth/fusionauth-quickstart-kotlin-android-native"/>

## Prerequisites

<RemoteContent url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/README.md"
tags="forDocSitePrerequisites" />

## General Architecture

<LoginArchitectureWeb/>

## Getting Started

In this section, you'll get FusionAuth up and running and use `git` to create a new application.

### Clone the Code

First off, grab the code from the repository and change into that directory.

```shell
git clone https://github.com/FusionAuth/fusionauth-quickstart-kotlin-android-native.git
cd fusionauth-quickstart-kotlin-android-native
```

### Run FusionAuth via Docker

<DockerSpinup kickstartUri={frontmatter.codeRoot + "/kickstart/kickstart.json"} />

### Create your Android App

If you want to skip the step by step creation of the Android App open the `./complete-application/` folder in Android Studio.

Open Android Studio and select `New Project`. Choose `No Activity` and click `Next`.

You can set `Name` to `FusionAuth Android SDK Quickstart`, `Package name` to `io.fusionauth.sdk` and `Save location` as per your preference.
Keep the `Language` as `Kotlin`, `Minimum API level` as `API 24 ("Nougat"; Android 7.0)` and `Build configuration language` as `Kotlin DSL`.

Click `Finish`.

Wait until Android Studio has finished creating and indexing the project.

Add the [FusionAuth SDK as a dependency](https://central.sonatype.com/artifact/io.fusionauth/fusionauth-android-sdk/) to your project by changing the `app/build.gradle.kts` file. You can replace the entire file with below contents.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/build.gradle.kts"
lang="kotlin"/>

Replace `app/src/main/AndroidManifest.xml` as well which defines all Activities used later.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/AndroidManifest.xml"
lang="kotlin"/>

## Authentication

We'll use the [FusionAuth Android SDK](/docs/sdks/android-sdk) , which simplifies integrating with FusionAuth and creating a secure web application.

### Configure FusionAuth

Create `app/src/main/res/raw/fusionauth_config.json` to use the values provisioned by Kickstart.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-android-sdk/main/app/src/main/res/raw/fusionauth_config.json"
lang="json"/>

### Change Activities

An [Activity](https://developer.android.com/guide/components/activities/intro-activities) is a screen for your app, combining the User Interface as well as the logic to handle it.
Start by creating the login activity layout at `app/src/main/res/layout/activity_login.xml`. Replace it with the below XML.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/layout/activity_login.xml"
lang="xml"/>

Now modify login activity logic by creating `app/src/main/java/io/fusionauth/sdk/LoginActivity.kt` with this code.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/java/io/fusionauth/sdk/LoginActivity.kt"
lang="kotlin"/>

Create the main screen layout in the file `app/src/main/res/layout/activity_token.xml`.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/layout/activity_token.xml"
lang="xml"/>

And finally, create the main screen logic by creating `app/src/main/java/io/fusionauth/sdk/TokenActivity.kt` with the below.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/java/io/fusionauth/sdk/TokenActivity.kt"
lang="kotlin"/>

## App Customization

In this section, you'll update the look and feel of your native application to match the ChangeBank banking styling.

### Change Colors and Strings

Change the application colors in `app/src/main/res/values/colors.xml` to the ones used by ChangeBank.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/values/colors.xml"
lang="xml"/>

Modify strings shown in the user interface by updating `app/src/main/res/values/strings.xml`.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/values/strings.xml"
lang="xml"/>

Update the theme in `app/src/main/res/values/themes.xml`.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/values/themes.xml"
lang="xml"/>

Create the dimension file in `app/src/main/res/values/dimens.xml`.

<RemoteCode url="https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/values/dimens.xml"
lang="xml"/>

Finally, remove the night theme by deleting `app/src/main/res/values-night` directory.

### Add Styling

Now, add image assets to make this look like a real application with the following shell commands, run in the root of your project.

```shell
curl -o app/src/main/res/drawable/changebank.png https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/drawable/changebank.png
curl -o app/src/main/res/drawable/ic_launcher_background.xml https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/drawable/ic_launcher_background.xml
curl -o app/src/main/res/drawable/ic_launcher_foreground.xml https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/drawable/ic_launcher_foreground.xml
curl -o app/src/main/res/mipmap-hdpi/ic_launcher.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-hdpi/ic_launcher.webp
curl -o app/src/main/res/mipmap-hdpi/ic_launcher_round.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-hdpi/ic_launcher_round.webp
curl -o app/src/main/res/mipmap-mdpi/ic_launcher.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-mdpi/ic_launcher.webp
curl -o app/src/main/res/mipmap-mdpi/ic_launcher_round.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-mdpi/ic_launcher_round.webp
curl -o app/src/main/res/mipmap-xhdpi/ic_launcher.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-xhdpi/ic_launcher.webp
curl -o app/src/main/res/mipmap-xhdpi/ic_launcher_round.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-xhdpi/ic_launcher_round.webp
curl -o app/src/main/res/mipmap-xxhdpi/ic_launcher.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-xxhdpi/ic_launcher.webp
curl -o app/src/main/res/mipmap-xxhdpi/ic_launcher_round.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-xxhdpi/ic_launcher_round.webp
curl -o app/src/main/res/mipmap-xxxhdpi/ic_launcher.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-xxxhdpi/ic_launcher.webp
curl -o app/src/main/res/mipmap-xxxhdpi/ic_launcher_round.webp https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-kotlin-android-native/main/complete-application/app/src/main/res/mipmap-xxxhdpi/ic_launcher_round.webp
```

Once you've created these files, you can test the application out.

## Run the App

The quickstart app is configured to run on an Android Virtual Device using the [Android Emulator](https://developer.android.com/studio/run/emulator)

[Build and run the app](https://developer.android.com/studio/run/) following Android Studio guidelines.

<QuickstartTshirtCTA/>

## Next Steps

<NextSteps/>

## Troubleshooting

* I can't log in

Make sure you have the right values at `app/src/main/res/raw/fusionauth_config.json`. Double-check the `Issuer` in the **Tenant** to make sure it matches the URL that FusionAuth is running at.

0 comments on commit fd8f5d1

Please sign in to comment.