Pemasok OAuth2 Umum

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

Pendahuluan

Plugin Login Sosial Capgo mencakup mesin OAuth2 dan OpenID Connect yang dibangun secara internal. Anda dapat menggunakan fitur ini untuk menghubungkan penyedia identitas berbasis standar, termasuk:

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

Konfigurasi ini berbasis multi-provider secara desain. Anda dapat mendaftarkan beberapa penyedia secara bersamaan dan kemudian memilih salah satu pada saat login dengan oauth2 Apa yang Anda butuhkan providerId.

Bab berjudul “Apa yang Anda butuhkan”

ID klien OAuth Anda

URL redirect yang sesuai dengan skema aplikasi Anda atau URL panggilan balik web
Endpoint otorisasi
Endpoint token untuk aliran otorisasi __CAPGO_KEEP_0__ atau
A token endpoint for authorization code flow, or an issuerUrl Skop yang aplikasi Anda butuhkan, seperti
Konfigurasi multi-provider openid profile email

Konfigurasi ini berbasis multi-provider secara desain. Anda dapat mendaftarkan beberapa penyedia secara bersamaan dan kemudian memilih salah satu pada saat login dengan

Gunakan SocialLogin.initialize() sekali selama proses startup aplikasi 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 pengaturan auth request override
additionalTokenParameters untuk pengaturan token exchange override
additionalResourceHeaders untuk header endpoint resource kustom
additionalLogoutParameters dan postLogoutRedirectUrl untuk aliran logout
loginHint, prompt, dan iosPrefersEphemeralSession

Preset yang 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 didukung:

auth0
azure
cognito
okta
onelogin

Jika penyedia memerlukan endpoint yang diatur secara khusus, Anda dapat menggantinya di preset atau mengabaikan preset dan mengonfigurasi penyedia secara langsung di oauth2.

Pilihan konfigurasi

Pilihan	Tipe	Diperlukan	Deskripsi
`appId` / `clientId`	string	Ya	Identifikasi klien OAuth2
`issuerUrl`	string	Tidak	URL dasar penemuan OIDC
`authorizationBaseUrl` / `authorizationEndpoint`	string	Ya*	URL endpoint otorisasi
`accessTokenEndpoint` / `tokenEndpoint`	string	Tidak*	URL endpoint token
`redirectUrl`	string	Ya	URL Panggilan Balik
`scope` / `scopes`	string / string[]	Tidak	Skop yang Diminta
`pkceEnabled`	boolean	Tidak	Bertumpuk dengan `true`
`responseType`	`'code'` atau `'token'`	Tidak	Bertumpuk dengan `'code'`
`resourceUrl`	string	Tidak	Informasi pengguna atau endpoint sumber daya
`logoutUrl` / `endSessionEndpoint`	string	Tidak	URL logout atau akhir-sesi
`postLogoutRedirectUrl`	string	Tidak	URL arahan setelah logout
`additionalParameters`	`Record<string, string>`	Tidak	Parameter permintaan autentikasi tambahan
`additionalTokenParameters`	`Record<string, string>`	Tidak	Parameter permintaan token tambahan
`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	Tidak	Mengutamakan sesi browser sementara pada iOS
`logsEnabled`	boolean	Tidak	Aktifkan pengembangan debug verbose

authorizationBaseUrl dan accessTokenEndpoint hanya opsional ketika issuerUrl Menggunakan login OAuth2

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

__CAPGO_KEEP_0__

Gunakan flow: 'redirect' jika Anda ingin pengalihan halaman penuh 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 refres

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() memungkinkan Anda untuk melewati token refresh sendiri dan mengembalikan respons OAuth2 yang segar.

Ambil Token Akses Saat Ini

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

console.log(code.accessToken);

Contoh-contoh yang spesifik untuk penyedia

Contoh GitHub

Gunakan GitHub ketika Anda ingin aliran aplikasi OAuth yang 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

Gunakan 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

Pilih 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

Field	Deskripsi
`providerId`	Kunci penyedia yang dikonfigurasi digunakan untuk login
`accessToken`	Isi token akses atau `null`
`idToken`	Token ID OIDC jika penyedia mengembalikannya
`refreshToken`	Jika skop yang diminta memungkinkannya, refresh token
`resourceData`	JSON mentah yang diambil dari `resourceUrl`
`scope`	Skop yang diberikan
`tokenType`	Biasanya `bearer`
`expiresIn`	Masa hidup token dalam detik

Referensi pengaturan penyedia

Bagian berjudul “GitHub”

Buka __CAPGO_KEEP_0__ Pengaturan Pengembang GitHub Developer Settings dan buatlah aplikasi OAuth baru.
Atur 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',
    },
  },
});

Azure AD / Microsoft Entra ID

Daftarkan aplikasi Buka Azure Portal, buka App registrations, dan buatlah registrasi aplikasi native atau mobile.
Tambahkan URI redirect Tambahkan URI redirect mobile atau desktop yang sesuai dengan URL panggilan balik 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 native Buka Auth0 Dashboard dan buatlah aplikasi Native.
Set URL Callback yang Diperbolehkan 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',
    },
  },
});

Okta

Buat Aplikasi OIDC Asli Dalam Console Admin Okta, buatlah Aplikasi OIDC Asli.
Tambahkan URI Redirect Anda Daftarkan URL Callback yang Tepat 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, gunakan 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 dan host aplikasi Anda.
Pastikan URL panggil balik penyedia tepat sama dengan pengaturan tautan dalam aplikasi Android Anda.
Plugin sudah menghandle aktivitas OAuth. Tambahkan filter intent khusus hanya 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 penyedia memblokir popup atau aturan autentikasi Anda memerlukan navigasi tingkat atas.
Beberapa penyedia memblokir pertukaran token browser langsung dengan CORS. Dalam kasus tersebut, gunakan pertukaran backend atau pengaturan penyedia yang memungkinkan klien publik.

Praktik keamanan terbaik

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

Mengatasi Masalah

`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 providerId sama dengan kunci objek di bawah oauth2.

Tidak Sama URL Redirect

Bandingkan URL redirect yang dikonfigurasi di aplikasi dan dashboard penyedia karakter per karakter.
Perhatikan adanya tanda slash di akhir URL, kesalahan skema, dan host yang berbeda.
Pastikan URL skema aplikasi seluler terdaftar sebelum melakukan pengujian di perangkat.

Tidak ada token refresh yang dikembalikan

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

Bab berjudul “Pengujian Token”

di konfigurasi penyedia untuk memeriksa URL yang dihasilkan dan detail pengubahan token. logsEnabled: true Dokumen terkait

Lanjutkan dari Penggunaan Provider OAuth2 Umum

Jika Anda menggunakan Penggunaan Provider OAuth2 Umum untuk merencanakan autentikasi dan alur akun, hubungkannya dengan Menggunakan @capgo/capacitor-login-sosial untuk kemampuan asli dalam Menggunakan @capgo/capacitor-login-sosial, Menggunakan @capgo/capacitor-login-sosial untuk detail implementasi dalam @capgo/capacitor-login-sosial, Menggunakan @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.