External Identity Providers

Users can sign in with an account they already have at Google, Apple, Facebook or Microsoft. Your client app runs the provider's own sign-in (its SDK or web flow) and sends the result to ErtisAuth, which verifies it with the provider and returns an ErtisAuth token pair, exactly like a password sign-in.

Your app ──(1) provider sign-in──▶ Google / Apple / Facebook / Microsoft
    │                                          │
    │◀──────────(2) provider token ────────────┘
    │
    └──(3) POST /oauth/{slug}/login ──▶ ErtisAuth ──(4) verify──▶ provider
                                           │
    ◀──────────(5) ErtisAuth tokens ───────┘

On the first sign-in the user is created; later sign-ins find the same user again.

Supported providers#

The identity (provider user id, email address) is always taken from the data ErtisAuth gets from the provider, never from what the client claims. Names sent by the client are used only where the provider shares them with the client alone (Apple sends the user's name only once, to the app).

The provider object#

{
	"_id": "66f1c0d2a4b5c6d7e8f90180",
	"type": "Google",
	"name": "Google",
	"slug": "google",
	"description": "Sign in with Google for the web app",
	"defaultRole": "customer",
	"defaultUserType": "customer",
	"appClientId": "1234567890-abc.apps.googleusercontent.com",
	"isActive": true,
	"trust_email": false,
	"membership_id": "66f1c0d2a4b5c6d7e8f90123"
}

You can create several providers of the same type, for example one Google provider per app with its own client id, each with its own slug.

The default user type should allow the fields the provider fills in (firstname, lastname, email_address, username). If it declares an object field named avatar, the provider's profile picture URL is stored in avatar.url.

Signing in#

POST /oauth/{slug}/login
X-Ertis-Alias: <membership_id>
Content-Type: application/json

No token is needed. The body depends on the provider's type.

Google#

{
	"clientId": "1234567890-abc.apps.googleusercontent.com",
	"token": {
		"idToken": "eyJhbGciOiJSUzI1NiIs…"
	}
}

The ID token must be issued for the provider's appClientId, and it must contain the user's email and name: request the openid email profile scopes. A token without them answers 401 ProviderProfileIncomplete.

Facebook#

{
	"appId": "<facebook_app_id>",
	"user": {
		"id": "<facebook_user_id>",
		"first_name": "Ada",
		"last_name": "Lovelace",
		"email": "ada@example.com",
		"accessToken": "<facebook_access_token>"
	}
}

appId must be the provider's appClientId. id, first_name, email and accessToken are required in the body, but the identity and the email address that ErtisAuth uses are read from Facebook with the access token. For Facebook Limited Login (iOS), add ?limited_flow=true to the URL and send the Limited Login authentication token as accessToken.

Microsoft#

{
	"clientId": "<application_client_id>",
	"token": {
		"accessToken": "<access_token_for_microsoft_graph>"
	}
}

The access token must be valid for Microsoft Graph (User.Read).

Apple and AppleNative#

{
	"authorization": {
		"code": "<authorization_code>",
		"id_token": "<id_token>"
	},
	"user": {
		"name": { "firstName": "Ada", "lastName": "Lovelace" },
		"email": "ada@example.com"
	}
}

This is the response of Sign in with Apple, sent as is. user is only present on the user's very first sign-in, when Apple shares the name with the app; send it when you have it. ErtisAuth exchanges code with Apple, so a code can be used only once and expires after a few minutes.

Response#

201 Created with an ErtisAuth token pair, as for a password sign-in.

Errors#

How users are matched#

1. By connected account. Every user keeps the accounts they signed in with in connected_accounts:
   json

   "connected_accounts": [
   	{ "provider": "Google", "slug": "google", "user_id": "109876543210987654321" }
   ]

   A sign-in finds the user whose connected account has the same provider type and provider user id.
2. By email address. If no connected account matches, ErtisAuth looks for a user with the same email address in the membership and links the provider account to it, see below.
3. Sign-up. If no user matches, a new user is created with the provider's defaultRole and defaultUserType, the name and email from the provider, the email address as username, and source_provider set to the provider type. It has no password and signs in through the provider.

Every sign-in records a TokenGenerated event; a sign-up also records UserCreated.

Linking to existing accounts#

Linking a provider account to an existing user by email address is only safe if the provider guarantees that the user owns that address. Otherwise anyone could create a provider account with someone else's email address and take over their ErtisAuth account.

When an existing user has the same email address and the email can't be trusted, the sign-in is rejected with 409 ProviderEmailNotTrusted. The user can sign in with their password and you can then let them connect the account.

Account activation#

When the membership requires activation, users created by a provider sign-up are created inactive like any other user, and they receive the activation mail if the hook is set up.

Signing out#

Revoking an ErtisAuth token also revokes, where the provider supports it, the provider token that was stored with the user's connected account.

Managing providers#

All routes are under /memberships/{membershipId}.

Active providers#

GET /memberships/{membershipId}/providers/active-providers is public, so that sign-in pages can show the right buttons. It returns only the public settings:

[
	{ "_id": "…", "name": "Google", "slug": "google", "type": "Google", "appClientId": "1234567890-abc.apps.googleusercontent.com", "membership_id": "…" },
	{ "_id": "…", "name": "Apple", "slug": "apple", "type": "Apple", "appClientId": "com.example.web", "redirectUri": "https://app.example.com/auth/apple", "membership_id": "…" },
	{ "_id": "…", "name": "Microsoft", "slug": "microsoft", "type": "Microsoft", "appClientId": "…", "tenantId": "…", "membership_id": "…" }
]

Create a provider#

curl -X POST https://auth.example.com/memberships/<membership_id>/providers \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"type": "Apple",
		"name": "Sign in with Apple",
		"slug": "apple",
		"defaultRole": "customer",
		"defaultUserType": "customer",
		"appClientId": "com.example.web",
		"teamId": "ABCDE12345",
		"privateKeyId": "XYZ987WVU6",
		"privateKey": "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMG…\n-----END PRIVATE KEY-----",
		"redirectUri": "https://app.example.com/auth/apple",
		"isActive": true
	}'

Response 201 Created: the provider.

Update a provider#

PUT /memberships/{membershipId}/providers/{id}

Omitted fields keep their current values. type can't change, and a different slug answers 400 ProviderSlugCannotBeChanged. An update without any change answers 409 IdenticalDocumentError.

Delete a provider#

DELETE /memberships/{membershipId}/providers/{id}

Response 204 No Content. Users created by it keep their accounts.

Events#

ProviderCreated, ProviderUpdated and ProviderDeleted. See Events.