Provider OAuth2 Generic

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 karena itu oauth2 Konfigurasi ini dirancang untuk multi-provider. Anda dapat mendaftarkan beberapa penyedia secara bersamaan 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 Apa yang Anda butuhkan
• Skop yang dibutuhkan aplikasi Anda, seperti openid profile email

Konfigurasi multi-provder

Pakai 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-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 penggantian permintaan autentikasi
• additionalTokenParameters untuk penggantian pertukaran token
• additionalResourceHeaders untuk header endpoint sumber daya yang dapat 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 Dibuka:

• auth0
• azure
• cognito
• okta
• onelogin

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

Pilihan Konfigurasi

Jenis	Diperlukan	Deskripsi	Salin ke clipboard
appId / clientId	Klien Identifier OAuth2	Ya	Identifier Klien OAuth2
issuerUrl	string	Tidak	URL 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	Benar	Tidak	Dapat Dihubungkan ke true
responseType	'code' atau 'token'	Tidak	Dapat Dihubungkan ke 'code'
resourceUrl	String	Tidak	URL 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	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	Preferlah sesi browser sementara di iOS
logsEnabled	boolean	No	aktifkan pencatatan debug verbose

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 diatur sendiri:

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

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

Login OAuth2 sukses kembali:

Kolom	Deskripsi
providerId	Kunci penyedia yang telah dikonfigurasi digunakan untuk login
accessToken	Payload token akses atau null
idToken	Token ID OIDC jika penyedia mengembalikan satu
refreshToken	Token refresh jika ruang lingkup yang diminta memungkinkannya
resourceData	JSON mentah diambil dari resourceUrl
scope	Ruang 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 Pakai URL redirect aplikasi kamu, 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',
       },
     },
   });

Microsoft Azure / ID Entra Microsoft

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

2. Tambahkan URI redirect Tambahkan URI redirect untuk perangkat 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 native Buka Dashboard Auth0 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 panggilan 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 sebuah sesi browser pribadi tanpa cookie yang dibagikan.

Sistem Android

• OAuth mengarahkan kembali melalui skema aplikasi dan host Anda.
• Pastikan URL panggilan provider Anda sesuai dengan pengaturan deep link 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 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

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

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

3. Validasi token di backend Anda Decod dan verifikasi issuer, audience, expiration, dan tanda tangan 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

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

Tidak Cocok URL Redirect

• Bandikan URL redirect yang telah diatur di aplikasi dan dashboard penyedia karakter per karakter.
• Perhatikan tanda baca akhir, skema yang tidak sesuai, dan host yang berbeda.
• Pastikan URL skema aplikasi mobile telah terdaftar sebelum melakukan pengujian di perangkat.

Tidak Dapat Ditemukan Token Refres

Banyak penyedia hanya mengembalikan token refres ketika Anda meminta skop seperti offline_access atau secara eksplisit memaksakan persetujuan. Tinjau kebijakan penyedia yang spesifik.

Pengujian Token

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

Rujukan dokumen

• Mulai menggunakan Social Login
• Migrasi Ionic Auth Connect

Lanjutkan dari Penggunaan Provider OAuth2 Umum

Jika Anda menggunakan Penggunaan Provider OAuth2 Umum untuk merencanakan autentikasi dan alur akun, hubungkannya dengan Menggunakan @capgo/capacitor-social-login untuk kemampuan native di Menggunakan @capgo/capacitor-social-login, @capgo/capacitor-social-login 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 Autentikasi dua faktor untuk detail implementasi di Autentikasi dua faktor.