Generic OAuth2-Anbieter

GitHub

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

Einführung

Das Capgo Social Login Plugin enthält einen integrierten OAuth2- und OpenID Connect-Motor. Sie können damit jeden standardsbasierten Identitätsanbieter verbinden, einschließlich:

GitHub
Azure AD / Microsoft Entra ID
Auth0
Okta
Keycloak
Eigene 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 mit providerId.

Was Sie benötigen

Bevor Sie einen Anbieter konfigurieren, sammeln Sie:

Den OAuth-Kunden-ID
A eine Umleitungs-URL, die Ihrem App-Schema oder Ihrer Web-Callback-URL entspricht
Eine Autorisierungs-Endpunkt
Eine Token-Endpunkt für die Autorisierung code-Fluss oder ein issuerUrl Eine für OIDC-Entdeckung
Die Berechtigungen, die Ihre App benötigt, wie z.B. openid profile email

Multi-Anbieter-Konfiguration

Verwenden SocialLogin.initialize() einmal während der App-Start 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-Entdeckungsdocument ausgibt, issuerUrl ist dies die einfachste Einrichtung:

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 Authentifizierungsanforderungs-Überschreibungen
additionalTokenParameters für Tokenaustauschs-Überschreibungen
additionalResourceHeaders für benutzerdefinierte Ressourcendpunktheader
additionalLogoutParameters und postLogoutRedirectUrl für Abmeldevorgänge
loginHint, prompt, and 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 oauth2.

Konfigurationsoptionen

Einstellung	Typ	Pflicht	Beschreibung
`appId` / `clientId`	Zeichenfolge	Ja	OAuth2-Kundenidentifikator
`issuerUrl`	Zeichenfolge	Nein	OIDC-Entdeckungs-URL
`authorizationBaseUrl` / `authorizationEndpoint`	Zeichenfolge	Ja*	Anmeldeendpunkt-URL
`accessTokenEndpoint` / `tokenEndpoint`	Zeichenfolge	Nein	Tokenendpunkt-URL
`redirectUrl`	Zeichenfolge	Ja	Rückruf-URL
`scope` / `scopes`	Zeichenfolge / Zeichenfolgenarray	Nein	Gewünschte Berechtigungen
`pkceEnabled`	Wahr	Nein	Defaults zu `true`
`responseType`	`'code'` oder `'token'`	No	Defaults zu `'code'`
`resourceUrl`	Nein	No	Benutzerinformationen oder Ressourcenendpunkt
`logoutUrl` / `endSessionEndpoint`	Nein	No	Benutzerinformationen oder Ressourcenendpunkt
`postLogoutRedirectUrl`	Nein	No	Richtlinie für die Umleitung nach dem Abmelden
`additionalParameters`	`Record<string, string>`	Nein	Zusätzliche Authentifizierungsanforderungen
`additionalTokenParameters`	`Record<string, string>`	Nein	Zusätzliche Tokenanforderungen
`additionalResourceHeaders`	`Record<string, string>`	Nein	Zusätzliche Kopfzeilen für `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	Nein	Zusätzliche Abmeldeparameter
`loginHint`	Zeichenfolge	Nein	Kurzform für `additionalParameters.login_hint`
`prompt`	Deutsch	Nein	Kürzel für `additionalParameters.prompt`
`iosPrefersEphemeralSession`	Boolesch	Nein	Verwenden Sie eine vorübergehende Browser-Sitzung auf iOS
`logsEnabled`	Boolesch	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 Web

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

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

Auf der Seite, die den Callback empfängt, den Login-Ergebnis auswerten:

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 abrufen

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 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 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 das Ergebnis 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

Verwenden Sie Entdeckung, 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 von Benutzern konfigurierte Anbieter-Schlüssel für die Anmeldung
`accessToken`	Zugriffstoken-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`	Eingeräumte Berechtigungen
`tokenType`	In der Regel `bearer`
`expiresIn`	Lebensdauer des Tokens in Sekunden

Referenz zur Anbieterkonfiguration

GitHub

OAuth-Anwendung erstellen Ö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

Eine Anwendung registrieren Gehe zum Azure-Portal, öffne App registrationsund erstelle eine native oder mobile Anwendung zur Registrierung.
Füge den Redirect-URI hinzu Füge einen mobilen oder Desktop-Redirect-URI hinzu, der sich mit deiner App-Callback-URL übereinstimmt.

Konfiguriere 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 und erstellen Sie eine Native-Anwendung.
Ermöglichen Sie die Callback-URLs Add the exact redirect URL used by your Capacitor app.

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

