Allgemeine OAuth2-Anbieter

Einführung

Das Capgo Social Login-Plugin enthält einen integrierten OAuth2- und OpenID-Connect-Motor. Sie können ihn verwenden, um mit jedem standardsbasierten Identitätsanbieter zu verbinden, einschließlich:

• GitHub
• Azure AD / Microsoft Entra ID
• Auth0
• Okta
• Keycloak
• Benutzerdefinierte OAuth2- oder OIDC-Server

Die oauth2 Die Konfiguration ist multi-Provider-geeignet. Sie können mehrere Anbieter gleichzeitig registrieren und dann bei der Anmeldung einen auswählen. providerId.

Was Sie benötigen

Bevor Sie einen Anbieter konfigurieren, sammeln Sie:

• Ihren OAuth-Kunden-ID
• Eine Umleitungs-URL, die Ihrem App-Schema oder Web-Callback-URL entspricht
• Ein Autorisierungs-Endpunkt
• Ein Token-Endpunkt für die Autorisierung code-Fluss, oder ein issuerUrl für OIDC-Entdeckung
• Die von Ihrem Anwendungs benötigten Berechtigungen, wie openid profile email

Multi-Anbieter-Konfiguration

Verwenden Sie SocialLogin.initialize() einmal während der Anwendungsstart und registrieren Sie jeden Anbieter, den Sie benötigen:

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-Entdeckung und Aliase

Wenn Ihr Anbieter ein OpenID Connect-Entdeckungs-Dokument ausgibt, issuerUrl ist die einfachste Konfiguration:

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

Der Plugin unterstützt auch gängige OAuth- und OIDC-Aliase:

• clientId als Alias von appId
• authorizationEndpoint als Alias von authorizationBaseUrl
• tokenEndpoint als Alias von accessTokenEndpoint
• endSessionEndpoint als Alias von logoutUrl
• scopes als Alias von scope

Zusätzlich verfügbar:

• additionalParameters für Auth-Anforderungs-Überschreibungen
• additionalTokenParameters für Token-Austausch-Überschreibungen
• additionalResourceHeaders für benutzerdefinierte Ressourcen-Endpunkt-Header
• additionalLogoutParameters und postLogoutRedirectUrl für Abmeldeflows
• loginHint, prompt, und iosPrefersEphemeralSession

Auth Connect-kompatible Vorlagen

Wenn Sie von Ionic Auth Connect migrieren und die gleichen Anbieternamen beibehalten möchten, verwenden Sie 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',
    },
  },
});

Unterstützte Vorlagengeber-Provider-IDs:

• auth0
• azure
• cognito
• okta
• onelogin

Wenn ein Anbieter benutzerdefinierte Endpunkte benötigt, können Sie entweder diese in der Vorlage überschreiben oder die Vorlagen umgehen und den Anbieter direkt in der oauth2.

Konfigurationsoptionen

Option	Typ	Pflichtfeld	Beschreibung
appId / clientId	__CAPGO_KEEP_0__	Ja	OAuth2-Kundenidentifikator
issuerUrl	__CAPGO_KEEP_0__	Nein	OIDC-Entdeckungs-Base-URL
authorizationBaseUrl / authorizationEndpoint	__CAPGO_KEEP_0__	Ja*	Autorisierungsanforderungs-URL
accessTokenEndpoint / tokenEndpoint	__CAPGO_KEEP_0__	Nein*	Token-Endpunkt-URL
redirectUrl	Zeichenfolge	Ja	Callback-URL
scope / scopes	Zeichenfolge / Zeichenfolge[]	Nein	Angeforderter Berechtigungen
pkceEnabled	boolean	Nein	Standardmäßig true
responseType	'code' oder 'token'	Nein	Standardmäßig 'code'
resourceUrl	__CAPGO_KEEP_0__	Nein	Benutzerinformationen oder Ressourcen-Endpunkt
logoutUrl / endSessionEndpoint	__CAPGO_KEEP_0__	Nein	Abmelden oder Sitzungsende-URL
postLogoutRedirectUrl	__CAPGO_KEEP_0__	Nein	Umleitungs-URL nach Abmeldung
additionalParameters	Record<string, string>	Nein	Zusätzliche Auth-Request-Parameter
additionalTokenParameters	Record<string, string>	Nein	__CAPGO_KEEP_0__
additionalResourceHeaders	Record<string, string>	Nein	__CAPGO_KEEP_0__ für resourceUrl
additionalLogoutParameters	Record<string, string>	Nein	__CAPGO_KEEP_0__ für
loginHint	Zeichenkette	Nein	__CAPGO_KEEP_0__ für additionalParameters.login_hint
prompt	__CAPGO_KEEP_0__ für	__CAPGO_KEEP_0__ für	__CAPGO_KEEP_0__ additionalParameters.prompt
iosPrefersEphemeralSession	boolean	Nein	Präferieren Sie eine ephemere Browser-Sitzung auf iOS
logsEnabled	boolean	Nein	Aktivieren Sie ausführliche Debug-Protokollierung

