In this section · 1 article

Social sign-in from a mobile app

Sign people in to your mobile app with their Google, Apple or other account: through the phone's browser and a deep link, or with Google's or Apple's own sign-in on the phone. Includes the server settings, the endpoints and why each refusal happens.

Applies to
Social Login 2.0 and later
Who can do this
Developer, Platform owner
On this page

A mobile app can sign people in with the providers you've set up in Social Login. Your Laramin keeps every client secret: the app never holds one. Both ways end with the same access token and refresh token as a password sign-in from the app.

Browser and deep linkOn-phone sign-in
The app opensThe phone's browserThe provider's own sign-in, such as Google Sign-In or Sign in with Apple
Works withEvery provider except Twitter (OAuth 1.0a)Google and Apple
The app receivesA single-use code in a deep linkAn ID token from the provider
The app sends it toPOST /api/v1/mobile/module/sociallogin/sessionPOST /api/v1/mobile/module/sociallogin/{provider}/exchange

A first sign-in that would create an account follows Allow mobile app sign-up in Configurations › Security › Security Settings, not the website's switch. Both are off to start with. An account created from the app can use the app straight away. From Social Login 2.1.3, a first sign-in from a network address your global IP rules refuse creates no account. See How social sign-in works.

Calling the API

Every endpoint below is under your Laramin's address, such as https://crm.example.com. Before someone is signed in, the app sends your platform API key as an X-Api-Key header or a bearer token. The key is set in Core Mobile's API Security section, or in the server's PLATFORM_API_KEY. See Core Mobile configuration settings.

Read the provider list

HTTP
GET /api/v1/mobile/module/sociallogin/providers
X-Api-Key: <your platform API key>

Each provider has its provider key, label, logo_url, enabled, scopes, and flows:

Value in flowsMeaning
web_redirectSign-in through the website. Every provider.
mobile_redirectThe browser and deep link flow.
id_tokenOn-phone sign-in.

config holds the values an app needs to start on-phone sign-in, such as client_id_ios and client_id_android for Google. It never holds a secret. Read the flows from this list rather than hard-coding which providers support what.

Server setup

Whoever runs your server sets these in the .env file:

VariableWhat it doesDefault
SOCIAL_MOBILE_REDIRECT_ALLOWLISTThe deep links your Laramin may send people back to, separated by commas, such as myapp://auth/*. * is the only wildcard.Empty, which switches this flow off
SOCIAL_MOBILE_STATE_TTLSeconds a sign-in may take, from start to coming back from the provider.300
SOCIAL_MOBILE_HANDOFF_TTLSeconds the app has to trade its code.120

Careful: List only a scheme and path your app owns, such as myapp://auth/*. Never add https://*: it would let a sign-in hand its result to any website.

Also register a second callback address in each provider's console, beside the website one:

Plain text
https://<your Laramin's address>/auth/<key>/mobile/callback

Replace the highlighted values with your own.

The flow

  1. The app opens this address in the phone's browser, not in a web view inside the app:

    Plain text
    https://crm.example.com/auth/google/mobile/redirect?redirect=myapp://auth/callback
  2. The person signs in at the provider, which returns them to your Laramin's mobile callback.

  3. Your Laramin finishes the sign-in and opens the deep link with a single-use code: myapp://auth/callback?code=….

  4. The app trades the code for tokens:

    HTTP
    POST /api/v1/mobile/module/sociallogin/session
    X-Api-Key: <your platform API key>
    Content-Type: application/json
    
    { "code": "<the code from the deep link>" }

    The response holds access_token, refresh_token and expires_in.

The code works once, within SOCIAL_MOBILE_HANDOFF_TTL seconds. If a refusal happens before the deep link, the browser shows your Laramin's Sign-In screen with the reason, such as "That sign-in cannot return to the address it asked for." when the deep link isn't on the allowlist.

On-phone sign-in

Setup

In Social Login, edit the provider and fill in the client ID each app signs in with:

  • Google: iOS Client ID and Android Client ID, created for your apps in Google Cloud Console.
  • Apple: iOS Client ID, set to your iOS app's bundle ID.

A token issued to a client ID that isn't filled in is refused, so a token minted for somebody else's app can't be used to sign in here.

The flow

The app signs in with the provider's SDK, then sends the ID token:

HTTP
POST /api/v1/mobile/module/sociallogin/google/exchange
X-Api-Key: <your platform API key>
Content-Type: application/json

{ "id_token": "<the ID token from the provider's SDK>" }

The response holds access_token, refresh_token and expires_in. Send an ID token, not an access token, and never both.

Two-factor authentication

With Core 12.8 or later, a social sign-in for an account that has set up two-factor authentication doesn't return tokens straight away. Both session and exchange answer with data.two_factor instead, and the app finishes the sign-in with the person's code at POST /api/v1/mobile/login/two-factor, exactly as after a password. See Sign people in from a mobile app.

Refusals

ResponseMeaning
401 from exchangeAny refusal: unknown provider, a provider without on-phone sign-in, a token for a client ID that isn't filled in, an address the provider doesn't vouch for that belongs to an existing account, sign-up closed, or an inactive account. All look the same on purpose. The reason is in your Laramin's application log.
401 from sessionThe code is wrong, used already or expired. Start again.
403 UNAUTHORIZED, message "Access denied from your network address. Please contact your administrator."From Social Login 2.1.2: your Laramin's IP rules refuse the phone's network address for the account the credential proved, exactly as they would refuse a password sign-in on the web. No token and no two-factor challenge is issued, and a handoff code is used up. From 2.1.3, for a credential that would create an account, the global rules decide and no account is created. In the browser flow, a refused address is stopped in the browser, on your Laramin's Sign-In screen with the same sentence, and the app gets no code. Ask an administrator, or sign in from an allowed network. See How IP access control works.
403 PASSWORD_CHANGE_REQUIREDWith Core 12.8 or later: an administrator asked the person to change their password. They choose a new one with Forgot password first.
403 TWO_FACTOR_ENROLMENT_REQUIREDWith Core 12.8 or later: your Laramin requires two-factor authentication and the person hasn't set it up. They set it up on the web at errors.enrol_url.
429Too many attempts from one IP address. Wait and try again.

If on-phone sign-in fails while everything looks right, check the platform's client ID on the provider first.