OIDC-Anwendung erstellen OIDC-Native-Anwendung in Okta Admin Console erstellen.
Hinzufügen Ihrer Redirect-URI Registriere die genaue Callback-URL, die von deiner App verwendet wird.

Plugin konfigurieren

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

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

Android

OAuth-Redirects kehren über Ihre App-Scheme und -Host zurück.
Stellen Sie sicher, dass der Provider-Callback-URL genau Ihren Android-Deep-Link-Einrichtungen 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.

Website

Die Popup-Fluss ist der Standard und funktioniert gut für Ein-Seiten-Anwendungen.
Der Redirect-Fluss ist besser, wenn der Anbieter Popups blockiert oder Ihre Auth-Regeln eine oberste Ebene Navigation erfordern.
Einige Anbieter blockieren direkte Browser-Token-Austausch mit CORS. In solchen Fällen verwenden Sie einen Backend-Austausch oder einen Anbieter-Setup, der öffentliche Clients zulässt.

Sicherheitsbest Practices

Verwende PKCE Halten Sie pkceEnabled: true für öffentliche Clients.
Präferieren Sie die Autorisierung code-Fluss responseType: 'code' ist sicherer als der implizite Fluss.
Validieren Sie Token auf Ihrem Backend Decode und überprüfe den Aussteller, Empfänger, Ablaufdatum und die Signatur serverseitig.
Speichern Sie die Refresh-Tokens sicher. Für native Apps, kombinieren Sie diesen Plugin mit @capgo/capacitor-persistierter-Konto.
Verwenden Sie HTTPS überall Produktionsauth-Endpunkte und Logout-Endpunkte sollten immer HTTPS verwenden.

Troubleshooting

`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`

Anrufen SocialLogin.initialize() vor der Anmeldung und sicherstellen, dass es providerId entspricht dem Schlüssel unter oauth2.

Ursprung-URL-Mismatch

Überprüfen Sie die konfigurierte Ursprung-URL in Ihrer App und im Anbieter-Portal Zeichen für Zeichen.
Achten Sie auf nachfolgende Schrägstriche, Scheme-Mismatches und unterschiedliche Hosts.
Stellen Sie sicher, dass die URL-Schemata für mobile Apps vor der Geräteprüfung registriert sind.

Kein Refresh-Token zurückgegeben

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

Fehlersuche bei Tokenaustausch

Aktivieren logsEnabled: true Aktivieren Sie auf der Anbieterkonfiguration, um generierte URLs und Tokenaustauschdetails zu überprüfen.

Weitermachen bei Generic OAuth2-Anbietern

Wenn Sie Generic OAuth2-Anbieter verwenden Wenn Sie Generic OAuth2-Anbieter verwenden Um die Authentifizierung und die Kontenflüsse zu planen, verbinden Sie es mit Verwenden Sie @capgo/capacitor-social-login für die native Fähigkeit in Verwenden Sie @capgo/capacitor-social-login für @capgo/capacitor-social-login für die Implementierungsdetail in @capgo/capacitor-social-login für @capgo/capacitor-passkey für die Implementierungsdetail in @capgo/capacitor-passkey @capgo/capacitor-native-biometrisch für die Implementierungsdetails in @capgo/capacitor-native-biometrisch, und für die Implementierungsdetail in Zwei-Faktor-Authentifizierung für die Implementierungsdetails in der Zwei-Faktor-Authentifizierung.

Generic OAuth2-Anbieter

Einführung

Was Sie benötigen

Multi-Anbieter-Konfiguration

OIDC-Entdeckung und Aliase

Auth Connect-kompatible Vorlagen

Konfigurationsoptionen

Mit OAuth2-Login verwenden

Anmelden

Umleitungsfluss auf Web

Anmeldestatus und Abmeldung

Aktualisierung von Tokens

Aktueller Zugriffstoken abrufen

Anbieter-spezifische Beispiele

GitHub Beispiel

Azure AD / Microsoft Entra ID-Beispiel

Auth0-Beispiel

Okta-Beispiel

Keycloak-Beispiel

OAuth2-Antwortform

Referenz zur Anbieterkonfiguration

GitHub

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak und benutzerdefinierte OIDC-Anbieter

Plattformspezifische Hinweise

iOS

Android

Website

Sicherheitsbest Practices

Troubleshooting

providerId is required

OAuth2 provider "xxx" not configured

Ursprung-URL-Mismatch

Kein Refresh-Token zurückgegeben

Fehlersuche bei Tokenaustausch

Zugehörige Dokumentation

Weitermachen bei Generic OAuth2-Anbietern

`providerId is required`

`OAuth2 provider "xxx" not configured`