Docs Cloud OAuth Providers

Cloud cabinet OAuth providers

Cloud cabinet sign-in supports Yandex ID, VK ID, GitHub, Google, and GitLab. Every provider is off until the operator enters its credentials and enables it, so each installation offers only the providers that fit its market (for example Yandex ID and VK ID for Russia). The Cloud API uses the authorization-code flow with PKCE S256, a browser-bound CSRF state, and a shared one-time callback fence. Provider access tokens are used only to read the identity during the callback and are not stored.

Only a Cloud operator can change the registry. Public fields and encrypted, versioned write-only secrets are stored by the Cloud connector authority. Raw client secrets are never returned by the API or UI and are not configured through environment variables.

Configure providers in Operator console → Email, payment and fiscal connectors. Leaving a write-only secret field empty preserves the current immutable version; entering a new value publishes a new version. Disabling a provider does not erase historical versions, while explicit revocation permanently prevents use of that version.

Interactive changes require a recent Cloud sign-in or a current password or 2FA code. Connector secret mutations intentionally reject API-token authentication; use an operator browser session with step-up verification.

The compatibility CLI command resolves a secret from the operator’s environment and sends the same write-only update contract. It never sends an env:// reference to Cloud:

export MOCKARTY_GITHUB_CLIENT_SECRET='replace-in-your-secure-shell'
mockarty cloud-oauth-providers configure github \
  --client-id your-github-client-id \
  --client-secret-env MOCKARTY_GITHUB_CLIENT_SECRET \
  --expected-revision 1 \
  --enabled \
  --idempotency-key github-oauth-20260830-1

New operator automation should prefer cloud-connectors configure oauth github, which uses the common revisioned connector lifecycle.

The callback URL is derived from the configured public Cloud URL:

https://cloud.example.com/api/v1/cloud/auth/oauth/PROVIDER/callback

It must exactly match the callback registered at the provider. Use HTTPS outside an isolated local environment.

In a production deployment, set CLOUD_API_OAUTH_STATE_SECRET to an independently generated value of at least 32 characters and use the same value on every Cloud API replica.

Yandex ID registration

  1. Open Yandex OAuth and create a web-service application.

  2. Register this exact callback URL:

    https://cloud.example.com/api/v1/cloud/auth/oauth/yandex/callback

  3. Allow access to the email and basic profile data required by the login:email login:info scopes.

  4. In Operator console → Email, payment and fiscal connectors, enter the client ID and the write-only client secret, enable the connector, and save it after step-up verification.

VK ID registration

  1. Open the VK ID application cabinet and create a website application.

  2. Register this exact callback URL:

    https://cloud.example.com/api/v1/cloud/auth/oauth/vk/callback

  3. Enable the email scope.

  4. Enter the numeric application ID in Operator console → Email, payment and fiscal connectors and enable it. Mockarty uses the current VK ID OAuth 2.1 PKCE flow at id.vk.ru; it does not send the legacy VK client secret.

Do not configure the old oauth.vk.com callback. The current callback also carries a provider-issued device_id; Cloud rejects the exchange when it is missing.

GitHub registration

Create an OAuth app in GitHub developer settings, set the authorization callback URL to /api/v1/cloud/auth/oauth/github/callback, then enter its client ID and write-only client secret in Operator console → Email, payment and fiscal connectors. Mockarty requests read:user user:email and accepts an email as verified only when GitHub reports it as both primary and verified.

Google registration

  1. Open the Google Cloud console and create an OAuth client of type Web application.
  2. Register this exact redirect URI:
https://<your-cloud-host>/api/v1/cloud/auth/oauth/google/callback
  1. Enter the client ID and client secret in Operator console → Email, payment and fiscal connectors. Mockarty requests openid email profile and accepts the address as verified only when Google reports email_verified.

GitLab registration

  1. In GitLab open User settings → Applications (or a group / instance application) and create an application with the read_user scope.
  2. Register this exact redirect URI:
https://<your-cloud-host>/api/v1/cloud/auth/oauth/gitlab/callback
  1. Enter the application ID and secret in Operator console → Email, payment and fiscal connectors. The primary email GitLab returns is already confirmed on the GitLab side, so the account is verified at once.

Inspect, rotate, disable

The operator UI shows public configuration, revision, whether a secret is configured, and the last bounded test result; it never shows a secret value. To rotate, enter a new secret and save a new immutable version, test it, and then validate a complete sign-in. Disable the connector to stop new sign-ins. Revoke an old version only after its in-flight callbacks are no longer needed; revocation is one-way.

Keep password sign-in and two-factor authentication available as a recovery path. The Security & Account → Sign-in methods panel links and unlinks external identities only after step-up verification. Removing the last external identity always asks for a current password; an OAuth-only account must add another method or set a local password through the recovery flow first. Cloud records every link, unlink, step-up, and provider-registry mutation in its audit chain.

Previous
BAA Template (HIPAA)