Allgemeine OAuth2-Anbieter

GitHub

Ein kopierfertiger Einrichtungsvorschlag mit den Installationsanweisungen und der vollständigen Markdown-Guide für diesen Plugin erstellen.

Einführung

Das Capgo-Plugin für soziale Anmeldungen enthält einen integrierten OAuth2- und OpenID-Connect-Motor. Sie können es 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

The Konfiguration ist multi-provider durch Design. Sie können mehrere Anbieter gleichzeitig registrieren und dann einen auswählen, wenn Sie sich anmelden. oauth2 Was Sie benötigen providerId.

Bevor Sie eine Anbieter-Konfiguration vornehmen, sammeln Sie:

Einen Redirect-URL, der Ihrem App-Schema oder Web-Callback-URL entspricht

Einen Autorisierungs-Endpunkt
Einen Token-Endpunkt für die Autorisierung __CAPGO_KEEP_0__-Fluss, oder einen
Für OIDC-Discovery
A token endpoint for authorization code flow, or an issuerUrl Multi-provider-Konfiguration
Was Sie benötigen openid profile email

Bevor Sie eine Anbieter-Konfiguration vornehmen, sammeln Sie:

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

Wenn Ihr Anbieter 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-Überschreibungen
additionalTokenParameters für Token-Austausch-Überschreibungen
additionalResourceHeaders für benutzerdefinierte Ressourcen-Endpunkte-Überschriften
additionalLogoutParameters und postLogoutRedirectUrl für Abmeldevorgänge
loginHint, prompt, und iosPrefersEphemeralSession

Auth-Connect-kompatible Vorlagen

If Sie aus 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 voreingestellte Anbieter-IDs:

auth0
azure
cognito
okta
onelogin

If ein Anbieter benutzerdefinierte Endpunkte benötigt, können Sie entweder diese in der Voreinstellung überschreiben oder die Voreinstellungen umgehen und den Anbieter direkt in oauth2.

Konfigurationsoptionen

Option	Typ	Zwingend	Beschreibung
`appId` / `clientId`	Zeichenfolge	Ja	OAuth2 Client Identifier
`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	Geforderte Berechtigungen
`pkceEnabled`	boolean	Nein	Standardmäßig `true`
`responseType`	`'code'` oder `'token'`	Nein	Standardmäßig `'code'`
`resourceUrl`	string	Nein	Benutzerinfo oder Ressourcenendpunkt
`logoutUrl` / `endSessionEndpoint`	Zeichenfolge	Nein	Abmelde- oder Sitzungsbeendungs-URL
`postLogoutRedirectUrl`	Zeichenfolge	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`	Zeichenkette	Nein	Kurzschlüssel für `additionalParameters.login_hint`
`prompt`	Zeichenkette	Nein	Kurzschlüssel für `additionalParameters.prompt`
`iosPrefersEphemeralSession`	Boolesch	Nein	Präferenz für eine vorübergehende Browser-Sitzung auf iOS
`logsEnabled`	boolean	Nein	Ausführliche Debug-Protokollierung aktivieren

authorizationBaseUrl und accessTokenEndpoint sind nur optional, wenn issuerUrl Ist für die Entdeckung ausreichend. 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

Verwenden flow: 'redirect' wenn Sie einen vollständigen Seiten-umleiten möchten, anstatt eines Pop-ups:

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

Auf der Seite, die den Callback empfängt, 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

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

Verwende Azure, wenn du Microsoft-Graph-Daten wie das Benutzerprofil benötigst:

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 du OIDC plus einen benutzerdefinierten API-Zielgruppe benötigst:

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 du auf Web den Redirect-Flow verwendest, lies 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 eine veröffentlicht hat /.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 eines zurückgegeben hat
`refreshToken`	Aktualisieren Sie den Token, wenn die angeforderten Berechtigungen dies zulassen
`resourceData`	Rohes JSON abgerufen von `resourceUrl`
`scope`	Genehmigte Berechtigungen
`tokenType`	Normalerweise `bearer`
`expiresIn`	Token-Laufzeit in Sekunden

