Penyedia OAuth2 Umum

Pendahuluan

Plugin Capgo Social Login sudah dilengkapi engine OAuth2 dan OpenID Connect bawaan. Anda bisa memakainya untuk terhubung ke penyedia identitas berbasis standar apa pun, termasuk:

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

Panduan oauth2 konfigurasi ini memang dirancang multi-provider. Anda bisa mendaftarkan beberapa provider sekaligus, lalu memilih salah satunya saat login dengan providerId.

Yang Anda butuhkan

Sebelum mengonfigurasi provider, siapkan:

• OAuth client ID Anda
• Redirect URL yang sesuai dengan app scheme atau web callback URL Anda
• Authorization endpoint
• Token endpoint untuk alur otorisasi code, atau issuerUrl untuk OIDC discovery
• Scope yang dibutuhkan app Anda, seperti openid profile email

Konfigurasi multi-provider

Gunakan SocialLogin.initialize() sekali saat app startup dan daftarkan setiap provider 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',
      },
    },
  },
});

OIDC discovery dan alias

Jika provider Anda menyediakan dokumen discovery OpenID Connect, issuerUrl adalah setup termudah:

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

Tersedia juga:

• additionalParameters untuk override request auth
• additionalTokenParameters untuk override token exchange
• additionalResourceHeaders untuk header endpoint resource kustom
• additionalLogoutParameters dan postLogoutRedirectUrl untuk flow logout
• loginHint, prompt, dan iosPrefersEphemeralSession

Preset kompatibel Auth Connect

Jika Anda migrasi dari Ionic Auth Connect dan ingin tetap menggunakan nama provider 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 provider preset yang didukung:

• auth0
• azure
• cognito
• okta
• onelogin

Jika provider membutuhkan endpoint kustom, Anda bisa menimpanya di preset atau melewati preset dan mengonfigurasi provider secara langsung di oauth2.

Opsi konfigurasi

Opsi	Tipe	Wajib	Deskripsi
appId / clientId	string	Ya	OAuth2 client identifier
issuerUrl	string	Tidak	Base URL discovery OIDC
authorizationBaseUrl / authorizationEndpoint	string	Ya*	URL endpoint Authorization
accessTokenEndpoint / tokenEndpoint	string	Tidak*	URL endpoint Token
redirectUrl	string	Ya	URL Callback
scope / scopes	string / string[]	Tidak	Scope yang diminta
pkceEnabled	boolean	Tidak	Default-nya true
responseType	'code' atau 'token'	Tidak	Default-nya 'code'
resourceUrl	string	Tidak	Endpoint info user atau resource
logoutUrl / endSessionEndpoint	string	Tidak	URL logout atau akhir sesi
postLogoutRedirectUrl	string	Tidak	URL redirect setelah logout
additionalParameters	Record<string, string>	Tidak	Parameter tambahan request auth
additionalTokenParameters	Record<string, string>	Tidak	Parameter tambahan request token
additionalResourceHeaders	Record<string, string>	Tidak	Header tambahan untuk resourceUrl
additionalLogoutParameters	Record<string, string>	Tidak	Parameter tambahan logout
loginHint	string	Tidak	Shortcut untuk additionalParameters.login_hint
prompt	string	Tidak	Shortcut untuk additionalParameters.prompt
iosPrefersEphemeralSession	boolean	Tidak	Gunakan sesi browser ephemeral di iOS
logsEnabled	boolean	Tidak	Aktifkan verbose debug logging

authorizationBaseUrl dan accessTokenEndpoint hanya bersifat opsional saat issuerUrl sudah cukup untuk discovery. Endpoint eksplisit akan selalu mengalahkan nilai hasil discovery.

Menggunakan login OAuth2

Masuk

const result = await SocialLogin.login({
  provider: 'oauth2',
  options: {
    providerId: 'github',
    scope: 'read:user user:email',
    loginHint: 'user@example.com',
  },
});

Alur redirect di web

Gunakan flow: 'redirect' jika Anda ingin redirect satu halaman penuh alih-alih popup:

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

Pada halaman yang menerima callback, parse 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',
});

Refresh token

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

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

refresh() menggunakan refresh token yang disimpan oleh plugin. refreshToken() memungkinkan Anda memasukkan refresh token sendiri dan mengembalikan respons OAuth2 yang baru.

Dapatkan access token saat ini

const code = await SocialLogin.getAuthorizationCode({
  provider: 'oauth2',
  providerId: 'github',
});

console.log(code.accessToken);

Contoh per provider

Contoh GitHub

Gunakan GitHub jika Anda ingin alur OAuth app yang 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 saat 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 sangat cocok jika Anda membutuhkan OIDC plus API audience kustom:

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 menggunakan redirect flow di web, baca hasilnya kembali pada callback page:

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 discovery saat provider Anda mempublikasikannya /.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);

