Otorisasi OAuth2 Generic

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

Pengenalan

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

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

Aplikasi oauth2 Konfigurasi adalah multi-provder oleh desain. Anda dapat mendaftarkan beberapa penyedia sekaligus dan kemudian memilih satu pada saat login dengan providerId.

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 alur otorisasi __CAPGO_KEEP_0__ atau
A token endpoint for authorization code flow, or an issuerUrl Skop yang diperlukan aplikasi Anda, seperti
Konfigurasi Multi-Provider openid profile email

Apa yang Anda butuhkan

Gunakan SocialLogin.initialize() satu kali selama aplikasi startup dan daftar 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 override permintaan autentikasi
additionalTokenParameters untuk pengaturan override pertukaran token
additionalResourceHeaders untuk header endpoint sumber daya kustom
additionalLogoutParameters dan postLogoutRedirectUrl untuk aliran keluar
loginHint, promptdan 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 khusus, baiklah menggantinya di preset atau lewati preset dan atur penyedia secara langsung di oauth2.

Pilihan konfigurasi

Pilihan	Tipe	Diperlukan	Deskripsi
`appId` / `clientId`	string	Ya	Identifikasi klien OAuth2
`issuerUrl`	Bahasa Indonesia	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 ruang lingkup yang diminta
`pkceEnabled`	boolean	Tidak	Default ke `true`
`responseType`	`'code'` atau `'token'`	Tidak	Default ke `'code'`
`resourceUrl`	string	Tidak	Informasi pengguna atau endpoint sumber daya
`logoutUrl` / `endSessionEndpoint`	string	Tidak	URL Logout atau akhir-sesi
`postLogoutRedirectUrl`	string	Tidak	URL Redirect setelah logout
`additionalParameters`	`Record<string, string>`	Tidak	Parameter tambahan permintaan autentikasi
`additionalTokenParameters`	`Record<string, string>`	Tidak	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	Tidak	Lebih suka sesi browser sementara pada iOS
`logsEnabled`	boolean	Tidak	Aktifkan verbose debug logging

authorizationBaseUrl dan accessTokenEndpoint hanya optional 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

Jika Anda ingin melakukan redirect halaman penuh bukan popup: flow: 'redirect' Salin ke clipboard

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

Salin ke clipboard

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

Judul bagian “Token refresh”

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

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

refresh() Jika Anda ingin melakukan redirect halaman penuh bukan popup: refreshToken() Mengizinkan Anda 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 Provider-Spesifik

Contoh GitHub

Gunakan 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

Gunakan Azure ketika Anda memerlukan 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 memerlukan 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

Field	Pengertian
`providerId`	Kunci penyedia yang dikonfigurasi digunakan untuk login
`accessToken`	Token akses payload atau `null`
`idToken`	Token ID OIDC jika penyedia mengembalikannya
`refreshToken`	Token refresh jika ruang lingkup yang diminta memungkinkannya
`resourceData`	Data JSON mentah diambil dari `resourceUrl`
`scope`	Izin yang diberikan
`tokenType`	Biasanya `bearer`
`expiresIn`	Masa berlaku 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 Buka Azure Portal, 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 Auth0 Dashboard dan buatlah aplikasi Native.
Tentukan 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

Buat aplikasi OIDC asli Dalam Console Admin Okta, buat Aplikasi OIDC Asli.
Tambahkan URI redirect 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 sesi browser pribadi tanpa kuki yang dibagikan.

Android

Pengalihan OAuth kembali melalui skema dan host aplikasi Anda.
Pastikan URL panggilan provider Anda tepat sama dengan pengaturan tautan dalam aplikasi Android Anda.
Plugin sudah menghandle aktivitas OAuth. Hanya tambahkan filter intent kustom 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 menghalangi popup 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.
Preferensi aliran code lebih aman daripada aliran implisit. responseType: 'code' Validasi token di backend Anda
Menguraikan dan memeriksa emiten, audiens, kedaluwarsa, dan tanda tangan di sisi server. Simpan token refresh dengan aman
Untuk aplikasi native, pairkan plugin ini dengan @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-akun-persistent @capgo/capacitor-persistent-account.
Endpoint autentikasi produksi dan logout harus selalu menggunakan HTTPS. Pengaturan Masalah

Pengaturan Masalah

`providerId is required`

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

Tidak Cocoknya URL Redirect

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

Tidak ada token refresh yang dikembalikan

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

Pengujian Token

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

Teruskan dari Pengguna OAuth2 Umum

Jika Anda menggunakan Pengguna OAuth2 Umum untuk merencanakan autentikasi dan aliran akun, hubungkannya dengan Menggunakan @capgo/capacitor-login-media sosial untuk kemampuan asli dalam Menggunakan @capgo/capacitor-login-media sosial, @capgo/capacitor-login-media sosial untuk detail implementasi dalam @capgo/capacitor-login-media sosial, @capgo/capacitor-kunci akses untuk detail implementasi dalam @capgo/capacitor-kunci akses, @capgo/capacitor-biometrik native untuk detail implementasi di @capgo/capacitor-biometrik native, dan Autentikasi dua faktor untuk detail implementasi di Autentikasi dua faktor.

Otorisasi OAuth2 Generic

Pengenalan

Apa yang Anda butuhkan

Apa yang Anda butuhkan

Penemuan OIDC dan alias-alias

Preset yang kompatibel dengan Auth Connect

Pilihan konfigurasi

Menggunakan login OAuth2

Login

Aliran redirect di web

Judul bagian “Status login dan logout”

Judul bagian “Token refresh”

Ambil Token Akses Saat Ini

Contoh-Contoh Provider-Spesifik

Contoh GitHub

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 Masalah

providerId is required

OAuth2 provider "xxx" not configured

Tidak Cocoknya URL Redirect

Tidak ada token refresh yang dikembalikan

Pengujian Token

Dokumen terkait

Teruskan dari Pengguna OAuth2 Umum

`providerId is required`

`OAuth2 provider "xxx" not configured`