Penyedia Oauth2 umum

Pendahuluan

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

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

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

Bagian berjudul “Apa yang Anda butuhkan”

ID klien OAuth Anda

• URL redirect yang sesuai dengan skema aplikasi atau URL panggilan balik web Anda
• URL yang Anda gunakan untuk mengarahkan pengguna ke penyedia OAuth Anda
• Endpoint otorisasi
• Endpoint token untuk aliran otorisasi code atau issuerUrl untuk penemuan OIDC
• Skop yang dibutuhkan aplikasi Anda, seperti openid profile email

Konfigurasi multi-providder

Gunakan SocialLogin.initialize() sekali selama aplikasi startup dan daftarkan setiap penyedia yang dibutuhkan:

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

Jika penyedia Anda menampilkan dokumen penemuan OpenID Connect, issuerUrl adalah konfigurasi 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 pengaturan pengganti permintaan autentikasi
• additionalTokenParameters untuk pengaturan pengganti tukar token
• additionalResourceHeaders untuk header endpoint sumber daya yang disesuaikan
• additionalLogoutParameters dan postLogoutRedirectUrl untuk aliran keluar
• loginHint, prompt, dan 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 yang dibutuhkan memiliki endpoint yang khusus, baik override-nya di preset atau lewati preset dan atur penyedia secara langsung di oauth2.

Opsi Konfigurasi

Pilihan	Jenis	Diperlukan	Deskripsi
appId / clientId	string	Ya	Identifikasi klien OAuth2
issuerUrl	string	Tidak	URL dasar penemuan OIDC
authorizationBaseUrl / authorizationEndpoint	string	Ya*	URL endpoint otorisasi
accessTokenEndpoint / tokenEndpoint	Bahasa Indonesia	Tidak	URL Endpoint Token
redirectUrl	Bahasa Indonesia	Ya	URL Panggilan Balik
scope / scopes	string / string[]	Tidak	Istilah yang Dibutuhkan
pkceEnabled	boolean	Tidak	__CAPGO_KEEP_0__ true
responseType	'code' atau 'token'	Tidak	Default 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 alih arah setelah keluar
additionalParameters	Record<string, string>	Tidak	Parameter tambahan autentikasi
additionalTokenParameters	Record<string, string>	Tidak	Parameter tambahan token
additionalResourceHeaders	Record<string, string>	Tidak	__CAPGO_KEEP_0__ untuk resourceUrl
additionalLogoutParameters	Record<string, string>	Tidak	Parameter tambahan keluar
loginHint	__CAPGO_KEEP_0__	Tidak	__CAPGO_KEEP_0__ untuk additionalParameters.login_hint
prompt	__CAPGO_KEEP_0__	Tidak	Pintasan untuk additionalParameters.prompt
iosPrefersEphemeralSession	boolean	Tidak	Menggunakan browser sementara pada iOS
logsEnabled	boolean	Tidak	Mengaktifkan pencatatan debug verbose

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

Menggunakan login OAuth2

Login

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

Aliran Redirect di Web

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

Menggunakan token refresh yang disimpan oleh plugin.

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

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

refresh() Contoh spesifik penyedia refreshToken() Salin ke clipboard

Menggunakan token refresh yang disimpan oleh plugin.

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

console.log(code.accessToken);

Salin ke clipboard

GitHub contoh

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 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 alur redirect di web, baca hasilnya kembali pada 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

Salin ke papan klip /.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);

Bagian berjudul “Bentuk respons OAuth2”

Baca hasilnya kembali pada halaman panggilan balik:

Bidang	Deskripsi
providerId	Kunci penyedia yang telah dikonfigurasi untuk login
accessToken	Isi token akses atau null
idToken	Token ID OIDC jika penyedia mengembalikannya
refreshToken	Token refresh jika ruang lingkup yang diminta memungkinkannya
resourceData	JSON mentah yang diambil dari resourceUrl
scope	Ruangan yang diberikan
tokenType	Biasanya bearer
expiresIn	Masa hidup token dalam detik

Referensi pengaturan penyedia

GitHub

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

2. Atur URL panggil 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',
       },
     },
   });

Azure AD / ID Microsoft Entra

1. Daftarkan aplikasi Buka Azure Portal, buka App registrations, dan daftarkan aplikasi native atau aplikasi seluler.

2. Tambahkan URI redirect Tambahkan URI redirect seluler atau desktop yang sesuai dengan URL panggilan balik 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 tenant Anda jika aplikasi Anda adalah aplikasi single-tenant.

Auth0

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

2. Tentukan URL panggilan balik yang diizinkan Tambahkan URL redirect yang tepat 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. Buat aplikasi OIDC native Dalam Okta Admin Console, buatlah Aplikasi OIDC Native.

2. Tambahkan URI pengalihan Anda Daftarkan URL panggil balik 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

Salin ke clipboard 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,
    },
  },
});

Catatan spesifik platform

Jika penyedia Anda mendukung penemuan OpenID Connect, prefer

iOS

• Plugin ini menggunakan ASWebAuthenticationSession.
• Tetapkan iosPrefersEphemeralSession: true Jika Anda ingin sesi browser pribadi tanpa cookie yang dibagikan.

Android

• Pengalihan OAuth kembali melalui skema aplikasi dan host Anda.
• Pastikan URL panggilan balik penyedia persis cocok dengan pengaturan tautan dalam aplikasi Android Anda.
• Plugin ini sudah menghandle aktivitas OAuth. Tambahkan hanya filter intent yang diinginkan jika aplikasi Anda memerlukan pola pengalihan yang berbeda.

Web

• Aliran popup adalah default dan berfungsi baik untuk aplikasi satu halaman.
• Aliran redirect lebih baik ketika penyedia memblokir popup atau aturan autentikasi Anda memerlukan navigasi tingkat atas.
• Beberapa penyedia memblokir pertukaran token browser langsung dengan CORS. Dalam kasus tersebut, gunakan pertukaran backend atau pengaturan penyedia yang memungkinkan klien publik.

Praktik keamanan terbaik

1. Gunakan PKCE Tetapkan pkceEnabled: true untuk klien publik.

2. Prefer aliran autentikasi code responseType: 'code' lebih aman daripada aliran implisit.

3. Validasi token di backend Anda Dekode dan verifikasi issuer, audience, expiration, dan tanda tangan di server.

4. Simpan token refresh secara aman Untuk aplikasi native, pair plugin ini dengan @capgo/capacitor-akun-tetap.

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

Pengaturan

providerId is required

Setiap metode OAuth2 memerlukan kunci penyedia yang dikonfigurasi:

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

OAuth2 provider "xxx" not configured

Panggil SocialLogin.initialize() sebelum login dan pastikan itu providerId sesuai dengan kunci objek di bawah oauth2.

Tidak Sesuai URL Redirect

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

Tidak Dapat Diperoleh Token Refresh

Hampir semua penyedia hanya mengembalikan token refresh ketika Anda meminta skop seperti offline_access atau secara eksplisit memaksa persetujuan. Tinjau kebijakan penyedia khusus.

Mengembangkan Pertukaran Token

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

Dokumen terkait

• Mulai menggunakan Social Login
• Migrasi Ionic Auth Connect