Provider OAuth2 Umum

Copy 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
Azure AD / Microsoft Entra ID
Auth0
Okta
Keycloak
Server OAuth2 atau OIDC kustom

Oleh oauth2 Konfigurasi ini dirancang untuk beberapa penyedia. Anda dapat mendaftarkan beberapa penyedia sekaligus 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 Skop yang diperlukan aplikasi Anda, seperti
Skop yang dibutuhkan aplikasi Anda, seperti openid profile email

Konfigurasi penyedia multi

Pilih SocialLogin.initialize() sekali 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

Jika penyedia Anda menampilkan dokumen penemuan OpenID Connect, issuerUrl Pengaturan 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 OAuth dan OIDC yang umum:

clientId sebagai sebuah 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 pengaturan permintaan autentikasi
additionalTokenParameters untuk pengaturan penggantian token
additionalResourceHeaders untuk header endpoint sumber daya kustom
additionalLogoutParameters dan postLogoutRedirectUrl untuk aliran keluar
loginHint, prompt, dan iosPrefersEphemeralSession

preset yang kompatibel dengan Auth Connect

Jika Anda sedang melakukan migrasi dari Ionic Auth Connect dan ingin menjaga 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 Dibantu:

auth0
azure
cognito
okta
onelogin

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

Pilihan Konfigurasi

Pilihan	Tipe	Kewajiban	Deskripsi
`appId` / `clientId`	string	Ya	Identifikasi Klien OAuth2
`issuerUrl`	string	Tidak	URL Dasar Pengenalan OIDC
`authorizationBaseUrl` / `authorizationEndpoint`	string	Ya*	URL Endpoint Otorisasi
`accessTokenEndpoint` / `tokenEndpoint`	string	Tidak*	URL Endpoint Token
`redirectUrl`	string	Ya	URL Panggilan Balik
`scope` / `scopes`	string / array string[]	Tidak	Skop yang Diminta
`pkceEnabled`	boolean	Tidak	Defaultnya `true`
`responseType`	`'code'` atau `'token'`	Tidak	Defaultnya `'code'`
`resourceUrl`	string	Tidak	Informasi pengguna atau endpoint sumber daya
`logoutUrl` / `endSessionEndpoint`	string	Tidak	URL keluar atau akhir-sesi
`postLogoutRedirectUrl`	string	Tidak	URL arahan setelah keluar
`additionalParameters`	`Record<string, string>`	Tidak	Parameter tambahan permintaan autentikasi
`additionalTokenParameters`	`Record<string, string>`	Tidak	Parameter tambahan permintaan token
`additionalResourceHeaders`	`Record<string, string>`	Tidak	Kop surut tambahan untuk `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	Tidak	Kop keluar tambahan
`loginHint`	string	Tidak	Singkat untuk `additionalParameters.login_hint`
`prompt`	string	Tidak	Singkat untuk `additionalParameters.prompt`
`iosPrefersEphemeralSession`	boolean	Tidak	Preferlah sesi browser sementara di iOS
`logsEnabled`	boolean	Tidak	aktifkan pengaturan debug verbose

authorizationBaseUrl dan accessTokenEndpoint hanya opsional ketika issuerUrl adalah 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',
  },
});

Aliran Redirect di Web

Pilih flow: 'redirect' Jika Anda ingin aliran redirect penuh halaman daripada 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 refresh yang disimpan oleh plugin. refreshToken() Mengizinkan Anda melewati token refresh 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-contoh spesifik 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 kustom API:

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

Pakai 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

Kolom	Deskripsi
`providerId`	Kunci penyedia yang diatur untuk login
`accessToken`	Isi akses token atau `null`
`idToken`	Token ID OIDC jika penyedia mengembalikannya
`refreshToken`	Token refresh jika ruang lingkup yang diminta memungkinkannya
`resourceData`	JSON mentah yang diambil dari `resourceUrl`
`scope`	Ruangan 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 Pakai 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',
    },
  },
});

Azure AD / Microsoft Entra ID

Daftarkan Aplikasi Mendaftarkan aplikasi App registrationsdan membuat registrasi aplikasi native atau mobile.
, dan buat pendaftaran aplikasi native atau mobile. Tambahkan URI pengalihan 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 Natively Buka halaman Auth0 Dashboard Membuat dan membuat aplikasi Native.
Setel URL panggilan balik yang diizinkan. Tambahkan URL redirect yang tepat 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',
    },
  },
});

context

Buat Aplikasi OIDC Asli Buat Aplikasi OIDC Native di Konsole Admin Okta.
Buat aplikasi OIDC native Dalam Console Admin Okta, buatlah Aplikasi OIDC Native.

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.
Pilih 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 provider Anda sesuai dengan pengaturan tautan dalam aplikasi Android Anda.
Plugin ini sudah menghandle aktivitas OAuth. Hanya tambahkan filter intent khusus 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

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

Troubleshooting

`providerId is required`

Setiap metode OAuth2 memerlukan kunci penyedia yang dikonfigurasi:

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

`OAuth2 provider "xxx" not configured`

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

Perbedaan URL Redirect

Bandingkan URL redirect yang dikonfigurasi di aplikasi dan dashboard penyedia karakter per karakter.
Perhatikan titik seru di akhir, kesalahan skema, dan host yang berbeda.
Pastikan URL skema aplikasi mobile terdaftar sebelum melakukan pengujian di perangkat.

Tidak ada token refresh yang dikembalikan

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

Mengatasi Masalah Token Tukar

Mengaktifkan logsEnabled: true untuk memeriksa URL yang dihasilkan dan detail pengubahan token.

Teruskan dari Pengguna OAuth2 Umum

Jika Anda menggunakan Pengguna OAuth2 Umum untuk merencanakan autentikasi dan alur akun, hubungkannya dengan Menggunakan @capgo/capacitor-login-sosial untuk kemampuan asli dalam Menggunakan @capgo/capacitor-login-sosial, @capgo/capacitor-login-sosial untuk detail implementasi dalam @capgo/capacitor-login-sosial, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey @capgo/capacitor-native-biometric untuk detail implementasi di @capgo/capacitor-native-biometric, dan Autentikasi Dua Faktor untuk detail implementasi di Autentikasi Dua Faktor.