一般的なOAuth2 プロバイダー

導入

Capgoのソーシャルログインプラグインには、OAuth2およびOpenID Connectエンジンが組み込まれています。任意の標準ベースのIDプロバイダーを接続できます。

• GitHub
• Azure AD / Microsoft Entra ID
• Auth0
• Okta
• Keycloak
• カスタム OAuth2 または OIDC サーバー

The oauth2 デザイン上、複数のプロバイダーを一度に登録し、ログイン時には 1 つを選択できるように、構成はマルチ プロバイダーです。 providerId.

必要なもの

プロバイダーを構成する前に、以下の情報を収集してください。

• OAuth クライアント ID
• アプリのスキームまたは Web コールバック URL に対応するリダイレクト URL
• 認可エンドポイント
• 認可 code フロー用のトークンエンドポイント、または issuerUrl for OIDC discovery
• アプリケーションが必要とするスコープ、例えば openid profile email

複数のプロバイダーの設定

使用 SocialLogin.initialize() アプリケーション起動時に一度だけ、必要なすべてのプロバイダを登録する:

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 discoveryとエイリアス

最も簡単な設定です: 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,
    },
  },
});

プラグインは、一般的なOAuthおよびOIDCエイリアスもサポートしています:

• clientId __CAPGO_KEEP_0__のエイリアスとして appId
• authorizationEndpoint __CAPGO_KEEP_0__のエイリアスとして authorizationBaseUrl
• tokenEndpoint __CAPGO_KEEP_0__のエイリアスとして accessTokenEndpoint
• endSessionEndpoint __CAPGO_KEEP_0__のエイリアスとして logoutUrl
• scopes __CAPGO_KEEP_0__のエイリアスとして scope

利用可能なものもあります:

• additionalParameters 認証要求のオーバーライド用
• additionalTokenParameters トークン交換のオーバーライド用
• additionalResourceHeaders カスタムリソースエンドポイントヘッダ用
• additionalLogoutParameters そして postLogoutRedirectUrl ログアウトフローの用途
• loginHint, prompt, および iosPrefersEphemeralSession

Auth Connect互換のプリセット

Ionic Auth Connectから移行している場合、同じプロバイダ名を維持したい場合は 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',
    },
  },
});

サポートされているプリセットプロバイダID:

• auth0
• azure
• cognito
• okta
• onelogin

プロバイダがカスタムエンドポイントを必要とする場合は、プリセットでオーバーライドするか、プリセットをバイパスしてプロバイダを直接 oauth2.

設定オプション

オプション	タイプ	必須	概要
appId / clientId	文字列	はい	OAuth2 クライアント識別子
issuerUrl	文字列	いいえ	OIDC 発見ベース URL
authorizationBaseUrl / authorizationEndpoint	文字列	はい*	認証エンドポイント URL
accessTokenEndpoint / tokenEndpoint	文字列	いいえ*	__CAPGO_KEEP_0__ URL
redirectUrl	__CAPGO_KEEP_0__	Yes	__CAPGO_KEEP_0__ URL
scope / scopes	__CAPGO_KEEP_0__ / __CAPGO_KEEP_0__	No	__CAPGO_KEEP_0__
pkceEnabled	boolean	__CAPGO_KEEP_0__	または true
responseType	'code' or 'token'	__CAPGO_KEEP_0__	デフォルト値 'code'
resourceUrl	__CAPGO_KEEP_0__	いいえ	ユーザー情報またはリソースエンドポイント
logoutUrl / endSessionEndpoint	__CAPGO_KEEP_0__	いいえ	ログアウトまたはセッション終了URL
postLogoutRedirectUrl	__CAPGO_KEEP_0__	ログアウト後にリダイレクトするURL	いいえ
additionalParameters	Record<string, string>	追加の認証要求パラメータ	__CAPGO_KEEP_0__
additionalTokenParameters	Record<string, string>	いいえ	__CAPGO_KEEP_0__
additionalResourceHeaders	Record<string, string>	いいえ	__CAPGO_KEEP_0__ resourceUrl
additionalLogoutParameters	Record<string, string>	いいえ	__CAPGO_KEEP_0__
loginHint	文字列	いいえ	__CAPGO_KEEP_0__ additionalParameters.login_hint
prompt	__CAPGO_KEEP_0__	いいえ	__CAPGO_KEEP_0__ additionalParameters.prompt
iosPrefersEphemeralSession	boolean	No	iOS上でephemeralブラウザセッションを優先する
logsEnabled	boolean	No	デバッグログを詳細に表示する

authorizationBaseUrl そして accessTokenEndpoint は、値が見つかった場合にのみオプションです。明示的なエンドポイントは、検出された値よりも優先されます。 issuerUrl OAuth2ログインを使用する

「OAuth2ログインを使用する」のセクション

__CAPGO_KEEP_0__

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

ウェブ上でのリダイレクトフロー

使用 flow: 'redirect' フルページのリダイレクトをポップアップの代わりにしたい場合は

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

コールバックを受け取るページで、ログイン結果を解析する

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

リフレッシュ トークン

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

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

refresh() __CAPGO_KEEP_0__ プラグインが保存したリフレッシュ トークンを使用します。 refreshToken() __CAPGO_KEEP_0__ プラグインが保存したリフレッシュ トークンを使用せずに、自分でリフレッシュ トークンを渡してOAuth2の最新のレスポンスを取得します。

現在のアクセス トークンを取得

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

console.log(code.accessToken);

プロバイダーの例

GitHub の例

