Pemasok OAuth2 Umum

Pengenalan

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

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

Konfigurasi ini berbasis multi-provder secara desain. Anda dapat mendaftarkan beberapa penyedia secara bersamaan dan kemudian memilih salah satu pada saat login dengan oauth2 Apakah yang Anda butuhkan providerId.

Bab berjudul “Apakah yang Anda butuhkan”

ID klien OAuth Anda

• URL redirect yang sesuai dengan skema aplikasi Anda atau URL panggilan balik web
• Endpoint otorisasi
• Endpoint token untuk aliran otorisasi __CAPGO_KEEP_0__ atau
• A token endpoint for authorization code flow, or an issuerUrl Skop yang diperlukan aplikasi Anda, seperti
• Konfigurasi multi-provder openid profile email

Konfigurasi multi-provder secara desain ini memungkinkan Anda mendaftarkan beberapa penyedia secara bersamaan dan kemudian memilih salah satu pada saat login dengan mudah.

Gunakan SocialLogin.initialize() satu kali 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',
      },
    },
  },
});

Penemuan 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 penggantian permintaan autentikasi
• additionalTokenParameters untuk penggantian tukar token
• additionalResourceHeaders untuk header endpoint sumber daya kustom
• additionalLogoutParameters dan postLogoutRedirectUrl untuk alur 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 memerlukan endpoint khusus, Anda dapat menggantinya di preset atau mengabaikan preset dan mengonfigurasi penyedia secara langsung di oauth2.

Opsi Konfigurasi

Opsi	Tipe	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	string	Tidak*	URL endpoint token
redirectUrl	string	Ya	URL Panggilan Balik
scope / scopes	string / string[]	Tidak	Skop yang Diminta
pkceEnabled	boolean	Tidak	Default ke true
responseType	'code' atau 'token'	Tidak	Default ke 'code'
resourceUrl	string	Tidak	Informasi pengguna atau endpoint sumber daya
logoutUrl / endSessionEndpoint	string	Tidak	URL logout atau akhir-sesi
postLogoutRedirectUrl	string	Tidak	URL arahan setelah logout
additionalParameters	Record<string, string>	Tidak	Parameter permintaan autentikasi tambahan
additionalTokenParameters	Record<string, string>	Tidak	Parameter permintaan token tambahan
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	Tidak	Mengutamakan sesi browser sementara pada iOS
logsEnabled	boolean	Tidak	Aktifkan pencatatan debug verbose

authorizationBaseUrl dan accessTokenEndpoint hanya opsional ketika issuerUrl 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 pengalihan halaman penuh 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 refres

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

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

refresh() menggunakan token refresh yang disimpan oleh plugin. refreshToken() memungkinkan Anda melewati token refresh 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 yang spesifik

Contoh GitHub

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 memerlukan 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 memerlukan OIDC plus audiens kustom API :

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

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

Field	Deskripsi
providerId	Kunci penyedia yang diatur untuk login
accessToken	Token akses payload atau null
idToken	Token ID OIDC jika penyedia mengembalikan satu
refreshToken	Refresh token jika ruang lingkup yang diminta memungkinkannya
resourceData	JSON mentah diambil dari resourceUrl
scope	Ruang lingkup yang diberikan
tokenType	Biasanya bearer
expiresIn	Masa hidup token dalam detik

Referensi pengaturan penyedia

GitHub

1. Buat aplikasi OAuth Buka GitHub Pengaturan Pengembang Membuat aplikasi OAuth baru.

2. Setel URL panggilan balik Pakai 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',
       },
     },
   });

ID Azure AD / Microsoft Entra

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

2. Tambahkan URI redirect Tambahkan URI redirect mobile 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 berbasis single-tenant.

Auth0

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

2. Set URL Callback yang Diperbolehkan 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 Di Konsole Admin Okta, buatlah Aplikasi OIDC Native.

2. Tambahkan URI Redirect Anda. Daftarkan URL Callback yang Tepat 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, 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 penemuan tidak tersedia, konfigurasi endpoint otorisasi dan token secara manual.

Catatan spesifik platform

iOS

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

Android

• OAuth mengarahkan kembali melalui skema dan host aplikasi Anda.
• Pastikan URL panggil balik penyediaan Anda tepat sama dengan pengaturan tautan dalam aplikasi Android Anda.
• Plugin sudah menghandle aktivitas OAuth. Tambahkan hanya filter intent yang diinginkan jika aplikasi Anda memerlukan pola redirect yang berbeda.

Web

• Aliran popup adalah default dan berfungsi baik untuk aplikasi single-page.
• 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 Simpan pkceEnabled: true untuk klien publik.

2. Lebih baik gunakan aliran code untuk autentikasi 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 dengan aman Untuk aplikasi native, pair plugin ini dengan @capgo/capacitor-akun-persistent.

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

[Troubleshooting]

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

Tidak Sesuai URL Redirect

• Bandingkan URL redirect yang dikonfigurasi di aplikasi dan dashboard penyedia karakter per karakter.
• Perhatikan adanya tanda slash di 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

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

Bab berjudul “Pengujian Token”

di konfigurasi penyedia untuk memeriksa URL yang dihasilkan dan detail pengubahan token. logsEnabled: true Dokumen terkait

Bab berjudul “Dokumen terkait”

• Mulai dengan Login Sosial
• Migrasi Ionic Auth Connect

Teruskan dari Provider OAuth2 Generic

Jika Anda menggunakan Provider OAuth2 Generic untuk merencanakan alur autentikasi dan 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-sosial, @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.