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

Multi-Provider-Konfiguration

Verwenden SocialLogin.initialize() einmal während der Anwendungsstart 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 ausgibt, issuerUrl ist 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 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 benutzerspezifische Endpunkte benötigt, können Sie entweder diese in der Vorlage überschreiben oder die Vorlagen umgehen und den Anbieter direkt in oauth2.

Konfigurationsoptionen

Option	Typ	Erforderlich	Beschreibung
appId / clientId	Zeichenfolge	Ja	OAuth2-Kundenidentifikator
issuerUrl	Zeichenfolge	Nein	OIDC-Entdeckungs-Base-URL
authorizationBaseUrl / authorizationEndpoint	Ja*	Autorisierungsanforderungs-URL	string
accessTokenEndpoint / tokenEndpoint	Sprache	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	Zeichenkette	Nein	Benutzerinformationen oder Ressourcen-Endpunkt
logoutUrl / endSessionEndpoint	Zeichenkette	Nein	Abmelden oder Sitzungsende-URL
postLogoutRedirectUrl	Zeichenkette	Nein	Zurücksetzen-URL nach Abmeldung
additionalParameters	Record<string, string>	Nein	Zusätzliche Auth-Anforderungsparameter
additionalTokenParameters	Record<string, string>	Nein	Zusätzliche Token-Anforderungsparameter
additionalResourceHeaders	Record<string, string>	Nein	Zusätzliche Header für resourceUrl
additionalLogoutParameters	Record<string, string>	Nein	Zusätzliche Logout-Parameter
loginHint	string	Nein	Kurzform für additionalParameters.login_hint
prompt	string	Nein	Kurzschlüssel für 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-Login

Anmelden

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

Umleitung im Web: Wenn Sie stattdessen eine volle Seite mit der Umleitung verwenden möchten,

Verwenden Sie flow: 'redirect' Wenn Sie eine volle Seite mit der Umleitung statt eines Pop-ups verwenden möchten:

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

Auf die Zwischenablage kopieren

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

Refresh-Tokens verwenden

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

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

refresh() Der Refresh-Token wird vom Plugin gespeichert und verwendet. refreshToken() Sie können einen Refresh-Token selbst übergeben und erhalten die frische OAuth2-Antwort.

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-Anmeldeprozess 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 Umleitungsfluss auf der Webanwendung 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);
}

Beispiel für 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);

Beispiel für Keycloak

Verwenden Sie die 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 zurück:

Feld	Beschreibung
providerId	Der konfigurierte Anbieter-Schlüssel, der für das Anmelden verwendet wird
accessToken	Zugriffstoken-Payload oder null
idToken	OIDC-ID-Token, wenn der Anbieter eines zurückgegeben hat
refreshToken	Aktualisierungstoken, wenn die angeforderten Berechtigungen es erlaubten
resourceData	Rohes JSON, abgerufen von resourceUrl
scope	Eingeräumte Berechtigungen
tokenType	Normalerweise bearer
expiresIn	Lebensdauer des Tokens in Sekunden

Referenz zur Anbieter-Einrichtung

GitHub

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

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

3. Die Plugin-Konfiguration anpassen

   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 App registrieren Gehe zum Azure-Portal, öffne App registrations, und erstelle eine native oder mobile App-Registrierung.

2. Füge den Redirect-URI hinzu Füge einen mobilen oder Desktop-Redirect-URI hinzu, der sich mit deiner App-Rückruf-URL übereinstimmt.

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

   Hinweis

   Ersetze common mit deinem Tenant-ID, wenn deine App ein Single-Tenant-App ist.

Auth0

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

2. Setzen Sie die zulässigen Callback-URLs Fügen Sie die genaue Redirect-URL hinzu, die von Ihrer Capacitor-Anwendung 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-Anwendung Erstellen Sie in Okta Admin Console eine OIDC-Native-Anwendung.

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

Plattformspezifische Hinweise

iOS

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

Android

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

• Popup-Flow ist die Standardmethode und funktioniert gut für Einseitige Anwendungen.
• Der Redirect-Flow ist besser, wenn der Anbieter Popups blockiert oder Ihre Auth-Regeln eine oberste Navigations-Ebene 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

1. Verwenden Sie PKCE Für öffentliche Clients pkceEnabled: true Präferieren Sie die Autorisierung __CAPGO_KEEP_0__-Methode

2. Prefer authorization code 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. Use PKCE for public clients.

4. Sichere Token für den Refresh speichern Für native Apps, kombinieren Sie diesen Plugin mit @capgo/capacitor-persistenter Account.

5. HTTPS verwenden Sie überall 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

Aufrufen SocialLogin.initialize() sich vor dem Login sicherstellen, dass providerId entspricht dem Schlüssel im Objekt unter oauth2.

Fehler bei der Umleitung

• Überprüfen Sie die im App- und Provider-Dashboard konfigurierte Umleitungs-URL Zeichen für Zeichen.
• Achten Sie auf Nachschläge, Scheme-Mismatches und unterschiedliche Hosts.
• Stellen Sie sicher, dass die URL-Schemata von mobilen Apps 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 Anforderungen wie offline_access oder explizit den Einwilligungszustand erzwingen. Überprüfen Sie die Anbieter-spezifische Richtlinie.

Fehlschlag bei der Token-Austausch-Abfrage

Aktivieren logsEnabled: true Aktivieren Sie im Anbieterkonfiguration, um generierte URLs und Details zur Token-Übertragung zu überprüfen.

Zugehörige Dokumentation

• Einführung in Social Login
• Migration von Ionic Auth Connect

Weitermachen mit Generic OAuth2-Anbietern

Wenn Sie Generic OAuth2-Anbieter zur Planung der Authentifizierung und der Kontoflows verwenden, verbinden Sie es mit Mit @capgo/capacitor-social-login für die native Fähigkeit in Mit @capgo/capacitor-social-login, @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-biometric für die Implementierungsdetails in @capgo/capacitor-native-biometric, und Zwei-Faktor-Authentifizierung für die Implementierungsdetails in Zwei-Faktor-Authentifizierung.