Struktur respons OAuth2

Login OAuth2 yang berhasil mengembalikan:

Kolom	Deskripsi
providerId	Key provider yang dikonfigurasi untuk login
accessToken	Payload access token atau null
idToken	OIDC ID token jika provider menyediakannya
refreshToken	Refresh token jika scope yang diminta mengizinkan
resourceData	Raw JSON yang diambil dari resourceUrl
scope	Scope yang diberikan
tokenType	Biasanya bearer
expiresIn	Masa berlaku token (detik)

Referensi setup provider

GitHub

1. Buat aplikasi OAuth Buka Pengaturan Developer GitHub dan buat OAuth App baru.

2. Atur callback URL Gunakan redirect URL aplikasi Anda, contohnya 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',
       },
     },
   });

Azure AD / Microsoft Entra ID

1. Daftarkan aplikasi Buka Azure Portal, App registrationsdan buat registrasi aplikasi native atau mobile.

2. Tambahkan redirect URI Tambahkan redirect URI mobile atau desktop yang sesuai dengan callback URL 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 tenant ID Anda jika aplikasi Anda single-tenant.

Auth0

1. Buat aplikasi native Buka Dashboard Auth0 dan buat aplikasi Native.

2. Atur allowed callback URLs Tambahkan redirect URL persis seperti yang digunakan 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. Buat aplikasi native OIDC Di Okta Admin Console, buatlah OIDC Native Application.

2. Tambahkan redirect URI Anda Daftarkan callback URL 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 custom OIDC provider

Jika provider Anda mendukung OpenID Connect discovery, sebaiknya gunakan 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 discovery tidak tersedia, konfigurasi endpoint otorisasi dan token secara manual.

Catatan khusus platform

iOS

• Plugin ini menggunakan ASWebAuthenticationSession.
• Atur iosPrefersEphemeralSession: true jika Anda ingin sesi browser privat tanpa cookie yang dibagikan.

Android

• Redirect OAuth akan kembali melalui app scheme dan host Anda.
• Pastikan callback URL provider sama persis dengan setup deep link Android Anda.
• Plugin ini sudah menangani aktivitas OAuth. Tambahkan custom intent filter hanya jika aplikasi Anda butuh pola redirect yang berbeda.

Web

• Popup flow adalah default dan bekerja dengan baik untuk single-page apps.
• Redirect flow lebih baik jika provider memblokir popup atau aturan auth Anda memerlukan navigasi top-level.
• Beberapa provider memblokir pertukaran token browser langsung karena CORS. Dalam kasus tersebut, gunakan backend exchange atau setup provider yang mengizinkan public clients.

Praktik terbaik keamanan

1. Gunakan PKCE Pertahankan pkceEnabled: true untuk public clients.

2. Utamakan alur authorization code responseType: 'code' lebih aman daripada implicit flow.

3. Validasi token di backend Anda Decode dan verifikasi issuer, audience, expiration, serta signature di sisi server.

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

5. Gunakan HTTPS di mana saja Endpoint auth dan logout di produksi harus selalu menggunakan HTTPS.

Pemecahan Masalah

providerId is required

Setiap metode OAuth2 memerlukan provider key yang sudah dikonfigurasi:

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

OAuth2 provider "xxx" not configured

Panggil SocialLogin.initialize() sebelum login dan pastikan providerId cocok dengan object key di bawah oauth2.

Redirect URL tidak cocok

• Bandingkan redirect URL yang dikonfigurasi di aplikasi Anda dan dashboard provider karakter demi karakter.
• Perhatikan trailing slash, ketidakcocokan scheme, dan perbedaan host.
• Pastikan URL scheme aplikasi mobile sudah terdaftar sebelum testing di device.

Refresh token tidak dikembalikan

Sebagian besar provider hanya mengembalikan refresh token saat Anda meminta scope seperti offline_access atau memaksa persetujuan secara eksplisit. Periksa kebijakan khusus provider.

Debugging pertukaran token

Aktifkan logsEnabled: true pada konfigurasi provider untuk memeriksa URL yang dihasilkan dan detail token exchange.

Dokumentasi terkait

• Memulai Social Login
• Migrasi Ionic Auth Connect

Lanjutkan dari Provider OAuth2 Generik

Jika Anda menggunakan Penyedia OAuth2 Umum untuk merencanakan alur autentikasi dan akun, hubungkan dengan Menggunakan @capgo/capacitor-social-login untuk kapabilitas native di Menggunakan @capgo/capacitor-social-login, @capgo/capacitor-social-login untuk detail implementasi di @capgo/capacitor-social-login, @capgo/capacitor-passkey untuk detail implementasi di @capgo/capacitor-passkey, @capgo/capacitor-native-biometric untuk detail implementasi di @capgo/capacitor-native-biometric, dan Autentikasi dua faktor untuk detail implementasi di autentikasi dua faktor.