authorizationBaseUrl und accessTokenEndpoint sind nur optional, wenn issuerUrl ist ausreichend für die Entdeckung. Explizite Endpunkte gewinnen immer über entdeckte Werte.

Mit OAuth2-Anmeldung

Anmeldung

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

Umleitung im Web aufbauen

Verwenden Sie flow: 'redirect' wenn Sie eine vollständige Seite für die Umleitung statt eines Pop-ups möchten:

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

Auf der Seite, die den Callback erhält, den Anmeldeergebnis auswerten:

const result = await SocialLogin.handleRedirectCallback();
if (result?.provider === 'oauth2') {
  console.log(result.result.providerId);
}

Anmeldestatus und Abmeldung

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

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

Aktualisierungstoken

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

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

refresh() verwendet das von dem Plugin gespeicherte Aktualisierungstoken. refreshToken() lässt Sie ein Aktualisierungstoken selbst übergeben und gibt die frische OAuth2-Antwort zurück.

Holen Sie sich das aktuelle Zugriffstoken

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

console.log(code.accessToken);

Beispiele für den Anbieter

GitHub Beispiel

Benutze GitHub wenn du einen einfachen OAuth-App-Flow und grundlegende Profilinformationen benötigst:

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

Azure AD / Microsoft Entra ID-Beispiel

Benutze Azure wenn du Microsoft-Graph-Daten wie das Benutzerprofil benötigst:

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

Auth0-Beispiel

Auth0 ist eine gute Wahl wenn du OIDC plus einen benutzerdefinierten API-Zielgruppe benötigst:

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

Wenn du auf Web den Redirect-Flow verwendest, lies die Ergebnisse auf der Callback-Seite zurück:

const auth0Result = await SocialLogin.handleRedirectCallback();
if (auth0Result?.provider === 'oauth2') {
  console.log(auth0Result.result.idToken);
}

Okta Beispiel

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

Keycloak Beispiel

Verwende Entdeckung, wenn dein Anbieter veröffentlicht /.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);

OAuth2-Antwortform

Erfolgreiche OAuth2-Anmeldungen liefern:

Feld	Beschreibung
providerId	Die konfigurierte Anbieter-Schlüssel, der für die Anmeldung verwendet wird
accessToken	Zugriffs-Token-Payload oder null
idToken	OIDC-ID-Token, wenn der Anbieter eines zurückgegeben hat
refreshToken	Refresh-Token, wenn die angeforderten Berechtigungen es erlaubten
resourceData	Rohes JSON, abgerufen von resourceUrl
scope	Eingriffsberechtigungen
tokenType	In der Regel bearer
expiresIn	Lebensdauer des Tokens in Sekunden

Referenz für die Anbieter-Einstellung

GitHub

1. Ein OAuth-Anwendung erstellen Öffnen GitHub Entwickler-Einstellungen und erstellen Sie eine neue OAuth-Anwendung.

2. Die Rückruff-URL einstellen Verwenden Sie die Redirect-URL Ihrer App, zum Beispiel myapp://oauth/github.

3. Die Plugin-Konfiguration

   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. Eine Anwendung registrieren Zum Azure-Portal gehen, öffnen App registrationsund erstelle eine native oder mobile App-Registrierung.

2. Fügen Sie den Redirect-URI hinzu Fügen Sie einen mobilen oder Desktop-Redirect-URI hinzu, der sich an Ihre App-Callback-URL anpasst.

3. Konfigurieren Sie das 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',
       },
     },
   });

   Hinweis

   Ersetzen Sie common mit Ihrem Tenant-ID, wenn Ihre App ein Single-Tenant-App ist.

Auth0

1. Erstelle eine native Anwendung Öffnen Sie das Auth0-Dashboard und erstellen Sie eine Native-App.

