Generic OAuth2-Anbieter

Ein Setup-Prompt mit den Installations-Schritten und der vollständigen Markdown-Guideline für diesen Plugin kopieren.

Einführung

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

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

Die oauth2 Die Konfiguration ist multi-Provider-geeignet. Sie können mehrere Anbieter gleichzeitig registrieren und dann bei der Anmeldung einen auswählen mit 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 Berechtigungen, die Ihre App benötigt, wie z.B. openid profile email

Multi-provider-Konfiguration

Verwenden Sie SocialLogin.initialize() einmal während der Anwendungsstartzeit und registrieren Sie jeden Provider, 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 Provider ein OpenID Connect-Entdeckungsdocument offenlegt, issuerUrl ist dies 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 As Alias von authorizationBaseUrl
tokenEndpoint As Alias von accessTokenEndpoint
endSessionEndpoint As Alias von logoutUrl
scopes As Alias von scope

Auch 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 Abmeldevorgänge
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-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

Einstellung	Typ	erforderlich	Beschreibung
`appId` / `clientId`	Zeichenfolge	Ja	OAuth2-Kundenidentifikator
`issuerUrl`	string	Nein	OIDC-Entdeckungs-Base-URL
`authorizationBaseUrl` / `authorizationEndpoint`	string	Ja*	Autorisierungs-Endpunkt-URL
`accessTokenEndpoint` / `tokenEndpoint`	string	Nein*	Token-Endpunkt-URL
`redirectUrl`	string	Ja	Rückruf-URL
`scope` / `scopes`	string / string[]	Nein	Gebotene Berechtigungen
`pkceEnabled`	boolean	Nein	Standardmäßig `true`
`responseType`	`'code'` oder `'token'`	Nein	Standardmäßig `'code'`
`resourceUrl`	string	Nein	Benutzerinformationen oder Ressourcen-Endpunkt
`logoutUrl` / `endSessionEndpoint`	string	Nein	Abmelde- oder Sitzungsbeendungs-URL
`postLogoutRedirectUrl`	string	Nein	Umleitungs-URL nach Abmeldung
`additionalParameters`	`Record<string, string>`	Nein	Zusätzliche Auth-Request-Parameter
`additionalTokenParameters`	`Record<string, string>`	Nein	Zusätzliche Token-Request-Parameter
`additionalResourceHeaders`	`Record<string, string>`	Nein	Zusätzliche Kopfzeilen für `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	Nein	Zusätzliche Logout-Parameter
`loginHint`	Zeichenkette	Nein	Kurzschlüssel für `additionalParameters.login_hint`
`prompt`	Zeichenkette	Nein	Kurzschlüssel für `additionalParameters.prompt`
`iosPrefersEphemeralSession`	Boolescher Wert	Nein	Präferieren Sie eine vorübergehende 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.

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

Umleitungsfluss auf der Webanwendung

Verwenden flow: 'redirect' wenn Sie einen vollständigen Seitenwechsel statt eines Pop-ups möchten:

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

Auf der Seite, die den Callback erhält, analysieren Sie das Login-Ergebnis:

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

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

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

Aktualisierung von Tokens

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

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

refresh() verwendet den von dem Plugin gespeicherten Refresh-Token. refreshToken() erlaubt Ihnen, einen Refresh-Token selbst zu übergeben und gibt die frische OAuth2-Antwort zurück.

Aktueller Zugriffstoken holen

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

console.log(code.accessToken);

Anbieter-spezifische Beispiele

Beispiel für GitHub

Verwenden Sie GitHub wenn Sie einen einfachen OAuth-App-Flow und grundlegende Profildaten benötigen:

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

Verwenden Sie Azure, wenn Sie Microsoft-Graph-Daten wie das Benutzerprofil benötigen:

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 Sie OIDC plus eine benutzerdefinierte API Zielgruppe benötigen:

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 Sie den Redirect-Flow auf der Web-Seite verwenden, lesen Sie die Ergebnisse auf der Callback-Seite wieder ein:

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

Verwenden Sie den Discovery, wenn Ihr 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`	Der konfigurierte Anbieter-Schlüssel, der für die Anmeldung verwendet wird
`accessToken`	Zugriffstoken-Payload oder `null`
`idToken`	OIDC-Identitäts-Token, wenn der Provider eins zurückgegeben hat
`refreshToken`	Refresh-Token, wenn die angeforderten Berechtigungen es erlaubten
`resourceData`	Rohes JSON, das von `resourceUrl`
`scope`	Zugeteilte Berechtigungen
`tokenType`	Häufig `bearer`
`expiresIn`	Lebensdauer des Tokens in Sekunden

Referenz für die Anbieterkonfiguration

GitHub

Erstellen Sie eine OAuth-Anwendung Öffnen GitHub Entwickler-Einstellungen und erstellen Sie eine neue OAuth-Anwendung.
Setzen Sie die Callback-URL Verwenden Sie die Redirect-URL Ihrer App, zum Beispiel myapp://oauth/github.

Konfigurieren Sie das 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

