Pengguna OAuth2 Generic

Copas prompt pengaturan dengan langkah instalasi dan panduan markdown lengkap untuk plugin ini.

Pendahuluan

Plugin Login Sosial Capgo mencakup mesin OAuth2 dan OpenID Connect bawaan. Anda dapat menggunakan plugin ini untuk menghubungkan penyedia identitas berbasis standar, termasuk:

GitHub
AD Azure / Microsoft Entra ID
Auth0
Okta
OAuth2
Server OAuth2 atau OIDC kustom

Oleh oauth2 Konfigurasi ini dirancang untuk multi-provider. Anda dapat mendaftarkan beberapa penyedia secara bersamaan dan kemudian memilih salah satu pada saat login dengan providerId.

Yang Anda Butuhkan

Sebelum Anda mengonfigurasi penyedia, kumpulkan:

ID Klien OAuth Anda
URL Redirect yang sesuai dengan skema aplikasi atau URL panggilan web Anda
Endpoint Otorisasi
Endpoint Token untuk aliran otorisasi code atau untuk penemuan OIDC issuerUrl What you need
Skop yang dibutuhkan aplikasi Anda, seperti openid profile email

Konfigurasi multi-providder

Gunakan SocialLogin.initialize() satu kali selama aplikasi startup dan daftarkan setiap penyedia yang Anda butuhkan:

import { SocialLogin } from '@capgo/capacitor-social-login';

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
    auth0: {
      issuerUrl: 'https://your-tenant.auth0.com',
      appId: 'your-auth0-client-id',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
    },
  },
});

Penemuan OIDC dan alias-alias

Jika penyedia Anda menampilkan dokumen penemuan OpenID Connect, issuerUrl adalah konfigurasi yang paling sederhana:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

Plugin ini juga mendukung alias-alias OAuth dan OIDC yang umum:

clientId sebagai alias dari appId
authorizationEndpoint sebagai alias dari authorizationBaseUrl
tokenEndpoint sebagai alias dari accessTokenEndpoint
endSessionEndpoint sebagai alias dari logoutUrl
scopes sebagai alias dari scope

Juga tersedia:

additionalParameters untuk penggantian permintaan autentikasi
additionalTokenParameters untuk penggantian pertukaran token
additionalResourceHeaders untuk pengaturan header endpoint sumber daya kustom
additionalLogoutParameters dan postLogoutRedirectUrl untuk aliran keluar
loginHint, prompt, dan iosPrefersEphemeralSession

Preset Kompatibel dengan Auth Connect

Jika Anda sedang melakukan migrasi dari Ionic Auth Connect dan ingin menjaga nama-nama penyedia yang sama, gunakan SocialLoginAuthConnect.

import { SocialLoginAuthConnect } from '@capgo/capacitor-social-login';

await SocialLoginAuthConnect.initialize({
  authConnect: {
    auth0: {
      domain: 'https://your-tenant.auth0.com',
      clientId: 'your-auth0-client-id',
      redirectUrl: 'myapp://oauth/auth0',
      audience: 'https://your-api.example.com',
    },
    azure: {
      tenantId: 'common',
      clientId: 'your-azure-client-id',
      redirectUrl: 'myapp://oauth/azure',
    },
    okta: {
      issuer: 'https://dev-12345.okta.com/oauth2/default',
      clientId: 'your-okta-client-id',
      redirectUrl: 'myapp://oauth/okta',
    },
  },
});

ID Penyedia Preset yang Dapat Dibuka:

auth0
azure
cognito
okta
onelogin

Jika penyedia yang dibutuhkan memiliki endpoint yang perlu disesuaikan, baiklah menggantinya di preset atau lewati preset dan atur penyedia secara langsung di oauth2.

Pilihan Konfigurasi