2. Setzen Sie die zulässigen Callback-URLs Fügen Sie die genaue Redirect-URL hinzu, die von Ihrer Capacitor-App verwendet wird.

3. Konfigurieren Sie das 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. Erstellen Sie eine OIDC-Native-App In der Okta-Admin-Konsole erstellen Sie eine OIDC-Native-Anwendung.

2. Fügen Sie Ihre Redirect-URI hinzu Registrieren Sie die genaue Callback-URL, die von Ihrer App verwendet wird.

3. Konfigurieren Sie das 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 und benutzerdefinierte OIDC-Anbieter

Wenn Ihr Anbieter OpenID Connect-Discovery unterstützt, bevorzugen Sie 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,
    },
  },
});

Wenn die Discovery nicht verfügbar ist, konfigurieren Sie die Autorisierungs- und Token-Endpunkte manuell.

Plattform-spezifische Hinweise

iOS

• The Plugin verwendet ASWebAuthenticationSession.
• Setzen iosPrefersEphemeralSession: true Wenn Sie eine private Browser-Sitzung mit keinen geteilten Cookies möchten.

Android

• OAuth-Weiterleitungen kehren durch Ihre App-Scheme und -Host zurück.
• Stellen Sie sicher, dass der Anbieter-Callback-URL genau Ihrem Android-Deep-Link-Einrichtung entspricht.
• Der Plugin verarbeitet bereits die OAuth-Aktivität. Fügen Sie nur benutzerdefinierte Intent-Filter hinzu, wenn Ihre App ein anderes Redirect-Muster benötigt.

Web

• Der Pop-up-Flow ist der Standard und funktioniert gut für Einseitige Apps.
• Der Redirect-Flow ist besser, wenn der Anbieter Pop-ups blockiert oder Ihre Auth-Regeln eine oberste Ebene Navigation erfordern.
• Einige Anbieter blockieren direkte Browser-Token-Wechsel durch CORS. In solchen Fällen verwenden Sie einen Backend-Wechsel oder eine Anbieterkonfiguration, die öffentliche Clients zulässt.

Sicherheitsbest Practices

1. Verwenden Sie PKCE Behalten Sie pkceEnabled: true für öffentliche Clients.

2. Die Autorisierung code-Fluss ist sicherer als der implizite Flow. responseType: 'code' Validieren Sie Token auf Ihrem Backend

3. Entschlüsseln und überprüfen Sie den Aussteller, die Zielgruppe, die Ablaufzeit und die Signatur serverseitig. Speichern Sie Refresh-Tokens sicher

4. Für native Apps, kombinieren Sie dieses Plugin mit Capacitor @capgo/capacitor-persistente-Konto.

5. HTTPS überall verwenden Produktionsauth-Endpunkte und Logout-Endpunkte sollten immer HTTPS verwenden.

Fehlersuche

providerId is required

Jeder OAuth2-Methode benötigt die konfigurierte Provider-Schlüssel:

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

OAuth2 provider "xxx" not configured

Aufrufen SocialLogin.initialize() vor der Anmeldung und stellen Sie sicher, dass der providerId sich mit dem Schlüssel unter dem Objekt übereinstimmt oauth2.

URL-Mismatch bei der Weiterleitung

• Überprüfen Sie die im App- und Provider-Dashboard konfigurierte Weiterleitungs-URL Zeichen für Zeichen.
• Achten Sie auf verbleibende Schrägstriche, Schemamismatches und unterschiedliche Hosts.
• Stellen Sie sicher, dass die URL-Schemata der mobilen App vor der Testung auf einem Gerät registriert sind.

Kein Refresh-Token zurückgegeben

Die meisten Anbieter liefern Refresh-Tokens nur dann zurück, wenn Sie Scopes wie __CAPGO_KEEP_0__ anfordern oder explizit die Zustimmung erzwingen. Überprüfen Sie die Anbieter-spezifische Richtlinie. offline_access Fehlende Token-Überprüfung

Abschnitt: Fehlende Token-Überprüfung

Abschnitt: Aktivieren Sie die Token-Überprüfung logsEnabled: true auf der Anbieterkonfiguration, um generierte URLs und Tokenaustauschdetails zu überprüfen.

Verwandte Dokumente

• Soziale Anmeldung - Einführung
• Ionic Auth Connect-Migration