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 link | On-phone sign-in | |
|---|---|---|
| The app opens | The phone's browser | The provider's own sign-in, such as Google Sign-In or Sign in with Apple |
| Works with | Every provider except Twitter (OAuth 1.0a) | Google and Apple |
| The app receives | A single-use code in a deep link | An ID token from the provider |
| The app sends it to | POST /api/ | POST /api/ |
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
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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 flows | Meaning |
|---|---|
web_redirect | Sign-in through the website. Every provider. |
mobile_redirect | The browser and deep link flow. |
id_token | On-phone sign-in. |
config holds the values an app needs to start on-phone sign-in, such as client_id_ios and client_ for Google. It never holds a secret. Read the flows from this list rather than hard-coding which providers support what.
Browser and deep link
Server setup
Whoever runs your server sets these in the .env file:
| Variable | What it does | Default |
|---|---|---|
SOCIAL_ | The 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_ | Seconds a sign-in may take, from start to coming back from the provider. | 300 |
SOCIAL_ | Seconds 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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
https://<your Laramin's address>/auth/<key>/mobile/callbackReplace the highlighted values with your own.
The flow
-
The app opens this address in the phone's browser, not in a web view inside the app:
Plain textCouldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
https://crm.example.com/auth/google/mobile/redirect?redirect=myapp://auth/callback -
The person signs in at the provider, which returns them to your Laramin's mobile callback.
-
Your Laramin finishes the sign-in and opens the deep link with a single-use code:
myapp://auth./callback ?code=… -
The app trades the code for tokens:
HTTPCouldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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_tokenandexpires_in.
The code works once, within SOCIAL_ 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:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
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/, exactly as after a password. See Sign people in from a mobile app.
Refusals
| Response | Meaning |
|---|---|
401 from exchange | Any 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 session | The 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_ | With 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_ | With 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. |
429 | Too 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.
Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.laramin.in. The online article may have changed since.