Generic OAuth2-Anbieter

GitHub

Eine Einrichtungsvorlage mit den Installationsanweisungen und der vollständigen Markdown-Guideline für diesen Plugin kopieren.

Einführung

Der 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

Das oauth2 Konfiguration ist multi-Provider-Design. Sie können mehrere Anbieter gleichzeitig registrieren und dann einen auswählen, wenn Sie sich anmelden. providerId.

Was Sie benötigen

Ihre OAuth-Kunden-ID

Ein Redirect-URL, der Ihrem App-Schema oder Web-Callback-URL entspricht
Ein Autorisierungs-Endpunkt
Ein Token-Endpunkt für die Autorisierungs-Flow, oder ein
A token endpoint for authorization code flow, or an issuerUrl Die Berechtigungen, die Ihre App benötigt, wie z.B.
Multi-Provider-Konfiguration openid profile email

Abschnitt mit dem Titel „Multi-Provider-Konfiguration“

Verwenden Sie 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 Alias

Wenn Ihr Provider ein OpenID-Connect-Entdeckungsdocument 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-Ü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 Provider-Namen 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 voreingestellte Anbieter-IDs:

auth0
azure
cognito
okta
onelogin

Wenn ein Anbieter benutzerdefinierte Endpunkte benötigt, können diese entweder im voreingestellten Anbieter überschrieben werden oder der Anbieter wird umgangen und direkt in der Konfiguration konfiguriert. oauth2.

Konfigurationsoptionen

Option	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`	Zeichenfolge / Zeichenfolgenarray	Nein	Gebotene Berechtigungen
`pkceEnabled`	Boolesch	Nein	Standardmäßig `true`
`responseType`	`'code'` oder `'token'`	Nein	Standardmäßig `'code'`
`resourceUrl`	Zeichenfolge	Nein	Benutzerinformationen oder Ressourcenendpunkt
`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 Header für `resourceUrl`
`additionalLogoutParameters`	`Record<string, string>`	Nein	Zusätzliche Logout-Parameter
`loginHint`	Zeichenfolge	Nein	Kürzel für `additionalParameters.login_hint`
`prompt`	Zeichenfolge	Nein	Kürzel für `additionalParameters.prompt`
`iosPrefersEphemeralSession`	Boolesch	Nein	Präferenz für eine vorübergehende Browser-Sitzung auf iOS
`logsEnabled`	Boolesch	Nein	Verbose Debug-Logging 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

Benutzen flow: 'redirect' wenn Sie eine volle Seite umleiten möchten, anstatt ein Pop-up:

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

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

GitHub-Beispiel

Verwenden Sie GitHub wenn Sie einen einfachen OAuth-Anwendungsfluss 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-Modus, wenn Ihr Anbieter ihn 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-ID-Token, wenn der Anbieter eins 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 Anbieterkonfiguration

GitHub

Erstellen Sie ein OAuth-App Öffnen GitHub Entwickler-Einstellungen und erstellen Sie eine neue OAuth-App.
Setze die Callback-URL Verwende die Redirect-URL deiner App, zum Beispiel myapp://oauth/github.

Konfiguriere 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

Registriere eine App Gehe zum Azure-Portal, öffne App registrationsund erstelle eine native oder mobile App-Registrierung.
Füge den Redirect-URI hinzu Füge einen mobilen oder Desktop-Redirect-URI hinzu, der 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.
Setzen Sie die zulässigen Callback-URLs Fügen Sie die genaue Umleitungs-URL ein, die von Ihrem Capacitor-Anwendung 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-Anwendung In der Okta-Admin-Konsole eine OIDC-Native-Anwendung erstellen.
Fügen Sie Ihre Umleitungs-URI hinzu Registrieren Sie die genaue Callback-URL, die von Ihrer Anwendung 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 die Entdeckung 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 keinen geteilten Cookies möchten.

Android

OAuth-Weiterleitungen kehren über Ihre App-Scheme und -Host zurück.
Stellen Sie sicher, dass die Anbieter-Callback-URL genau Ihren Android-Deep-Link-Einrichtungen entspricht.
Der Plugin bereits handhabt 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 Navigations-Ebene erfordern.
Einige Anbieter blockieren direkte Browser-Token-Austausch mit CORS. In solchen Fällen verwenden Sie einen Backend-Austausch oder eine Anbieter-Einrichtung, die öffentliche Clients zulässt.

Sicherheitsbest Practices

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

Behebungsprobleme

`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 providerId sich mit dem Schlüssel unter oauth2.

Umwelt-URL-Mismatch

Vergleichen Sie die konfigurierte Umwelt-URL in Ihrer App und dem Anbieter-Dashboard Zeichen für Zeichen.
Achten Sie auf nachfolgende Schrägstriche, Scheme-Mismatches und unterschiedliche Hosts.
Stellen Sie sicher, dass die mobilen App-URL-Schemas 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 erzwingen Sie explizit den Einwilligung. Überprüfen Sie die Anbieter-spezifische Richtlinie.

Fehlersuche bei Tokenaustausch

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

Weitermachen von Generic OAuth2 Providern

Wenn Sie Ionic Auth Connect verwenden Generic OAuth2 Providern für die Planung der Authentifizierung und der Kontoflows, verbinden Sie es mit Mit @capgo/capacitor-social-login für die native Fähigkeit in Mit @capgo/capacitor-social-login, Mit @capgo/capacitor-social-login für die Implementierungsdetails in @capgo/capacitor-social-login, Mit @capgo/capacitor-passkey für die Implementierungsdetails in @capgo/capacitor-passkey @capgo/capacitor-native-biometrisch für die Implementierungsdetails in @capgo/capacitor-native-biometrisch, und Zwei-Faktor-Authentifizierung für die Implementierungsdetails in Zwei-Faktor-Authentifizierung.

Generic OAuth2-Anbieter

Einführung

Was Sie benötigen

Abschnitt mit dem Titel „Multi-Provider-Konfiguration“

OIDC-Entdeckung und Alias

Auth Connect-kompatible Vorlagen

Konfigurationsoptionen

Mit OAuth2-Login

Anmelden

Umleitung im Web

Login-Status und Abmeldung

Aktualisierungstoken

Aktueller Zugriffstoken holen

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

Web

Sicherheitsbest Practices

Behebungsprobleme

providerId is required

OAuth2 provider "xxx" not configured

Umwelt-URL-Mismatch

Kein Refresh-Token zurückgegeben

Fehlersuche bei Tokenaustausch

Zugehörige Dokumentation

Weitermachen von Generic OAuth2 Providern

`providerId is required`

`OAuth2 provider "xxx" not configured`