Pemberi Layanan OAuth2 Umum

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

Pengenalan

Plugin Login Sosial Capgo termasuk mesin OAuth2 dan OpenID Connect bawaan. Anda dapat menggunakan itu untuk terhubung dengan penyedia identitas berbasis standar, termasuk:

GitHub
Azure AD / Microsoft Entra ID
Auth0
Okta
Keycloak
__CAPGO_KEEP_0__

Konfigurasi ini dirancang untuk multi-providernya. Anda dapat mendaftarkan beberapa penyedia sekaligus dan kemudian memilih salah satu pada saat login dengan oauth2 Apa yang Anda butuhkan providerId.

Judul bagian “Apa yang Anda butuhkan”

ID klien OAuth Anda

URL redirect yang sesuai dengan skema aplikasi Anda atau URL panggilan balik web
Suatu endpoint otorisasi
Suatu endpoint otorisasi
Endpoint token untuk aliran otorisasi code issuerUrl untuk penemuan OIDC
Skop yang dibutuhkan aplikasi Anda, seperti openid profile email

Konfigurasi multi-providder

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

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 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 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 Juga tersedia: scope

untuk pengaturan override permintaan autentikasi

additionalParameters untuk pengaturan override tukar token
additionalTokenParameters untuk pengaturan header endpoint sumber daya kustom
additionalResourceHeaders dan
additionalLogoutParameters dan postLogoutRedirectUrl untuk aliran keluar
loginHint, prompt, dan iosPrefersEphemeralSession

Preset yang kompatibel dengan Auth Connect

Jika Anda sedang bermigrasi 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 disesuaikan, baik override mereka di preset atau lewati preset dan konfigurasi penyedia secara langsung di oauth2.

Opsi Konfigurasi

Opsi	Tipe	Wajib	Deskripsi
`appId` / `clientId`	string	Ya	Identifier 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	Istilah yang diminta
`pkceEnabled`	boolean	Tidak	Default ke `true`
`responseType`	`'code'` atau `'token'`	Tidak	Ditentukan secara default `'code'`
`resourceUrl`	string	Tidak	Informasi pengguna atau endpoint sumber daya
`logoutUrl` / `endSessionEndpoint`	string	Tidak	URL keluar atau akhir-sesi
`postLogoutRedirectUrl`	string	Tidak	URL redirect setelah keluar
`additionalParameters`	`Record<string, string>`	Tidak	Parameter tambahan untuk permintaan autentikasi
`additionalTokenParameters`	`Record<string, string>`	Tidak	Parameter tambahan untuk permintaan token
`additionalResourceHeaders`	`Record<string, string>`	Tidak	Kop sur tambahan untuk `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	Tidak	Parameter tambahan untuk logout
`loginHint`	string	Tidak	Singkat untuk `additionalParameters.login_hint`
`prompt`	string	Tidak	Pintasan untuk `additionalParameters.prompt`
`iosPrefersEphemeralSession`	boolean	Tidak	Menggunakan browser sesi sementara pada iOS
`logsEnabled`	boolean	Tidak	Mengaktifkan pencatatan debug verbose

authorizationBaseUrl dan accessTokenEndpoint hanya opsional ketika issuerUrl 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

Gunakan 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 callback, 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',
});

Mengaktifkan ulang token

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 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 spesifik penyedia

GitHub contoh

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

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 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`	__CAPGO_KEEP_0__
`accessToken`	Token akses payload atau `null`
`idToken`	Token ID OIDC jika penyedia kembali satu
`refreshToken`	Token refresh jika ruang lingkup yang diminta memungkinkannya
`resourceData`	JSON mentah yang diambil dari `resourceUrl`
`scope`	Ruangan yang diberikan
`tokenType`	Biasanya `bearer`
`expiresIn`	Masa hidup token dalam detik

Referensi pengaturan penyedia

GitHub

Buat aplikasi OAuth Buka GitHub Pengaturan Pengembang dan buat 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 Arah ke Portal Azure, buka App registrations, dan buat 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 halaman Dashboard Auth0 dan buat aplikasi Native.
Tentukan URL panggilan balik 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

Buat aplikasi OIDC native Dalam Console Admin Okta, buat Aplikasi OIDC Native.
Tambahkan URI pengalihan Anda Daftarkan URL panggil balik 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.
Tetapkan iosPrefersEphemeralSession: true Jika Anda ingin sebuah sesi browser pribadi dengan tidak ada cookie yang dibagikan.

Android

Pengalihan OAuth kembali melalui skema dan host aplikasi Anda.
Pastikan URL panggilan balik provider Anda tepat sama dengan pengaturan tautan dalam aplikasi Android Anda.
Plugin ini sudah menghandle aktivitas OAuth. Tambahkan saja filter intent yang diinginkan jika aplikasi Anda memerlukan pola pengalihan yang berbeda.

Web

Section titled “Web”
Aliran redirect lebih baik ketika penyedia menghalangi pop-up atau aturan autentikasi Anda memerlukan navigasi tingkat atas.
Beberapa penyedia menghalangi pertukaran token browser langsung dengan CORS. Dalam kasus tersebut, gunakan pertukaran backend atau pengaturan penyedia yang memungkinkan klien publik.

Praktik keamanan terbaik

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

Pengaturan

`providerId is required`

Setiap metode OAuth2 memerlukan kunci provider yang dikonfigurasi:

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

`OAuth2 provider "xxx" not configured`

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

Tidak Sesuai URL Redirect

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

Tidak Ada Token Refresh Dikembalikan

Hampir semua penyedia hanya mengembalikan token refresh ketika Anda meminta ruang lingkup seperti offline_access atau secara eksplisit memaksa persetujuan. Tinjau kebijakan khusus penyedia.

Mengembangkan Token Pertukaran

Aktifkan logsEnabled: true di konfigurasi penyedia untuk memeriksa URL yang dihasilkan dan detail pertukaran token.

Lanjutkan dari Penyedia OAuth2 Generic

Jika Anda menggunakan Penyedia OAuth2 Generic untuk merencanakan autentikasi dan alur akun, hubungkannya dengan Gunakan @capgo/capacitor-login-sosial untuk kemampuan asli di Menggunakan @capgo/capacitor-login-sosial, @capgo/capacitor-login-sosial untuk detail implementasi di @capgo/capacitor-login-sosial, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-biometrik-asli untuk detail implementasi di @capgo/capacitor-biometrik-asli, dan Autentikasi dua faktor untuk detail implementasi di Autentikasi dua faktor.

Pemberi Layanan OAuth2 Umum

Pengenalan

Judul bagian “Apa yang Anda butuhkan”

Konfigurasi multi-providder

Penemuan OIDC dan alias

Preset yang kompatibel dengan Auth Connect

Opsi Konfigurasi

Menggunakan login OAuth2

Login

Aliran redirect di web

Status login dan keluar

Mengaktifkan ulang token

Ambil token akses saat ini

Contoh spesifik penyedia

GitHub contoh

Contoh Azure AD / Microsoft Entra ID

Contoh Auth0

Contoh Okta

Contoh Keycloak

Bentuk respons OAuth2

Referensi pengaturan penyedia

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak dan penyedia OIDC kustom

Catatan spesifik platform

iOS

Android

Web

Praktik keamanan terbaik

Pengaturan

providerId is required

OAuth2 provider "xxx" not configured

Tidak Sesuai URL Redirect

Tidak Ada Token Refresh Dikembalikan

Mengembangkan Token Pertukaran

Dokumen terkait

Lanjutkan dari Penyedia OAuth2 Generic

`providerId is required`

`OAuth2 provider "xxx" not configured`