Referenz für die Anbieterkonfiguration

Abschnitt mit dem Titel „GitHub“

Öffnen __CAPGO_KEEP_0__ Entwickler-Einstellungen GitHub Developer Settings Einen neuen OAuth-App erstellen.
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

Eine App registrieren Gehe zum Azure-Portal, öffne App registrations, und 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.

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.
Erlaubte Callback-URLs setzen Fügen Sie die genaue Umleitungs-URL ein, die von Ihrer Capacitor-Anwendung verwendet wird.

Plugin konfigurieren

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-Native-App erstellen In der Okta-Admin-Konsole einen OIDC-Native-Application erstellen.
Hinzufügen Sie Ihre Umleitungs-URI Registrieren Sie die genaue Callback-URL, die von Ihrer Anwendung 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 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.
Die Erweiterung handhabt bereits die OAuth-Aktivität. Fügen Sie nur benutzerdefinierte Intent-Filter hinzu, wenn Ihre App ein anderes Weiterleitungs-Muster benötigt.

Web

Der Umleitungs-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

Abschnitt mit dem Titel “Sicherheitsbest Practices”

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

Fehlersuche

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

Umwahl des Redirect-URLs

Vergleichen Sie den konfigurierten Redirect-URL in Ihrer App und dem Anbieter-Dashboard Zeichen für Zeichen.
Achten Sie auf verbleibende Schrägstriche, Scheme-Missverhältnisse und unterschiedliche Hosts.
Stellen Sie sicher, dass die URL-Schemes der mobilen App 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 Anforderungsskope wie __CAPGO_KEEP_0__ anfordern oder explizit die Zustimmung erzwingen. Überprüfen Sie die Anbieter-spezifische Richtlinie. offline_access Fehlersuche bei Token-Wechsel

Abschnitt mit dem Titel „Fehlersuche bei Token-Wechsel“

auf der Anbieter-Konfiguration, um generierte URLs und Token-Wechsel-Daten zu überprüfen. logsEnabled: true Zugehörige Dokumentation

Weitermachen von Generic OAuth2 Providern

Wenn Sie " Generic OAuth2 Providern" zur Planung der Authentifizierung und Benutzerflüsse verwenden, verbinden Sie es mit Verwenden Sie @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-social-login für die native Fähigkeit in Verwenden Sie @capgo/capacitor-social-login, @capgo/capacitor-social-login für die Implementierungsdetail in @capgo/capacitor-social-login, @capgo/capacitor-passkey für die native Fähigkeit in @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.

Allgemeine OAuth2-Anbieter

Einführung

Bevor Sie eine Anbieter-Konfiguration vornehmen, sammeln Sie:

Bevor Sie eine Anbieter-Konfiguration vornehmen, sammeln Sie:

OIDC-Entdeckung und Alias

Auth-Connect-kompatible Vorlagen

Konfigurationsoptionen

Mit OAuth2-Login

Anmelden

Umleitungsfluss auf Web

Anmeldung und Abmeldung

Aktualisierung von Tokens

Aktueller Zugriffstoken holen

Anbieter-spezifische Beispiele

GitHub-Beispiel

Azure AD / Microsoft Entra ID-Beispiel

Auth0-Beispiel

Okta-Beispiel

Keycloak-Beispiel

OAuth2-Antwortform

Referenz für die Anbieterkonfiguration

Abschnitt mit dem Titel „GitHub“

Azure AD / Microsoft Entra ID

Auth0

Okta

Keycloak und benutzerdefinierte OIDC-Anbieter

Plattformspezifische Hinweise

iOS

Android

Web

Abschnitt mit dem Titel “Sicherheitsbest Practices”

Fehlersuche

providerId is required

OAuth2 provider "xxx" not configured

Umwahl des Redirect-URLs

Kein Refresh-Token zurückgegeben

Abschnitt mit dem Titel „Fehlersuche bei Token-Wechsel“

Abschnitt mit dem Titel „Zugehörige Dokumentation“

Weitermachen von Generic OAuth2 Providern

`providerId is required`

`OAuth2 provider "xxx" not configured`