Provider OAuth2 Generic

Pendahuluan

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

• GitHub
• AD Azure / Microsoft Entra ID
• Auth0
• Okta
• OAuth2
• Server OAuth2 atau OIDC kustom

Konfigurasi 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 ID Klien OAuth Anda
• Skop yang dibutuhkan aplikasi Anda, seperti openid profile email

Konfigurasi multi-provder

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

Pengenalan OIDC dan alias

Jika penyedia Anda menampilkan dokumen pengenalan 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 sebagai alias dari scope

Juga tersedia:

• additionalParameters untuk penggantian permintaan autentikasi
• additionalTokenParameters untuk penggantian pertukaran token
• additionalResourceHeaders untuk pengaturan header endpoint sumber daya kustom
• 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, baiklah menggantinya di preset atau menghindari preset dan mengkonfigurasi penyedia secara langsung di oauth2.

Pilihan Konfigurasi

Jenis	Diperlukan	Deskripsi	Salin ke clipboard
appId / clientId	ID: 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	Istilah yang Diminta
pkceEnabled	Boolean	Tidak	Atau true
responseType	'code' Tidak 'token'	Atau	Atau 'code'
resourceUrl	Informasi pengguna atau endpoint sumber daya	Tidak	URL logout atau akhir sesi
logoutUrl / endSessionEndpoint	Tidak	URL redirect setelah logout	Tidak
postLogoutRedirectUrl	Parameter tambahan permintaan autentikasi	Tidak	__CAPGO_KEEP_0__
additionalParameters	Record<string, string>	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__
additionalTokenParameters	Record<string, string>	__CAPGO_KEEP_0__	Parameter tambahan untuk permintaan token
additionalResourceHeaders	Record<string, string>	Tidak	Kepala tambahan untuk resourceUrl
additionalLogoutParameters	Record<string, string>	Tidak	Parameter tambahan untuk keluar
loginHint	string	Tidak	Singkat untuk additionalParameters.login_hint
prompt	string	Tidak	Singkat untuk additionalParameters.prompt
iosPrefersEphemeralSession	boolean	No	Menggunakan Sesi Browser Sementara di iOS
logsEnabled	boolean	No	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',
  },
});

Alirkan arus pada web

Gunakan flow: 'redirect' jika Anda ingin alirkan arus 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 Khusus 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 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

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	Jika penyedia mengembalikan satu, token ID OIDC
refreshToken	Jika skop yang diminta memungkinkannya, token refresh
resourceData	JSON mentah yang diambil dari resourceUrl
scope	Skop 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',
       },
     },
   });

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 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 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 Pada Konsole 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 sesi browser pribadi tanpa cookie yang dibagikan.

Android

• OAuth mengarahkan kembali melalui skema aplikasi dan host Anda.
• Pastikan URL panggilan provider Anda tepat sama dengan pengaturan deep link Android Anda.
• Plugin sudah menghandle aktivitas OAuth. Tambahkan hanya filter intent yang kustom jika aplikasi Anda membutuhkan pola redirect yang berbeda.

Web

• Aliran popup adalah default dan berfungsi baik untuk aplikasi single-page.
• Aliran redirect lebih baik ketika provider memblokir popup atau aturan autentikasi Anda membutuhkan 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 otorisasi 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.

Pembetulan Masalah

providerId is required

Setiap metode OAuth2 memerlukan kunci provider 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 sesuai dengan kunci objek di bawah oauth2.

Tidak Sesuai URL Redirect

• Perbandingkan URL redirect yang telah diatur di aplikasi dan dashboard penyedia karakter per karakter.
• Perhatikan titik koma belakang, 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.

Dokumen terkait

• Mulai menggunakan Social Login
• Migrasi Ionic Auth Connect

Lanjutkan dari Penggunaan Provider OAuth2 Generic

Jika Anda menggunakan Penggunaan Provider OAuth2 Generic 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-nativ untuk detail implementasi di @capgo/capacitor-biometrik-nativ, dan Dua faktor autentikasi untuk detail implementasi di Dua Faktor Autentikasi.