Skip to content

Commit d47ac35

Browse files
tafelnltafelnl
authored
feat: update readme (#262)
1 parent 38b65a4 commit d47ac35

File tree

1 file changed

+62
-87
lines changed

1 file changed

+62
-87
lines changed

‎README.md‎

Lines changed: 62 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,40 @@
1-
# Capacitor OAuth 2 client plugin
1+
<p align="center"><br><img src="https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png" width="128" height="128" /></p>
2+
<h3 align="center">Safe Area</h3>
3+
<p align="center"><strong><code>@capacitor-community/generic-oauth2</code></strong></p>
4+
<p align="center">
5+
Generic Capacitor OAuth 2 client plugin.
6+
</p>
27

3-
<a href="#sponsors"><img src="https://img.shields.io/badge/plugin-Sponsors-blue?style=flat-square" /></a>
4-
<a href="https://github.com/moberwasserlechner/capacitor-oauth2/actions/workflows/ci.yml"><img src="https://github.com/moberwasserlechner/capacitor-oauth2/actions/workflows/ci.yml/badge.svg?branch=main" /></a>
5-
<a href="https://www.npmjs.com/package/@capacitor-community/generic-oauth"><img src="https://img.shields.io/npm/dw/@capacitor-community/generic-oauth?style=flat-square" /></a>
6-
<a href="https://www.npmjs.com/package/@capacitor-community/generic-oauth"><img src="https://img.shields.io/npm/v/@capacitor-community/generic-oauth?style=flat-square" /></a>
7-
<a href="LICENSE"><img src="https://img.shields.io/npm/l/@capacitor-community/generic-oauth?style=flat-square" /></a>
8+
<p align="center">
9+
<img src="https://img.shields.io/maintenance/yes/2024?style=flat-square" />
10+
<a href="https://github.com/capacitor-community/generic-oauth2/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/capacitor-community/generic-oauth2/ci.yml?branch=main&style=flat-square" /></a>
11+
<a href="https://www.npmjs.com/package/@capacitor-community/generic-oauth2"><img src="https://img.shields.io/npm/l/@capacitor-community/generic-oauth2?style=flat-square" /></a>
12+
<br>
13+
<a href="https://www.npmjs.com/package/@capacitor-community/generic-oauth2"><img src="https://img.shields.io/npm/dw/@capacitor-community/generic-oauth2?style=flat-square" /></a>
14+
<a href="https://www.npmjs.com/package/@capacitor-community/generic-oauth2"><img src="https://img.shields.io/npm/v/@capacitor-community/generic-oauth2?style=flat-square" /></a>
15+
</p>
816

9-
This is a **generic OAuth 2 client** plugin. It let you configure the oauth parameters yourself instead of using SDKs. Therefore it is usable with various providers.
10-
See [identity providers](#list-of-providers) the community has already used this plugin with.
17+
## Introduction
1118

12-
## How to install
19+
This is a **generic OAuth 2 client** plugin. It lets you configure the oauth parameters yourself instead of using SDKs. Therefore it is usable with various providers. See [identity providers](#list-of-providers) the community has already used this plugin with.
1320

14-
For Capacitor v5
21+
## Installation
1522

1623
```bash
17-
npm i @capacitor-community/generic-oauth
18-
npx cap sync
19-
```
20-
21-
For Capacitor v4
22-
23-
```bash
24-
npm i @capacitor-community/generic-oauth@4
25-
npx cap sync
26-
```
27-
28-
For Capacitor v3
29-
30-
```bash
31-
npm i @capacitor-community/generic-oauth@3
24+
npm install @capacitor-community/generic-oauth2
3225
npx cap sync
3326
```
3427

3528
## Versions
3629

37-
| Plugin | For Capacitor | Docs | Notes |
38-
| ------ | ------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
39-
| 5.x | 5.x.x | [README](./README.md) | Breaking changes see Changelog. XCode 14.1 needs this version |
40-
| 4.x | 4.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/4.0.0/README.md) | Breaking changes see Changelog. XCode 12.0 needs this version |
41-
| 3.x | 3.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/3.0.1/README.md) | Breaking changes see Changelog. XCode 12.0 needs this version |
42-
| 2.x | 2.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/2.1.0/README.md) | Breaking changes see Changelog. XCode 11.4 needs this version |
43-
| 1.x | 1.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/1.1.0/README.md) | |
44-
45-
For further details on what has changed see the [CHANGELOG](https://github.com/moberwasserlechner/capacitor-oauth2/blob/main/CHANGELOG.md).
46-
47-
## Sponsors
48-
49-
I would like to especially thank some people and companies for supporting my work on this plugin and therefore improving it for everybody.
50-
51-
- [Mark Laurence](https://github.com/UnclearMaker) and the [Royal Veterinary College](https://www.rvc.ac.uk/) - Thanks for supporting open source.
52-
53-
## Maintainers
54-
55-
| Maintainer | GitHub | Social |
56-
| ------------------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
57-
| Michael Oberwasserlechner | [moberwasserlechner](https://github.com/moberwasserlechner) | [@michaelowl_web](https://twitter.com/michaelowl_web) |
58-
59-
Actively maintained: YES
30+
| Plugin | For Capacitor | Docs | Notes |
31+
| ------ | ------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
32+
| 6.x | 6.x.x | [README](./README.md) | Breaking changes. As of this version the changelog will be available in the Releases tab in GitHub. XCode 15.0 needs this version |
33+
| 5.x | 5.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/5.0.0/README.md) | Breaking changes see Changelog. XCode 14.1 needs this version |
34+
| 4.x | 4.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/4.0.0/README.md) | Breaking changes see Changelog. XCode 12.0 needs this version |
35+
| 3.x | 3.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/3.0.1/README.md) | Breaking changes see Changelog. XCode 12.0 needs this version |
36+
| 2.x | 2.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/2.1.0/README.md) | Breaking changes see Changelog. XCode 11.4 needs this version |
37+
| 1.x | 1.x.x | [README](https://github.com/moberwasserlechner/capacitor-oauth2/blob/1.1.0/README.md) | |
6038

6139
## Supported flows
6240

@@ -108,12 +86,10 @@ That flow should only be used on the backend (server).
10886

10987
## Configuration
11088

111-
Starting with version 3.0.0, the plugin is registered automatically on all platforms.
112-
11389
### Use it
11490

11591
```typescript
116-
import { OAuth2Client } from '@capacitor-community/generic-oauth';
92+
import { OAuth2Client } from '@capacitor-community/generic-oauth2';
11793

11894
@Component({
11995
template:
@@ -295,21 +271,20 @@ This implementation just opens a browser window to let users enter their credent
295271
As there is no provider SDK used to accomplish OAuth, no additional javascript files must be loaded and so there is no performance
296272
impact using this plugin in a web application.
297273

298-
### Register plugin
299-
300-
On Web/PWA the plugin is registered **automatically** by Capacitor.
301-
302274
## Platform: Android
303275

304-
Prerequisite: [Capacitor Android Docs](https://capacitor.ionicframework.com/docs/android/configuration)
276+
There are two options when configuring an OAuth 2 protocol:
305277

306-
### Register plugin
278+
1. Some OAuth providers allow using their service _without_ implementing their SDK. For these providers, you can use the default config available,
279+
2. Other OAuth providers (e.g. Facebook) force developers to use their SDK. For these providers, you can implement a _Custom OAuth Handler_.
307280

308-
On Android the plugin is registered **automatically** by Capacitor.
281+
### 1. Android Default Config
309282

310-
### Android Default Config
283+
> [!NOTE]
284+
> You can skip this, if you're only exclusively configuring providers using a _Custom OAuth Handler_.
311285
312-
Skip this, if you use a `OAuth2CustomHandler`. See below.
286+
> [!NOTE]
287+
> For more information about configuring your Android app, refer to the [offical Capacitor documentation](https://capacitor.ionicframework.com/docs/android/configuration)
313288
314289
#### android/app/src/main/res/AndroidManifest.xml
315290

@@ -336,10 +311,12 @@ and change it to
336311
<data android:scheme="@string/custom_url_scheme" android:host="oauth" />
337312
```
338313

339-
Note: Actually any value for `android:host` will do. It does not has to be `oauth`.
340-
341-
This will fix an issues within the oauth workflow when the application is shown twice.
342-
See [Issue #15](https://github.com/moberwasserlechner/capacitor-oauth2/issues/15) for details what happens.
314+
> [!NOTE]
315+
> Actually any value for `android:host` will do. It does not have to be `oauth`.
316+
>
317+
> This will fix an issues within the oauth workflow where the application is shown twice.
318+
>
319+
> See [Issue #15](https://github.com/moberwasserlechner/capacitor-oauth2/issues/15) for details what happens.
343320
344321
#### android/app/src/main/res/values/strings.xml
345322

@@ -383,27 +360,29 @@ android.buildTypes.release.manifestPlaceholders = [
383360
Also, it uses the system browser that the plugin uses (and not the user's default browser) to call the logout URL.
384361
This additionally ensures that the cookies are deleted in the correct browser.
385362

386-
### Custom OAuth Handler
363+
### 2. Custom OAuth Handler
387364

388-
Some OAuth provider (Facebook) force developers to use their SDK on Android.
365+
Some OAuth providers (e.g. Facebook) force developers to use their SDK.
389366

390-
This plugin should be as generic as possible so I don't want to include provider specific dependencies.
367+
This plugin should be as generic as possible, so I don't want to include provider specific dependencies.
391368

392369
Therefore, I created a mechanism which let developers integrate custom SDK features in this plugin.
393370
Simply configure a full qualified classname in the option property `android.customHandlerClass`.
394-
This class has to implement `com.byteowls.capacitor.oauth2.handler.OAuth2CustomHandler`.
371+
This class has to implement `com.getcapacitor.community.genericoauth2.handler.OAuth2CustomHandler`.
395372

396-
See a full working example below!
373+
Refer to the [Facebook example below](#facebook) for a reference implementation.
397374

398375
## Platform: iOS
399376

400-
### Register plugin
377+
There are two options when configuring an OAuth 2 protocol:
401378

402-
On iOS the plugin is registered **automatically** by Capacitor.
379+
1. Some OAuth providers allow using their service _without_ implementing their SDK. For these providers, you can use the default config available,
380+
2. Other OAuth providers (e.g. Facebook) force developers to use their SDK. For these providers, you can implement a _Custom OAuth Handler_.
403381

404-
### iOS Default Config
382+
### 1. iOS Default Config
405383

406-
Skip this, if you use a `OAuth2CustomHandler`. See below.
384+
> [!NOTE]
385+
> You can skip this, if you're only exclusively configuring providers using a _Custom OAuth Handler_.
407386
408387
Open `ios/App/App/Info.plist` in XCode (Context menu -> Open as -> Source) and add the value of `redirectUrl` from your config without `:/` like that
409388

@@ -419,17 +398,17 @@ Open `ios/App/App/Info.plist` in XCode (Context menu -> Open as -> Source) and a
419398
</array>
420399
```
421400

422-
### Custom OAuth Handler
401+
### 2. Custom OAuth Handler
423402

424-
Some OAuth provider (e.g., Facebook) force developers to use their SDK on iOS.
403+
Some OAuth providers (e.g. Facebook) force developers to use their SDK.
425404

426405
This plugin should be as generic as possible, so I don't want to include provider specific dependencies.
427406

428407
Therefore, I created a mechanism which let developers integrate custom SDK features in this plugin.
429408
Simply configure the class name in the option property `ios.customHandlerClass`.
430409
This class has to implement `CapacitorCommunityGenericOauth2.OAuth2CustomHandler`.
431410

432-
See a full working example below!
411+
Refer to the [Facebook example below](#facebook) for a reference implementation.
433412

434413
## Platform: Electron
435414

@@ -499,7 +478,7 @@ In Angular do sth like
499478
```typescript
500479
import { Component, OnInit } from '@angular/core';
501480
import { Device, DeviceInfo } from '@capacitor/device';
502-
import { OAuth2Client } from '@capacitor-community/generic-oauth';
481+
import { OAuth2Client } from '@capacitor-community/generic-oauth2';
503482

504483
@Component({
505484
templateUrl: './siwa.component.html',
@@ -560,7 +539,7 @@ They share the same core features and therefore the plugin should work either wa
560539
import {
561540
OAuth2AuthenticateOptions,
562541
OAuth2Client,
563-
} from '@capacitor-community/generic-oauth';
542+
} from '@capacitor-community/generic-oauth2';
564543

565544
export class AuthService {
566545
getAzureB2cOAuth2Options(): OAuth2AuthenticateOptions {
@@ -599,7 +578,7 @@ Try to experiment with the config until Azure includes everything you need in th
599578
<summary>A configuration with custom scopes might look like this:</summary>
600579

601580
```typescript
602-
import {OAuth2Client} from "@capacitor-community/generic-oauth";
581+
import {OAuth2Client} from "@capacitor-community/generic-oauth2";
603582

604583
getAzureB2cOAuth2Options(): OAuth2AuthenticateOptions {
605584
return {
@@ -635,7 +614,7 @@ import {OAuth2Client} from "@capacitor-community/generic-oauth";
635614
<summary>Other configs that works in prior versions</summary>
636615

637616
```typescript
638-
import {OAuth2Client} from "@capacitor-community/generic-oauth";
617+
import {OAuth2Client} from "@capacitor-community/generic-oauth2";
639618

640619
azureLogin() {
641620
OAuth2Client.authenticate({
@@ -666,7 +645,7 @@ azureLogin() {
666645
```
667646

668647
```typescript
669-
import {OAuth2Client} from "@capacitor-community/generic-oauth";
648+
import {OAuth2Client} from "@capacitor-community/generic-oauth2";
670649

671650
azureLogin() {
672651
OAuth2Client.authenticate({
@@ -803,7 +782,7 @@ See this [example repo](https://github.com/loonix/capacitor-oauth2-azure-example
803782
#### PWA
804783

805784
```typescript
806-
import {OAuth2Client} from "@capacitor-community/generic-oauth";
785+
import {OAuth2Client} from "@capacitor-community/generic-oauth2";
807786

808787
googleLogin() {
809788
OAuth2Client.authenticate({
@@ -849,7 +828,7 @@ See [iOS Default Config](#ios-default-config)
849828
#### PWA
850829

851830
```typescript
852-
import {OAuth2Client} from "@capacitor-community/generic-oauth";
831+
import {OAuth2Client} from "@capacitor-community/generic-oauth2";
853832

854833
facebookLogin() {
855834
let fbApiVersion = "2.11";
@@ -1174,10 +1153,6 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
11741153

11751154
See [Contribution Guidelines](https://github.com/moberwasserlechner/capacitor-oauth2/blob/main/.github/CONTRIBUTING.md).
11761155

1177-
## Changelog
1178-
1179-
See [CHANGELOG](https://github.com/moberwasserlechner/capacitor-oauth2/blob/main/CHANGELOG.md).
1180-
11811156
## License
11821157

11831158
MIT. See [LICENSE](https://github.com/moberwasserlechner/capacitor-oauth2/blob/main/LICENSE).

0 commit comments

Comments
 (0)