Allgemeine OAuth2-Anbieter

GitHub

Kopieren Sie eine Setup-Anleitung mit den Installationsanweisungen und der vollständigen Markdown-Guideline für diesen Plugin.

Einführung

The Capgo Social Login plugin includes a built-in OAuth2 and OpenID Connect engine. You can use it to connect any standards-based identity provider, including:

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

Die oauth2 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
Eine Autorisierungs-Endpunkt
Ein Token-Endpunkt für die Autorisierungs-code-Fluss, oder einen issuerUrl für OIDC-Discovery
Die Berechtigungen, die Ihre App benötigt, wie z.B. openid profile email

Multi-Provider-Konfiguration

Verwenden Sie SocialLogin.initialize() einmal während der App-Startzeit 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 Alias

Wenn Ihr Provider 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 As 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-Übernahmen
additionalTokenParameters Für Token-Austausch-Übernahmen
additionalResourceHeaders Für benutzerdefinierte Ressourcen-Endpunkt-Überschriften
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 benutzerspezifische Endpunkte benötigt, können Sie entweder diese in der Vorlage überschreiben oder die Vorlagen umgehen und den Anbieter direkt in oauth2.

Konfigurationsoptionen

Einstellung	Typ	Pflichtfeld	Beschreibung
`appId` / `clientId`	OAuth2-Klientenidentifikator	Ja	OAuth2-Klientenidentifikator
`issuerUrl`	Zeichenfolge	Nein	OIDC-Entdeckungs-Base-URL
`authorizationBaseUrl` / `authorizationEndpoint`	Zeichenfolge	Ja*	Autorisierungsanforderungs-URL
`accessTokenEndpoint` / `tokenEndpoint`	Zeichenfolge	Nein*	Tokenanforderungs-URL
`redirectUrl`	Ja	Ja	Rückruf-URL
`scope` / `scopes`	string / string[]	Nein	Bereitgestellte Berechtigungen
`pkceEnabled`	boolean	Nein	Standardmäßig `true`
`responseType`	`'code'` oder `'token'`	Nein	Standardmäßig `'code'`
`resourceUrl`	OAuth2-Plugin für soziale Anmeldungen	Nein	Benutzerinformationen oder Ressourcen-Endpunkt
`logoutUrl` / `endSessionEndpoint`	string	Nein	Abmelde- oder Sitzungs-End-URL
`postLogoutRedirectUrl`	string	Nein	Zurück-URL nach Abmeldung
`additionalParameters`	`Record<string, string>`	Nein	Zusätzliche Auth-Request-Parameter
`additionalTokenParameters`	`Record<string, string>`	Nein	Zusätzliche Tokenanforderungsparameter
`additionalResourceHeaders`	`Record<string, string>`	Nein	Zusätzliche Kopfzeilen für `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	Nein	Zusätzliche Abmeldeparameter
`loginHint`	Zeichenfolge	Nein	Kürzel für `additionalParameters.login_hint`
`prompt`	Zeichenfolge	Nein	Kürzel für `additionalParameters.prompt`
`iosPrefersEphemeralSession`	Boolescher Wert	No	Präferieren Sie eine vorübergehende Browser-Sitzung auf iOS
`logsEnabled`	boolean	No	Erweiterte Debug-Protokollierung aktivieren

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

Umleitung im Web aktivieren

Verwenden Sie flow: 'redirect' wenn Sie eine vollständige Seite-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 Login-Ergebnis analysieren:

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 das von dem Plugin gespeicherte Aktualisierungstoken. refreshToken() erlaubt Ihnen ein Aktualisierungstoken selbst zu übergeben und gibt die frische OAuth2-Antwort zurück.

Ermitteln Sie das aktuelle Zugriffstoken

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

console.log(code.accessToken);

Anbieter-spezifische Beispiele

GitHub Beispiel

Verwenden Sie GitHub wenn Sie einen einfachen OAuth-App-Flow und grundlegende Profilinformationen möchten:

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

Beispiel für Keycloak

Wenn Ihr Anbieter die Discovery-Methode verwendet /.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);

Form der OAuth2-Antwort

Erfolgreiche OAuth2-Anmeldungen liefern:

Feld	Beschreibung
`providerId`	Der konfigurierte Anbieter-Schlüssel für die Anmeldung
`accessToken`	Zugriffs-Token-Inhalte oder `null`
`idToken`	OIDC-ID-Token, wenn der Anbieter eins zurückgegeben hat
`refreshToken`	Refresh-Token, wenn die angeforderten Berechtigungen es erlaubten
`resourceData`	Rohes JSON abgerufen von `resourceUrl`
`scope`	Zugeteilte Berechtigungen
`tokenType`	Häufig `bearer`
`expiresIn`	Lebensdauer des Tokens in Sekunden

Anbieter-Einstellungen-Referenz

GitHub

OAuth-Anwendung erstellen Öffnen GitHub Entwickler-Einstellungen und erstellen Sie ein neues OAuth-App.
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 App Gehe zur Azure-Portal-Website, öffne App registrations, und erstellen Sie eine native oder mobile App-Registrierung.
Zurücksetzen der URI Hinzufügen einer mobilen oder Desktop-URI, die sich an Ihre App-Callback-URL anpasst.

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 Auth0-Dashboard und erstellen Sie eine Native-App.
Setzen Sie die zulässigen 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

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

Einstellungen des Plugins

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.

Plattformspezifische Hinweise

iOS

Das Plugin verwendet ASWebAuthenticationSession.
Setze iosPrefersEphemeralSession: true Wenn du eine private Browser-Sitzung mit keiner gemeinsamen Cookie-Verwendung möchtest.

Android

OAuth-Redirects kehren durch deine App-Scheme und -Host zurück.
Stelle sicher, dass die Provider-Callback-URL genau mit deiner Android-Deep-Link-Einstellung übereinstimmt.
Die Plugin-Verwaltung handhabt bereits die OAuth-Aktivität. Füge nur benutzerdefinierte Intent-Filter hinzu, wenn deine App ein anderes Redirect-Muster benötigt.

Web

Die Popup-Flussmethode ist die Standardmethode und funktioniert gut für Single-Page-Apps.
Der Redirect-Fluss ist besser, wenn der Provider Popups blockiert oder deine Auth-Regeln eine oberste Ebene Navigation erfordern.
Einige Anbieter blockieren direkte Browser-Token-Austausch mit CORS. In solchen Fällen verwende einen Backend-Austausch oder eine Anbieter-Einstellung, die öffentliche Clients zulässt.

Sicherheitsbest Practices

Verwenden Sie PKCE Behalten Sie pkceEnabled: true für öffentliche Clients.
Präferieren Sie die Autorisierungs-code-Fluss responseType: 'code' ist sicherer als der implizite Fluss.
Validieren Sie Token auf Ihrem Backend Entschlüsseln und überprüfen Sie Aussteller, Zielgruppe, Ablaufdatum und Signatur serverseitig.
Speichern Sie Refresh-Tokens sicher Für native Apps, kombinieren Sie diesen Plugin mit @capgo/capacitor-persistent-account.
Verwenden Sie HTTPS überall Produktionsauth-Endpunkte und -Logout-Endpunkte sollten immer HTTPS verwenden.

Schwierigkeiten beheben

`providerId is required`

Jeder OAuth2-Methode ist die konfigurierte Anbieter-Schlüssel erforderlich:

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 entspricht dem Schlüssel unter oauth2.

Ursache für die Umleitung nicht übereinstimmen

Überprüfen Sie die konfigurierte Umwleitung-URL in Ihrer App und im Anbieter-Dashboard Zeichen für Zeichen.
Achten Sie auf nachfolgende Schrägstriche, Schemamismatches 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 Refresh-Tokens nur dann zurück, wenn Sie Anforderungen wie ‘oder explizit die Zustimmung erzwingen’. Überprüfen Sie die Anbieter-spezifische Richtlinie. offline_access Tokenaustausch-Debugging

Abschnitt mit dem Titel ‘Tokenaustausch-Debugging’

auf der Anbieter-Konfiguration, um generierte URLs und Tokenaustausch-Daten zu überprüfen. logsEnabled: true Aktivieren

Fortsetzung von Generic OAuth2-Anbietern

Wenn Sie Generic OAuth2-Anbieter verwenden Generic OAuth2-Anbieter um die Authentifizierung und die Kontenflüsse zu planen, verbinden Sie es mit Verwenden Sie @capgo/capacitor-social-login Verwenden Sie @capgo/capacitor-social-login für die native Fähigkeit in Verwenden Sie @capgo/capacitor-social-login Verwenden Sie @capgo/capacitor-social-login Für die Implementierungsdetails in @capgo/capacitor-Social-Login, @capgo/capacitor-Passkey Für die Implementierungsdetails in @capgo/capacitor-Passkey, @capgo/capacitor-Native-Biometrik Für die Implementierungsdetails in @capgo/capacitor-Native-Biometrik und Zwei-Faktor-Authentifizierung Für die Implementierungsdetails in Zwei-Faktor-Authentifizierung.

Allgemeine OAuth2-Anbieter

Einführung

Was Sie benötigen

Multi-Provider-Konfiguration

OIDC-Entdeckung und Alias

Auth Connect-kompatible Vorlagen

Konfigurationsoptionen

Mit OAuth2-Login

Anmelden

Umleitung im Web aktivieren

Anmeldestatus und Abmeldung

Aktualisierung von Tokens

Ermitteln Sie das aktuelle Zugriffstoken

Anbieter-spezifische Beispiele

GitHub Beispiel

Azure AD / Microsoft Entra ID-Beispiel

Auth0-Beispiel

Okta-Beispiel

Beispiel für Keycloak

Form der OAuth2-Antwort

Anbieter-Einstellungen-Referenz

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak und benutzerdefinierte OIDC-Anbieter

Plattformspezifische Hinweise

iOS

Android

Web

Sicherheitsbest Practices

Schwierigkeiten beheben

providerId is required

OAuth2 provider "xxx" not configured

Ursache für die Umleitung nicht übereinstimmen

Kein Refresh-Token zurückgegeben

Abschnitt mit dem Titel ‘Tokenaustausch-Debugging’

Zugehörige Dokumente

Fortsetzung von Generic OAuth2-Anbietern

`providerId is required`

`OAuth2 provider "xxx" not configured`