Registrieren Sie eine Anwendung Gehen Sie zum Azure-Portal, öffnen Sie App registrations, und erstellen Sie eine native oder mobile Anwendungserfassung.
Fügen Sie die Redirect-URI hinzu Fügen Sie eine mobile oder Desktop-Redirect-URI hinzu, die Ihren App-Callback-URL entspricht.

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

Auth0

Eine native Anwendung erstellen Öffnen Sie das Auth0-Dashboard Eine native App erstellen.
Ermöglichen Sie die Callback-URLs Fügen Sie die genaue Redirect-URL ein, die von Ihrer Capacitor-App verwendet wird.

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

Eine OIDC-native App erstellen In der Okta-Admin-Konsole eine OIDC-Native-Anwendung erstellen.
Hinzufügen Ihrer Redirect-URI Registrieren Sie die genaue Callback-URL, die von Ihrer App verwendet wird.

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 Discovery nicht verfügbar ist, konfigurieren Sie die Autorisierungs- und Token-Endpunkte manuell.

Plattform-spezifische Hinweise

iOS

Der Plugin verwendet ASWebAuthenticationSession.
Set iosPrefersEphemeralSession: true If Sie eine private Browser-Sitzung mit keiner gemeinsamen Cookie-Verwendung möchten.

Android

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

Web

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

Security-Best Practices

Verwende PKCE Behalte pkceEnabled: true für öffentliche Clients.
Die Autorisierung code-Fluss ist sicherer als der implizite Fluss. responseType: 'code' Validiere Token auf deinem Backend
Entschlüssle und überprüfe Issuer, Audience, Ablauf und Signatur serverseitig. Speichere Refresh-Tokens sicher
Für native Apps, kombiniere diesen Plugin mit @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-persistent-account @capgo/capacitor-persistent-account.
Die Autorisierung __CAPGO_KEEP_0__-Fluss ist sicherer als der implizite Fluss. Produktionsauth-Endpunkte und -Logout-Endpunkte sollten immer HTTPS verwenden.

Fehlersuche

`providerId is required`

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

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

`OAuth2 provider "xxx" not configured`

Aufruf SocialLogin.initialize() vor der Anmeldung und stellen Sie sicher, dass der providerId entspricht dem Schlüssel unter oauth2.

Ursprung-URL-Mismatch

Vergleichen Sie die im App- und Provider-Dashboard konfigurierte Umleitungs-URL Zeichen für Zeichen.
Achten Sie auf verbleibende Schrägstriche, Schemamängel und unterschiedliche Hosts.
Stellen Sie sicher, dass die URL-Schemata für mobile Apps vor der Testung auf einem Gerät registriert sind.

Kein Refresh-Token zurückgegeben

Die meisten Anbieter geben nur Refresh-Tokens zurück, wenn Sie Anforderungen wie offline_access oder explizit den Einwilligungszustand erzwingen. Überprüfen Sie die Anbieter-spezifische Richtlinie.

Fehlersuche bei Tokenaustausch

Aktivieren Sie logsEnabled: true auf der Provider-Konfiguration, um generierte URLs und Tokenaustausch-Details zu überprüfen.

Weitermachen von Generic OAuth2-Anbietern

Wenn Sie soziale Anmeldungen verwenden Generic OAuth2-Anbieter um die Authentifizierung und die Kontenflüsse zu planen, verbinden Sie es mit Mit @capgo/capacitor-soziale-Anmeldung für die native Fähigkeit in Mit @capgo/capacitor-soziale-Anmeldung @capgo/capacitor-soziale-Anmeldung für die Implementierungsdetails in @capgo/capacitor-soziale-Anmeldung @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric für die Implementierungsdetails in @capgo/capacitor-native-biometric, und Zwei-Faktor-Authentifizierung für die Implementierungsdetails in Zwei-Faktor-Authentifizierung.

Generic OAuth2-Anbieter

Einführung

Was Sie benötigen

Multi-provider-Konfiguration

OIDC-Entdeckung und Aliase

Auth Connect-kompatible Vorlagen

Konfigurationsoptionen

Mit OAuth2-Login verwenden

Anmelden

Umleitungsfluss auf der Webanwendung

Anmeldung und Abmeldung

Aktualisierung von Tokens

Aktueller Zugriffstoken holen

Anbieter-spezifische Beispiele

Beispiel für GitHub

Azure AD / Microsoft Entra ID Beispiel

Auth0-Beispiel

Okta-Beispiel

Keycloak-Beispiel

OAuth2-Antwortform

Referenz für die Anbieterkonfiguration

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak und benutzerdefinierte OIDC-Anbieter

Plattform-spezifische Hinweise

iOS

Android

Web

Security-Best Practices

Fehlersuche

providerId is required

OAuth2 provider "xxx" not configured

Ursprung-URL-Mismatch

Kein Refresh-Token zurückgegeben

Fehlersuche bei Tokenaustausch

Verwandte Dokumentation

Weitermachen von Generic OAuth2-Anbietern

`providerId is required`

`OAuth2 provider "xxx" not configured`