Provider OAuth2 Umum

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
• Indonesia
• Plugin

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

Apakah yang Anda butuhkan

Sebelum Anda mengonfigurasi penyedia, kumpulkan:

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

Konfigurasi multi-providernya

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

Pencarian OIDC dan alias-aliasnya

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 permintaan autentikasi
• additionalTokenParameters untuk penggantian token
• additionalResourceHeaders untuk header endpoint sumber daya yang disesuaikan
• 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 Dibantu:

• auth0
• azure
• cognito
• okta
• onelogin

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

Pilihan Konfigurasi

Jenis	Diperlukan	Deskripsi	Section titled “Configuration options”
appId / clientId	Klien Identifier OAuth2	Ya	Identifier Klien OAuth2
issuerUrl	string	Tidak	URL Penemuan OIDC
authorizationBaseUrl / authorizationEndpoint	Ya*	URL Endpoint Otorisasi	string
accessTokenEndpoint / tokenEndpoint	Tidak*	URL Endpoint Token	__CAPGO_KEEP_0__
redirectUrl	String	Ya	URL Panggilan Balik
scope / scopes	String / String[]	Tidak	Skop yang Diminta
pkceEnabled	Boolean	Tidak	Atau true
responseType	'code' Tidak 'token'	Atau	atau 'code'
resourceUrl	Informasi pengguna atau endpoint sumber daya	Tidak	URL untuk keluar atau akhir sesi
logoutUrl / endSessionEndpoint	Tidak	URL untuk diarahkan setelah keluar	Tidak
postLogoutRedirectUrl	Parameter tambahan permintaan autentikasi	Tidak	__CAPGO_KEEP_0__
additionalParameters	Record<string, string>	__CAPGO_KEEP_1__	__CAPGO_KEEP_2__
additionalTokenParameters	Record<string, string>	__CAPGO_KEEP_3__	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	Tidak	Mengaktifkan Pemantauan Debug yang Rinci

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

Menggunakan Login OAuth2

Masuk

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

Status login dan logout

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

Pakai Azure ketika kamu 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 kamu 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 kamu 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

Penggunaan OAuth2 sukses kembali:

Kolom	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	Ruangan lingkup yang diberikan
tokenType	Biasanya bearer
expiresIn	Umur token dalam detik

Referensi pengaturan penyedia

GitHub

1. Buat aplikasi OAuth Buka GitHub Pengaturan Pengembang dan buat aplikasi OAuth baru.

2. Setel URL panggilan balik Gunakan URL redirect aplikasi Anda, misalnya myapp://oauth/github.

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

AD Azure / ID Microsoft Entra

1. Mendaftarkan aplikasi Pergi ke Portal Azure, buka App registrations, dan buat pendaftaran aplikasi native atau mobile.

2. Tambahkan URI pengalihan Tambahkan URI pengalihan mobile atau desktop yang sesuai dengan URL panggilan aplikasi Anda.

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

   Catatan

   Ganti common dengan ID penyewa Anda jika aplikasi Anda adalah aplikasi tunggal.

Auth0

1. Buat aplikasi asli Buka Auth0 Dashboard dan buatlah aplikasi Native.

2. Setel URL panggilan yang diizinkan Tambahkan URL redirect yang tepat yang digunakan oleh aplikasi Capacitor Anda.

3. 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

1. Buatlah aplikasi OIDC Native Dalam Console Admin Okta, buatlah Aplikasi OIDC Native.

2. Tambahkan URI redirect Anda Daftarkan URL callback yang tepat yang digunakan oleh aplikasi Anda.

3. 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.
• Konfigurasi iosPrefersEphemeralSession: true Jika Anda ingin sesi browser pribadi tanpa cookie yang dibagikan.

Sistem Android

• arah OAuth kembali melalui skema aplikasi dan host Anda.
• Pastikan URL panggilan provider Anda sesuai dengan pengaturan tautan dalam aplikasi Android Anda.
• Plugin ini sudah mengelola aktivitas OAuth. Hanya tambahkan filter intent khusus jika aplikasi Anda memerlukan pola redirect yang berbeda.

Sistem Web

• Aliran popup adalah default dan berfungsi baik untuk aplikasi berbasis halaman tunggal.
• 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

1. Pakai PKCE Simpan pkceEnabled: true untuk klien publik.

2. Gunakan aliran code untuk otorisasi responseType: 'code' aliran otorisasi ini lebih aman daripada aliran implisit.

3. Validasi token di backend Anda Decod dan verifikasi issuer, audience, expiration, dan signature di server.

4. Simpan token refresh dengan aman Untuk aplikasi native, pairkan plugin ini dengan @capgo/capacitor-akun-persistent.

5. Gunakan HTTPS di mana-mana Endpoint autentikasi produksi dan endpoint keluar harus selalu menggunakan HTTPS.

Pembelajaran

providerId is required

Salin ke papan klip

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

OAuth2 provider "xxx" not configured

Kunci penyedia OAuth2 "xxx" belum dikonfigurasi SocialLogin.initialize() Panggil providerId sebelum login dan pastikan bahwa oauth2.

sesuai dengan kunci objek di bawahnya,

• Bandikan URL redirect yang telah diatur di aplikasi dan dashboard penyedia karakter per karakter.
• Perhatikan tanda baca akhir, kesalahan 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 offline_access atau secara eksplisit memaksa persetujuan. Tinjau kebijakan penyedia yang spesifik.

Pengujian Token

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

Rujukan dokumen

• Mulai menggunakan Login Sosial
• Migrasi Ionic Auth Connect

Teruskan 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 native di Menggunakan @capgo/capacitor-login-sosial, @capgo/capacitor-login-sosial 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.