GitHub を使用すると、単純な OAuth アプリフローと基本的なプロファイルデータを取得できます。

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 の例

Azure を使用すると、ユーザープロファイルなどの Microsoft Graph データを取得できます。

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 の例

Auth0 は、OIDC に加えてカスタム API の受信者を必要とする場合に適しています。

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

Web でリダイレクトフローを使用する場合、コールバックページで結果を読み戻す必要があります。

const auth0Result = await SocialLogin.handleRedirectCallback();
if (auth0Result?.provider === 'oauth2') {
  console.log(auth0Result.result.idToken);
}

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

Keycloakの例

プロバイダーが公開する場合、ディスカバリーを使用する /.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のレスポンスの形状

OAuth2のログインが成功した場合に返される

フィールド	説明
providerId	__CAPGO_KEEP_0__
accessToken	ログインに使用される設定されたプロバイダーキー null
idToken	アクセストークンパイロードまたは
refreshToken	OIDC ID トークンがプロバイダーが返した場合
resourceData	リフレッシュトークンが要求されたスコープが許可した場合 resourceUrl
scope	__CAPGO_KEEP_0__
tokenType	通常 bearer
expiresIn	トークン有効期限（秒)

プロバイダーのセットアップリファレンス

GitHub

1. OAuth アプリを作成 開く GitHub 開発者設定 新しい OAuth アプリを作成します。

2. コールバック URL を設定 アプリのリダイレクト URL を使用してください、例えば myapp://oauth/github.

3. プラグインを設定

   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. アプリを登録 Azure ポータルに移動し、開く App registrations, アプリケーション登録を実行します。

2. リダイレクト URI を追加します。 モバイルまたはデスクトップ用のリダイレクト URI を追加して、コールバック URL に一致するようにしてください。

3. プラグインを設定します。

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

   注意

   テナント ID に置き換えてください。アプリケーションがシングル テナントの場合。 common Auth0

「Auth0」というセクション

1. Add the redirect URI Open the Auth0 ダッシュボード Native アプリを作成します。

2. 許可されたコールバック URL を設定します。 Capacitor アプリが使用する exact なリダイレクト URL を追加します。

3. プラグインを設定します。

   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. OIDC Native アプリを作成します。 Okta Admin Console で、OIDC Native アプリケーションを作成します。

2. リダイレクト URI を追加します。 アプリが使用する正確なコールバックURLを登録してください。

3. プラグインの設定

   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とカスタムOIDCプロバイダー

OpenID Connectのディスカバリをサポートしているプロバイダーがあれば、 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,
    },
  },
});

ディスカバリが利用できない場合は、認証とトークンエンドポイントを手動で設定してください。

プラットフォーム固有の注意

iOS

• プラグインは ASWebAuthenticationSession.
• Set iosPrefersEphemeralSession: true プライベートブラウザセッションを使用するには、共有クッキーなしでセッションを実行したい場合に使用してください。

Android

• OAuthリダイレクトはアプリのスキームとホストを通じて戻ります。
• Androidのデープリンク設定と完全に一致するように、プロバイダーのコールバックURLを確実に設定してください。
• プラグインはOAuthアクティビティをすでに処理しています。アプリが異なるリダイレクトパターンを必要とする場合にのみ、カスタムインテントフィルタを追加してください。

Web

• ポップアップフローはデフォルトで、シングルページアプリ向けにうまく機能します。
• プロバイダーがポップアップをブロックしたり、認証ルールがトップレベルナビゲーションを必要とする場合、リダイレクトフローはより適切です。
• 直接ブラウザのトークン交換は、CORSによってブロックされる場合があります。その場合、バックエンドの交換またはパブリッククライアントを許可するプロバイダーの設定を使用してください。

セキュリティのベストプラクティス

1. PKCEを使用する __CAPGO_KEEP_0__ pkceEnabled: true パブリッククライアント用に

2. Prefer authorization code flow responseType: 'code' トークンをサーバー側で検証する

3. 発行者、受信者、有効期限、署名を検証する リフレッシュトークンを安全に保存する

4. ネイティブアプリ用に、このプラグインを pair する Capgo @capgo/capacitor-persistent-account.

5. 全ての場所でHTTPSを使用 プロダクション用の認証エンドポイントとログアウトエンドポイントは、常にHTTPSを使用する必要があります。

トラブルシューティング

providerId is required

すべてのOAuth2メソッドには、構成済みのプロバイダーキーが必要です。

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

OAuth2 provider "xxx" not configured

呼び出し SocialLogin.initialize() ログインする前に、 providerId 指定されたオブジェクトキーと一致することを確認してください。 oauth2.

リダイレクト URL の一致性が不正

• アプリとプロバイダーのダッシュボードで設定されているリダイレクト URL を、文字列単位で比較してください。
• 末尾のスラッシュ、スキームの不一致、ホストの差異などを注意してください。
• モバイル アプリの URL スキームが登録されていることを確認して、デバイス上でテストしてください。

リフレッシュ トークンが返されない

ほとんどのプロバイダは、スコープとして「__CAPGO_KEEP_0__」や「__CAPGO_KEEP_1__」を指定することで、または明示的に同意を強制することで、リフレッシュ トークンを返します。プロバイダーのポリシーを確認してください。 offline_access トークン エクスチェンジのデバッグ

トークン エクスチェンジのデバッグ

トークン エクスチェンジのデバッグ logsEnabled: true __CAPGO_KEEP_0__

関連ドキュメント

• ソーシャルログインのスタート
• Ionic Auth Connectの移行