Jenis	Wajib	Deskripsi	Salin ke Papan Klip
`appId` / `clientId`	Keterangan string	Ya	Identifikasi klien OAuth2
`issuerUrl`	Keterangan string	Tidak	URL penemuan OIDC
`authorizationBaseUrl` / `authorizationEndpoint`	Keterangan string	Ya*	URL endpoint otorisasi
`accessTokenEndpoint` / `tokenEndpoint`	Keterangan string	Tidak*	URL endpoint token
`redirectUrl`	String	Ya	URL Panggilan Balik
`scope` / `scopes`	String / String[]	Tidak	Istilah yang Diminta
`pkceEnabled`	Boolean	Tidak	Atau `true`
`responseType`	`'code'` Tidak `'token'`	Atau	Atau `'code'`
`resourceUrl`	Informasi Pengguna atau Endpoint Sumber Daya	Tidak	Endpoint Pengguna atau Sumber Daya
`logoutUrl` / `endSessionEndpoint`	string	Tidak	URL Keluar atau Akhir Sesi
`postLogoutRedirectUrl`	string	Tidak	URL Redirect Setelah Keluar
`additionalParameters`	`Record<string, string>`	string	Tidak
`additionalTokenParameters`	`Record<string, string>`	Parameter Tambahan Permintaan Otorisasi	Parameter tambahan permintaan token
`additionalResourceHeaders`	`Record<string, string>`	Tidak	Kepala tambahan untuk `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	Tidak	Parameter logout tambahan
`loginHint`	string	Tidak	Singkat untuk `additionalParameters.login_hint`
`prompt`	string	Tidak	Singkat untuk `additionalParameters.prompt`
`iosPrefersEphemeralSession`	boolean	No	Menggunakan Sesi Browser Sementara
`logsEnabled`	boolean	No	aktifkan Pemantauan Debug yang Rinci

authorizationBaseUrl dan accessTokenEndpoint hanya opsional ketika issuerUrl itu sudah cukup untuk penemuan. Endpoint eksplisit selalu menang atas nilai yang ditemukan.

const result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
    scope: 'read:user user:email',
    loginHint: 'user@example.com',
  },
});

Alirkan ke web

Gunakan flow: 'redirect' Jika Anda ingin alirkan ke halaman penuh bukan popup:

await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'auth0',
    flow: 'redirect',
  },
});

Pada halaman yang menerima panggilan balik, analisis hasil login:

const result = await SocialLogin.handleRedirectCallback();
if (result?.provider === 'oauth2') {
  console.log(result.result.providerId);
}

const status = await SocialLogin.isLoggedIn({
  provider: 'oauth2',
  providerId: 'github',
});

await SocialLogin.logout({
  provider: 'oauth2',
  providerId: 'github',
});

Token refresh

await SocialLogin.refresh({
  provider: 'oauth2',
  options: {
    providerId: 'github',
  },
});

const refreshed = await SocialLogin.refreshToken({
  provider: 'oauth2',
  providerId: 'github',
  refreshToken: 'existing-refresh-token',
});

refresh() menggunakan token refres yang disimpan oleh plugin. refreshToken() memungkinkan Anda melewati token refres sendiri dan mengembalikan respons OAuth2 segar.

Ambil Token Akses Saat Ini

const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});

console.log(code.accessToken);

Contoh-provider

Contoh GitHub

Pakai GitHub ketika Anda ingin aliran aplikasi OAuth sederhana dan data profil dasar:

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
  },
});

const githubResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
  },
});

console.log(githubResult.result.accessToken?.token);
console.log(githubResult.result.resourceData);

Contoh Azure AD / Microsoft Entra ID

Pilih Azure ketika Anda membutuhkan data Microsoft Graph seperti profil pengguna:

await SocialLogin.initialize({
  oauth2: {
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
  },
});

const azureResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'azure',
  },
});

console.log(azureResult.result.idToken);
console.log(azureResult.result.resourceData);

Contoh Auth0

Auth0 cocok digunakan ketika Anda membutuhkan OIDC plus audiens API yang disesuaikan:

await SocialLogin.initialize({
  oauth2: {
    auth0: {
      appId: 'your-auth0-client-id',
      authorizationBaseUrl: 'https://your-tenant.auth0.com/authorize',
      accessTokenEndpoint: 'https://your-tenant.auth0.com/oauth/token',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
    },
  },
});

const auth0Result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'auth0',
    flow: 'redirect',
  },
});

Jika Anda menggunakan aliran redirect di web, baca hasilnya kembali di halaman panggilan balik:

const auth0Result = await SocialLogin.handleRedirectCallback();
if (auth0Result?.provider === 'oauth2') {
  console.log(auth0Result.result.idToken);
}

Contoh Okta

await SocialLogin.initialize({
  oauth2: {
    okta: {
      appId: 'your-okta-client-id',
      authorizationBaseUrl: 'https://your-domain.okta.com/oauth2/default/v1/authorize',
      accessTokenEndpoint: 'https://your-domain.okta.com/oauth2/default/v1/token',
      redirectUrl: 'myapp://oauth/okta',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      resourceUrl: 'https://your-domain.okta.com/oauth2/default/v1/userinfo',
    },
  },
});

const oktaResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'okta',
  },
});

console.log(oktaResult.result.resourceData);

Contoh Keycloak

Gunakan penemuan ketika penyedia Anda menerbitkan /.well-known/openid-configuration:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

const keycloakResult = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'keycloak',
  },
});

console.log(keycloakResult.result.idToken);

Bentuk respons OAuth2

Bidang	Deskripsi
`providerId`	Kunci penyedia yang dikonfigurasi digunakan untuk login
`accessToken`	Payload token akses atau `null`
`idToken`	Jika penyedia mengembalikan satu, token ID OIDC
`refreshToken`	Jika ruang lingkup yang diminta memungkinkannya, token refresh
`resourceData`	JSON mentah yang diambil dari `resourceUrl`
`scope`	Ruang lingkup yang diberikan
`tokenType`	Biasanya `bearer`
`expiresIn`	Umur token dalam detik

Referensi pengaturan penyedia

GitHub

Buat aplikasi OAuth Buka GitHub Pengaturan Pengembang dan buat aplikasi OAuth baru.
Setel URL panggilan balik Gunakan URL redirect aplikasi Anda, misalnya myapp://oauth/github.

Konfigurasi plugin

await SocialLogin.initialize({
  oauth2: {
    github: {
      appId: 'your-github-client-id',
      authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
      accessTokenEndpoint: 'https://github.com/login/oauth/access_token',
      redirectUrl: 'myapp://oauth/github',
      scope: 'read:user user:email',
      pkceEnabled: true,
      resourceUrl: 'https://api.github.com/user',
    },
  },
});

Microsoft Azure / ID Entra Microsoft

Mendaftarkan aplikasi Pergi ke Portal Azure, buka App registrations, dan buat pendaftaran aplikasi native atau mobile.
Tambahkan URI pengalihan Tambahkan URI pengalihan untuk perangkat mobile atau desktop yang sesuai dengan URL panggilan aplikasi Anda.

Konfigurasi plugin

await SocialLogin.initialize({
  oauth2: {
    azure: {
      appId: 'your-azure-client-id',
      authorizationBaseUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
      accessTokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
      redirectUrl: 'myapp://oauth/azure',
      scope: 'openid profile email User.Read',
      pkceEnabled: true,
      resourceUrl: 'https://graph.microsoft.com/v1.0/me',
    },
  },
});

Auth0

Buat aplikasi asli Buka Dashboard Auth0 dan buatlah aplikasi Native.
Setel URL panggilan yang diizinkan Tambahkan URL redirect yang tepat yang digunakan oleh aplikasi Capacitor Anda.

Konfigurasi plugin

await SocialLogin.initialize({
  oauth2: {
    auth0: {
      appId: 'your-auth0-client-id',
      authorizationBaseUrl: 'https://your-tenant.auth0.com/authorize',
      accessTokenEndpoint: 'https://your-tenant.auth0.com/oauth/token',
      redirectUrl: 'myapp://oauth/auth0',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      additionalParameters: {
        audience: 'https://your-api.example.com',
      },
      logoutUrl: 'https://your-tenant.auth0.com/v2/logout',
    },
  },
});

Okta

Buatlah aplikasi OIDC Native Dalam Console Admin Okta, buatlah Aplikasi OIDC Native.
Tambahkan URI redirect Anda Daftarkan URL panggilan yang tepat yang digunakan oleh aplikasi Anda.

Konfigurasi plugin

await SocialLogin.initialize({
  oauth2: {
    okta: {
      appId: 'your-okta-client-id',
      authorizationBaseUrl: 'https://your-domain.okta.com/oauth2/default/v1/authorize',
      accessTokenEndpoint: 'https://your-domain.okta.com/oauth2/default/v1/token',
      redirectUrl: 'myapp://oauth/okta',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
      resourceUrl: 'https://your-domain.okta.com/oauth2/default/v1/userinfo',
    },
  },
});

Keycloak dan penyedia OIDC kustom

Jika penyedia Anda mendukung penemuan OpenID Connect, prefer issuerUrl:

await SocialLogin.initialize({
  oauth2: {
    keycloak: {
      issuerUrl: 'https://sso.example.com/realms/mobile',
      clientId: 'mobile-app',
      redirectUrl: 'myapp://oauth/keycloak',
      scope: 'openid profile email offline_access',
      pkceEnabled: true,
    },
  },
});

Jika penemuan tidak tersedia, konfigurasi endpoint otorisasi dan token secara manual.

Catatan spesifik platform

iOS

Plugin ini menggunakan ASWebAuthenticationSession.
Set iosPrefersEphemeralSession: true Jika Anda ingin sesi browser pribadi tanpa cookie yang dibagikan.

Android

OAuth mengarahkan kembali melalui skema aplikasi dan host Anda.
Pastikan URL panggilan balik provider tepat sama dengan pengaturan deep link Android Anda.
Plugin sudah menghandle aktivitas OAuth. Tambahkan hanya filter intent yang diinginkan jika aplikasi Anda memerlukan pola redirect yang berbeda.

Web

Aliran popup adalah default dan berfungsi baik untuk aplikasi single-page.
Aliran redirect lebih baik ketika provider memblokir popup atau aturan autentikasi Anda memerlukan navigasi tingkat atas.
Beberapa provider memblokir pertukaran token browser langsung dengan CORS. Dalam kasus tersebut, gunakan pertukaran backend atau pengaturan provider yang memungkinkan klien publik.

Praktik keamanan terbaik

Gunakan PKCE Tetapkan pkceEnabled: true untuk klien publik.
Menggunakan aliran code untuk otorisasi lebih baik responseType: 'code' lebih aman daripada aliran implisit.
Validasi token di backend Anda Dekode dan verifikasi issuer, audience, expiration, dan tanda tangan di server.
Simpan token refresh dengan aman Untuk aplikasi native, pairkan plugin ini dengan @capgo/capacitor-persistent-account.
Gunakan HTTPS di mana-mana Endpoint autentikasi produksi dan endpoint keluar harus selalu menggunakan HTTPS.

Pembelajaran

`providerId is required`

Menggunakan metode OAuth2 memerlukan kunci penyedia yang telah dikonfigurasi:

await SocialLogin.login({
  provider: 'oauth2',
  options: { providerId: 'github' },
});

`OAuth2 provider "xxx" not configured`

Panggil SocialLogin.initialize() sebelum login dan pastikan bahwa providerId sama dengan kunci objek di bawah oauth2.

Tidak Cocok URL Redirect

Bandingkan URL redirect yang telah diatur di aplikasi dan dashboard penyedia karakter per karakter.
Perhatikan apakah ada tanda slash di akhir, perbedaan skema, dan host yang berbeda.
Pastikan URL skema aplikasi mobile telah terdaftar sebelum melakukan pengujian di perangkat.

Tidak Ada Token Refresh yang Dikembalikan

Sebagian besar penyedia hanya mengembalikan token refresh ketika Anda meminta skop seperti __CAPGO_KEEP_0__ atau secara eksplisit memaksa persetujuan. Tinjau kebijakan penyedia yang spesifik. offline_access Pengujian Token

Judul Bagian: ‘Pengujian Token’

untuk menginspeksi URL yang dihasilkan dan detail pengubahan token. logsEnabled: true Aktifkan __CAPGO_KEEP_1__ pada konfigurasi penyedia untuk menginspeksi URL yang dihasilkan dan detail pengubahan token.

Lanjutkan dari Penggunaan Provider OAuth2 Umum

Jika Anda menggunakan Penggunaan Provider OAuth2 Umum untuk merencanakan autentikasi dan aliran akun, hubungkannya dengan Menggunakan @capgo/capacitor-social-login untuk kemampuan native di Menggunakan @capgo/capacitor-social-login, @capgo/capacitor-social-login untuk detail implementasi di @capgo/capacitor-login-social, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-biometrik-natif untuk detail implementasi di @capgo/capacitor-biometrik-natif, dan Dua faktor autentikasi untuk detail implementasi di Dua Faktor Autentikasi.

Pengguna OAuth2 Generic

Pendahuluan

Yang Anda Butuhkan

Konfigurasi multi-providder

Penemuan OIDC dan alias-alias

Preset Kompatibel dengan Auth Connect

Pilihan Konfigurasi

Menggunakan Login OAuth2

Login

Alirkan ke web

Status login dan logout

Token refresh

Ambil Token Akses Saat Ini

Contoh-provider

Contoh GitHub

Contoh Azure AD / Microsoft Entra ID

Contoh Auth0

Contoh Okta

Contoh Keycloak

Bentuk respons OAuth2

Referensi pengaturan penyedia

GitHub

Microsoft Azure / ID Entra Microsoft

Auth0

Okta

Keycloak dan penyedia OIDC kustom

Catatan spesifik platform

iOS

Android

Web

Praktik keamanan terbaik

Pembelajaran

providerId is required

OAuth2 provider "xxx" not configured

Tidak Cocok URL Redirect

Tidak Ada Token Refresh yang Dikembalikan

Judul Bagian: ‘Pengujian Token’

Dokumen terkait

Lanjutkan dari Penggunaan Provider OAuth2 Umum

`providerId is required`

`OAuth2 provider "xxx" not configured`