Google Cloud Identity Platform Blocking Functions

Google Cloud's Identity Platform (GCIP)
aims to provide Developers with Google-grade Authentication and Security for
their applications, services, APIs, or anything else that requires identity and
authentication.

Identity Platform allows you to trigger Cloud Functions synchronously (blocking
flow) in response to the following authentication events

- Before user account creation
- Before user sign-in completion

These triggers block the underlying authentication events from completing and
allows you to customize these events using your custom code in Cloud Functions.
They are different from the asynchronous pub/sub-modeled OnCreate and
OnDelete triggers (integrated with
Cloud Functions for Firebase)
that execute after a user account has been created or deleted and doesn't block
the underlying authentication event.

Blocking Functions
enable the following capabilities

- Block user sign-up or sign-in from succeeding if it doesn't meet certain
criteria (example from a banned email domain, certain IP addresses etc.)
- Update user profile information (displayName, photoURL, disabled,
emailVerified, etc).
- Modify or define persistent or session-specific custom claims on a user.

Table of Contents

1. Before you start
1. Blocking functions general behavior
1. Writing blocking functions
1. Forwarded OAuth credentials
1. Access Control
1. Sample blocking functions

Before you start

To use blocking functions (beforeCreate and beforeSignIn) with Google Cloud
Identity Platform:

1. Create a project on Google Cloud Console and enable
Identity Platform.

2. Enable the sign-in providers you want to support through Identity Platform.
The following providers are supported for blocking functions:

- Email/password and Email link
- Social: Google, Facebook, Apple, Twitter, GitHub, Microsoft, Yahoo,
LinkedIn
- Games: Google Play Games + Game Center for iOS
- SAML
- OIDC
- Phone authentication
- Multi-factor authentication with SMS. This will only trigger beforeSignIn
events.

3. Deploy an HTTP trigger for the blocking function

- Using the Cloud Console

- Go to Cloud Functions
- Select Create Function
- Give the function a name
- Select a GCP region.
- Select an HTTP trigger type.
- The HTTP trigger should allow unauthenticated invocations so that
Identity Platform server can access it.
- Click Save
- Click Next to write the function.
- Click Deploy to deploy the newly created trigger.

- Using gcloud CLI
Install gcloud SDK, if you have
not already done so.

Initialize gcloud via command line:

``bash
gcloud init
# Update components to latest.
gcloud components update
`

Follow the instructions below on how to
write an authentication blocking function.

`bash
# Deploy a beforeCreate HTTP trigger.
gcloud functions deploy $before_create_func_name --runtime nodejs10 --trigger-http --allow-unauthenticated
# Deploy a beforeSignIn HTTP trigger.
gcloud functions deploy $before_signin_func_name --runtime nodejs10 --trigger-http --allow-unauthenticated
`

$before_create_func_name and $before_signin_func_name are the
corresponding function names. In the example below,
$before_create_func_name would be myBeforeCreateFunc.

`javascript
exports.myBeforeCreateFunc = auth.functions().beforeCreateHandler((user, context) => {
// ...
});
`

Learn more about
GCF HTTP triggers.

4. Register the blocking function triggers with Identity Platform
- In the Identity Platform Cloud Console section
- Go to the Settings menu
- In the Triggers tab, click the drop down menu for the relevant event
(beforeCreate, beforeSignin or both) for which you want to trigger your
cloud function.
- Select the HTTP trigger previously deployed.
- If no function is deployed yet, click on Create Function. This will
redirect you to Google Cloud Functions and and allows you to set up an
HTTP trigger.
The GCF Cloud Console UI is convenient for simple functions.
For more complicated functions that require access to a code editor,
consider using the gcloud SDK. After deploying the HTTP trigger with GCF,
go back to the Identity Platform Triggers section and select the newly
deployed trigger from the event drop down menu.
- Optional: To forward additional inbound IdP credentials (IdP access tokens
or refresh tokens, etc), expand the Include token credentials section
and select the credentials to forward. For example, to forward the Google
ID token, access token and refresh token of a signed in user, check the
boxes for ID token, Access token and Refresh token. By doing
so, the function will receive these IdP credentials. This setting applies
to both events. The following OAuth credentials can be forwarded:

- ID token: Available for OIDC providers or social providers that are
OIDC compliant.
- Access token: Available for OAuth 2.0 providers or OIDC providers
with code flows enabled. This also refers to the Twitter OAuth access
token used in addition with the token secret.
- Refresh token: Available for OAuth 2.0 providers or OIDC providers
with code flows enabled.

- Click Save to complete.

Warning: Deleting a GCF HTTP trigger registered with Identity Platform
without first unregistering it (setting the trigger to None) in the Identity
Platform Cloud Console UI will result in all users failing to sign in or sign
up to your application.

Blocking functions general behavior

- When triggered, your function should respond within 7 seconds. After this
time, Identity Platform will timeout and return an error.
- A non-200 HTTP response from your function will result in the underlying
authentication event failing and the error propagating to the client.
Visit blocking function default error codes to learn more.
- If you delete the underlying function in Cloud Functions, you must update
the trigger in Identity Platform and set it to none. Failure to do so will
result in an error propagating to the client.
- Note that Identity Platform will trigger these functions for all the users
in your project. If you have enabled multi-tenancy in your project and are
authenticating users for that tenant, the blocking functions will be
triggered for these tenant users as well. Identity Platform will pass on
tenant information to your function, which you can use in your code and apply
appropriate logic.

Writing blocking functions

gcip-cloud-functions module is provided to help verify the incoming request,
parse the payload, and return the response to the Auth server in the right
format. The only requirement is to provide a callback function which takes the
user record and context information and returns either an object of user
properties/custom claims that need to be modified or throw an error to force
the sign-in or sign-up operation to fail

$3

Refer to the cloud functions documentation on
how to write cloud functions.
The provided code needs to be structured following the GCF
requirement.

In the package.json file, the gcip-cloud-functions npm module needs to be
provided:

`javascript
"dependencies": {
"gcip-cloud-functions": "^0.0.1"
}
`

If installing via CLI, this can also be done via command line:

`bash
npm install gcip-cloud-functions --save
`

In the index.js (the file used to export the functions), the
gcip-cloud-functions module needs to be required.

Using commonjs:

`javascript
const gcipCloudFunctions = require('gcip-cloud-functions');
`

Using ES6 imports:

`javascript
import * as gcipCloudFunctions from 'gcip-cloud-functions';
`

When initializing an Auth instance for usage with blocking functions,
the projectId is needed to ensure only events targeting this project are
allowed. The projectId can be explicitly specified but since the code will be
running in GCP infrastructure, the library will be able to auto-discover it by
calling the GCE metadata server internal. This is the recommended process to
initialize an Auth client.

`javascript
const authClient = new gcipCloudFunctions.Auth();
`

If there is a need to manually provide the project ID, you can also specify it
via environment variable GCP_PROJECT during deployment. In gcloud, this is
done via --set-env-vars flag. If deploying the function via the Cloud Console
UI, the environment variables can be set in the
Variables, networking and advanced settings menu.

`bash


Deploy a beforeCreate HTTP trigger.


gcloud functions deploy $before_create_func_name --runtime nodejs10 \
--trigger-http --allow-unauthenticated --set-env-vars GCP_PROJECT=$project_id
`

$3

#### Event trigger

This event is triggered when a new user attempts to sign up (credential
verified or validated) and right before the user is saved in the Auth database
and the ID token and refresh tokens are returned to the client.
You can create a function that triggers before a user is created using the
Auth#functions().beforeCreateHandler() event handler:

`javascript
exports.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
// ...
});
`

Before a user creation event completes, the event handler callback will trigger
with a
UserRecord
object, identifying the user about to be created, and an
extended
EventContext
object.

When user creation is allowed, the callback is expected to return a response
(synchronous or asynchronous via Promise) with the optional attributes of the
user to be modified on the newly created user. If nothing is returned, the
operation will succeed without modifying the user.

`javascript
exports.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
return {
// If no display name is provided, set it to Guest.
displayName: user.displayName || 'Guest';
};
});
`

When the operation is disallowed, raise an HttpsError. This will surface to
the client API.

`javascript
exports.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
if (!isAuthorizedEmail(user.email)) {
throw new gcipCloudFunctions.https.HttpsError(
'invalid-argument', Unauthorized email "${user.email}");
}
});
`

Users created via Admin SDK (Authenticated REST API), CLI or Cloud Console will
not trigger the beforeCreate event. Only users created via the client API will
trigger this event.

#### Response fields that can be modified

Only modification of the following fields is allowed: displayName,
photoURL, customClaims, emailVerified, disabled. Note that
sessionClaims are not supported in beforeCreate. To set sessionClaims,
beforeSignIn needs to be used in addition to beforeCreate.

Supported sign-up methods:

- Email link
- Email/Password
- Federated sign in (OAuth, OIDC, SAML))
- phone number sign-in
- Game Center sign-in

| Supported response fields | Type | beforeCreate behavior |
|-|-|-|
| displayName | string | Persisted in database and propagated to ID token ("name" claim).
Propagated to beforeSignIn event if available. |
| disabled | boolean | Persisted in the database. This signals that the account is created in disabled mode. Client should throw USER_DISABLED error and account set as disabled. No beforeSignIn event should be triggered. |
| emailVerified | boolean | Persisted in database and propagated to ID token ("email_verified" claim).
Propagated to beforeSignIn event if available.
Note that emailVerified is not propagated to the ID token if no email is set on the account. |
| photoURL | string (URL) | Persisted in database and propagated to ID token ("picture" claim)..
Propagated to beforeSignIn event if available. |
| customClaims | Object with 1K byte size limit and no reserved OIDC claim names. | Persisted in the database and propagated to the ID token.
Stored as single value (no delta modifications) and also propagated to beforeSignIn event if available.
If beforeSignIn returns customClaims, they will completely overwrite customClaims from beforeCreate.
If beforeSignIn returns sessionClaims, the beforeSignIn claims will be merged with beforeCreate claims and beforeSignIn claims will overwrite overlapping claims.
Example 1:
beforeCreate returns {a: 1, b: 2, e: 0} custom claims
beforeSignIn returns {c: 3, d: 4, e: 5} session claims
In the Auth database, the user record will have {a: 1, b: 2, e: 0} as custom claims.
In the user's ID token, the following claims will be available: {a: 1, b: 2, c: 3, d: 4, e: 5}
Note that refreshing the user's token will preserve these claims: {a: 1, b: 2, c: 3, d: 4, e: 5}
Example 2:
beforeCreate returns {a: 1, b: 2, e: 0} custom claims
beforeSignIn returns {c: 3, d: 4, e: -1} custom claims
beforeSignIn returns {f: 6, g: 7, e: 5} session claims
beforeCreate custom claims will be completely replaced with beforeSignIn custom claims.
In the Auth database, the user record will have {c: 3, d: 4, e: -1} as custom claims.
In the user's ID token, the following claims will be available: {c: 3, d: 4, e: 5, f: 6, g: 7}
Note that refreshing the user's token will preserve these claims: {c: 3, d: 4, e: 5, f: 6, g: 7} |
| Non-200 error response | Throwing an HttpsError | Blocks user sign-up and propagates error immediately to client. No other event triggered after. |

#### End-to-end example

In the following example where an email/password user is created, only specific
email domains are allowed to succeed. Additional custom claims and a default
photo URL are set on the user.

Client logic

This event is triggered when a new user is created in the
client SDK.

`javascript
// Blocking functions can also be triggered in a multi-tenant context before user creation.
// firebase.auth().tenantId = 'tenant-id-1';
firebase.auth().createUserWithEmailAndPassword('johndoe@example.com', 'password')
.then((result) => {
result.user.getIdTokenResult()
})
.then((idTokenResult) => {
console.log(idTokenResult.claim.admin);
})
.catch((error) => {
if (error.code === 'auth/internal-error' &&
error.message.indexOf('Cloud Function') !== -1) {
// Unauthorized email "johndoe@example.com".
extractAndDisplayErrorMessage(error.message);
} else {
...
}
});
`

Server logic

A subscribed HTTP trigger will be called as a result of the above.

`javascript
// Import the Cloud Auth Admin module.
const gcipCloudFunctions = require('gcip-cloud-functions');

// Initialize the Auth client.
const authClient = new gcipCloudFunctions.Auth();

// Http trigger with Cloud Functions.
exports.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
// If the user is authenticating within a tenant context,
// the tenant ID can be determined from
// user.tenantId or from context.resource,
// eg. 'projects/project-id/tenant/tenant-id-1'

// Only users of a specific domain can sign up.
if (user.email.indexOf('@acme.com') !== -1) {
// Add custom claim and photo URL to authorized user before resolving.
return {
// User still needs to be verified by admin.
customClaims: {verified: false},
// Automatically add some default guest photo URL.
photoURL: 'https://www.example.com/profile/default/photo.png',
};
}
// Errors will translate to code auth/internal-error on the client side.
throw new gcipCloudFunctions.https.HttpsError(
'invalid-argument', Unauthorized email "${user.email}");
});
`

$3

#### Event trigger

This event is triggered when an existing user attempts to sign in (credential
verified), just before the ID token and refresh tokens are returned to the
client. This event will also trigger for new users after the beforeCreate
handler is triggered and processed. However, if beforeCreate fails,
beforeSignIn will not trigger. If beforeSignIn fails after beforeCreate is
triggered, the user is still created and saved in the Auth database, but the
sign-in attempt will fail.

You can create a function that triggers before a user is signed in using the
Auth#functions().beforeSignInHandler() event handler:

`javascript
// Http trigger with Cloud Functions.
exports.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
// ...
});
`

Before a user sign-in event completes, the event handler callback will trigger
with a
UserRecord
object, identifying the user about to be signed in, and an extended
EventContext
object.

When user sign-in is allowed, the callback is expected to return a response
(synchronous or asynchronous via Promise) with the optional attributes of the
user to be modified on the user attempting to sign in. If nothing is returned,
the operation will succeed without modifying the user.

`javascript
exports.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
// Check current user's access level and return it in user's custom claims.
// This will be persisted in the database for all sessions. For session only
// persistence, sessionClaims should be used instead.
return getUserAccessLevel(user.uid).then((level) => {
customClaims: {
accessLevel: level,
}
});
});
`

When the operation is disallowed, raise an HttpsError. This will surface to
the client API.

`javascript
exports.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
// Block sign-in until the user is verified.
if (!user.emailVerified)) {
throw new gcipCloudFunctions.https.HttpsError(
'invalid-argument',
Email "${user.email}" needs to be verified before access is granted.);
}
});
`

Multi-factor authentication with SMS: beforeSignIn will only trigger on
users with second factors after the second factor challenge is successfully
solved and before the ID token is issued for that user.

#### Response fields that can be modified

Only modification of the following fields is allowed: displayName, photoURL,
customClaims, emailVerified, disabled. An additional beforeSignIn
specific field, sessionClaims, field is also supported.

Supported sign-in methods:

- Email link
- Email/Password
- Federated sign in (OAuth, OIDC, SAML)
- Phone number sign-in
- Game Center sign-in
- Multi-factor auth (SMS) sign-in

| Supported response fields | Type | beforeSignIn behavior |
|-|-|-|
| displayName | string | Persisted in database and propagated to ID token ("name" claim)..
Will overwrite beforeCreate value in token if returned. |
| disabled | boolean | Persisted in the database. This should block current sign-in with the USER_DISABLED error thrown client side. The disabled status of the user is persisted in the Auth database. Other live sessions will fail on token refresh with USER_DISABLED error. |
| emailVerified | boolean | Persisted in database and propagated to ID token ("email_verified" claim). Will overwrite beforeCreate value in token if returned.
Note that emailVerified is not propagated to the ID token if no email is set on the account. |
| photoURL | string (URL) | Persisted in database and propagated to ID token ("picture" claim). Will overwrite beforeCreate value in token if returned. |
| customClaims | Object with 1K byte size limit and no reserved OIDC claim names.
Note that the combined sessionClaims and customClaims fields should also not exceed 1K byte. | Behaves similarly to customClaims in beforeCreate.
Persisted in database and propagated to ID token but will be overwritten in user's token claims with overlapping claims defined in sessionClaims.
If beforeCreate also returns customClaims, they will be replaced with beforeSignIn customClaims.
Example:
beforeSignIn returns {a: 1, b: 2, e: 0} custom claims
beforeSignIn returns {c: 3, d: 4, e: 5} session claims
In the Auth database, the user record will have {a: 1, b: 2, e: 0} as custom claims.
In the user's ID token, the following claims will be available: {a: 1, b: 2, c: 3, d: 4, e: 5}
Note that refreshing the user's token will preserve these claims: {a: 1, b: 2, c: 3, d: 4, e: 5} |
| sessionClaims | Object with 1K byte size limit and no reserved OIDC claim names.
Note that the combined sessionClaims and customClaims fields should also not exceed 1K byte. | This will only propagate to token (for current session) and will merge with beforeCreate/beforeSignIn custom claims while overwriting overlapping claims from beforeCreate/beforeSignIn. These will only be reflected in the current session and not persisted in the Auth database. This should behave like custom token claims where claims are stored in the refresh token and preserved on token refresh.
If both custom and session claims are returned, the session claims will be merged with custom claims and session claims will overwrite overlapping claims.
Example:
customClaims defined in beforeCreate or beforeSignIn as {a: 1, b: 2, e: 0}
beforeSignIn returns sessionClaims {c: 3, d: 4, e: 5}
In the Auth database, the user record will have {a: 1, b: 2, e: 0} as custom claims.
In the user's ID token, the following claims will be available: {a: 1, b: 2, c: 3, d: 4, e: 5}
Note that refreshing the user's token will preserve these claims: {a: 1, b: 2, c: 3, d: 4, e: 5} |
| Non-200 error response | | Blocks user sign-in and propagates error immediately to the client. |

#### End-to-end example

In the following example, an email/password user signing in will get blocked
if the request is coming from a disallowed region or IP address. In addition,
the user level of access is determined and set via custom claims before the
sign-in operation completes.

Client logic

This event is triggered when a new user is created in the
client SDK.

`javascript
// Blocking functions can also be triggered in a multi-tenant context
// before user sign-in.
// firebase.auth().tenantId = 'tenant-id-1';
firebase.auth().signInWithEmailAndPassword('user@domain.com', 'password')
.then((result) => {
result.user.getIdTokenResult()
})
.then((idTokenResult) => {
console.log(idTokenResult.claim.admin);
})
.catch((error) => {
if (error.code === 'auth/internal-error' &&
error.message.indexOf('Cloud Function') !== -1) {
// Unauthorized request origin!
extractAndDisplayErrorMessage(error.message);
} else {
...
}
});
`

Server logic

A subscribed HTTP trigger will be called as a result of the above.

`javascript
// Import the Cloud Auth Admin module.
const gcipCloudFunctions = require('gcip-cloud-functions');

// Initialize the Auth client.
const authClient = new gcipCloudFunctions.Auth();

// Http trigger with Cloud Functions.
exports.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
// If the user is authenticating within a tenant context,
// the tenant ID can be determined from user.tenantId or from context.resource,
// eg. 'projects/project-id/tenant/tenant-id-1'
if (!isSuspiciousRequest(context.ipAddress, context.userAgent)) {
return {
customClaims: {
// Check if this existing user is an admin.
admin: isAdmin(user)
}
};
}
throw new gcipCloudFunctions.https.HttpsError(
'permission-denied',
'Unauthorized request origin!');
});
`

$3

Whenever an event is triggered, additional event context will be provided to
the server callback. This provides additional event context, such as the
underlying resource, event type, locale, IP address, etc.

`javascript
exports.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
console.log(context.ipAddress);
// Get type of provider used to sign in with:
const signInProvider = context.eventType.split(':')[1]; // facebook.com
});
`

A comprehensive list of the properties provided in an event context object is
documented below:

| Property | Optional | Description | Example |
|-|-|-|-|
| locale | Yes | The application locale. This is set via the client API (firebase.auth().languageCode = 'fr';) or by passing the locale header in the REST API. This also accepts language-region format, eg. 'sv-SE'. | fr, en, it, en-US, sv-SE, etc. |
| ipAddress | No | The IP address of the end user triggering the blocking function. | 114.14.200.1 |
| userAgent | No | The user agent that triggered the blocking function. | Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36 |
| eventId | No | The event's unique identifier. | rWsyPtolplG2TBFoOkkgyg |
| eventType | No | The event type. This provides information on the event name (beforeSignIn, beforeCreate) and the associated sign-in method used, eg: google.com, password, emailLink, etc. | providers/cloud.auth/eventTypes/user.beforeSignIn:password, providers/cloud.auth/eventTypes/user.beforeCreate:google.com |
| authType | No | The level of permissions for a user. For beforeSignIn and beforeCreate, there is always a known user, hence this will always be "USER". | USER |
| resource | No | The resource that emitted the event. For authentication event, this is of format: projects/projectId or in a multi-tenant context: projects/projectId/tenants/tenantId | projects/project_id, or projects/project_id/tenants/tenant_id (multi-tenant context) |
| timestamp | No | Timestamp for the event as an RFC 3339 string. | Tue, 23 Jul 2019 21:10:57 GMT |
| additionalUserInfo | Yes | Additional user information. This is an AdditionalUserInfo object:

interface AdditionalUserInfo {
// eg. saml.provider, oidc.provider, google.com, facebook.com, etc.
providerId: string;
// Raw user info. This is the raw user info also returned in client SDK.
profile?: any;
// This is the Twitter screen_name.
username?: string;
// Whether the user is new or existing.
// This is true for beforeCreate, false for others.
isNewUser: boolean;
} | {
providerId: 'twitter.com',
profile: {
friends_count: 10,
profile_background_image_url: '...',
id: '...',
screen_name: '...',
},
username: 'twitter-username',
isNewUser: false
} |
| credential | Yes | Inbound IdP credentials if available. This is an AuthCredential object, available when signing in with federated providers, eg. social, SAML and OIDC providers. Raw OAuth credentials will only be available when enabled in the Cloud Console "Include token credentials" trigger settings and are applicable to beforeSignIn and beforeCreate events. By default, credentials are not returned.

interface AuthCredential {
// All user SAML or OIDC claims. These are in plain object format but should
// be verified and parsed from SAML response, IdP ID token, etc.
// This is empty for all other providers.
claims?: {[key: string]: any};
// Optional OAuth ID token if available and enabled in the project config.
idToken?: string;
// Optional OAuth access token if available and enabled in the project config.
accessToken?: string;
// Optional OAuth refresh token if available and enabled in the project config.
refreshToken?: string;
// Optional OAuth expiration if available and enabled in the project config.
expirationTime?: string;
// Optional OAuth token secret if available and enabled in the project config.
secret?: string;
// eg. saml.provider, oidc.provider, google.com, facebook.com, etc.
providerId: string;
}; | // Google credential.
{
idToken: 'GOOG_ID_TOKEN',
accessToken: 'GOOG_ACCESS_TOKEN',
refreshToken: 'GOOG_REFRESH_TOKEN',
expirationTime: 'Tue, 08 Sep 2020 08:06:51 GMT',
providerId: 'google.com'
}
// SAML credential.
{
claims: {
eid: 'EMPLOYEE_ID',
role: 'EMPLOYEE_ACCESS_LEVEL',
groups: 'EMPLOYEE_GROUP_ID'
},
providerId: 'saml.my-provider-id'
} |

$3

The following error codes can be thrown from a blocking function via an
HttpsError. An HttpsError can be initialized using one of the error codes
below (following the Google Cloud API
errors).
A default error message is provided for each error code. A custom message can
also be provided to override the default message.

| Error code | HTTP Status code | Default error message |
|-|-|-|
| invalid-argument | 400 | Client specified an invalid argument. |
| failed-precondition | 400 | Request can not be executed in the current system state. |
| out-of-range | 400 | Client specified an invalid range. |
| unauthenticated | 401 | Request not authenticated due to missing, invalid, or expired OAuth token |
| permission-denied | 403 | Client does not have sufficient permission. |
| not-found | 404 | Specified resource is not found. |
| aborted | 409 | Concurrency conflict, such as read-modify-write conflict. |
| already-exists | 409 | The resource that a client tried to create already exists. |
| resource-exhausted | 429 | Either out of resource quota or reaching rate limiting. |
| cancelled | 499 | Request cancelled by the client. |
| data-loss | 500 | Unrecoverable data loss or data corruption. |
| unknown | 500 | Unknown server error. |
| internal | 500 | Internal server error. |
| not-implemented | 501 | API method not implemented by the server. |
| unavailable | 503 | Service unavailable. |
| deadline-exceeded | 504 | Request deadline exceeded. |

Note that the HTTP non-200 status codes will not be returned to the client.
Instead they will be returned to the Auth server and wrapped in another error
object before surfacing to the client.

To throw an error with the default error message:

`javascript
throw new gcipCloudFunctions.https.HttpsError('permission-denied');
`

To throw an error with a custom error message:

`javascript
throw new gcipCloudFunctions.https.HttpsError(
'permission-denied', 'Unauthorized request origin!');
`

Currently, the error will be surfaced to the client side wrapping the details
of the error thrown in the blocking functions. Currently, the error is surfaced
as an INTERNAL_ERROR, where $XYZ is the HTTP error code (eg. 400),
$STATUS_CODE is the error status code (eg. INVALID_ARGUMENT) and
$BLOCKING_FUNCTION_MESSAGE Is the default or custom error message returned
in the function.

| Web error codes (error.code) | iOS Error name | Android Error Code | Description (error.message in JS SDK) |
|-|-|-|-|
| auth/internal-error | ERROR_INTERNAL_ERROR | ERROR_INTERNAL_ERROR (FirebaseException Android Exception) | HTTP Cloud Function returned an error. Code: $XYZ, Status: "$STATUS_CODE", Message: "$BLOCKING_FUNCTION_MESSAGE" |

Example

In this example, the HttpsError thrown in the function will surface to the
client like this:

`javascript
throw new gcipCloudFunctions.https.HttpsError(
'invalid-argument', Unauthorized email ${user.email});
`

Client SDK error code: auth/internal-error
Client error message: HTTP Cloud Function returned an error. Code: 400,
Status: "INVALID_ARGUMENT", Message: "Unauthorized email user@evil.com"

REST API backend error sample:

`javascript
{
"error": {
"code": 400,
"message": "BLOCKING_FUNCTION_ERROR_RESPONSE : HTTP Cloud Function returned an error. Code: 400, Status: \"INVALID_ARGUMENT\", Message: \"Unauthorized email user@evil.com\"",
"errors": [
{
"message": "BLOCKING_FUNCTION_ERROR_RESPONSE : HTTP Cloud Function returned an error. Code: 400, Status: \"INVALID_ARGUMENT\", Message: \"Unauthorized email user@evil.com\"",
"domain": "global",
"reason": "invalid"
}
]
}
}
`

Forwarded OAuth credentials

The following table documents the different credentials / data that can be
forwarded (additional requirements may be needed for some of the credentials
to be returned) to the blocking functions depending on the IdP the user signs
in with:

| IdP | ID token | Access Token | Expiration Time | Token Secret | Refresh Token | Sign in claims |
|-----------|----------|--------------|-----------------|--------------|---------------|----------------|
| Google | ✓ | ✓ | ✓ | | ✓ | |
| Facebook | | ✓ | ✓ | | | |
| Twitter | | ✓ | | ✓ | | |
| GitHub | | ✓ | | | | |
| Microsoft | ✓ | ✓ | ✓ | | ✓ | |
| LinkedIn | | ✓ | ✓ | | | |
| Yahoo | ✓ | ✓ | ✓ | | ✓ | |
| Apple | ✓ | ✓ | ✓ | | ✓ | |
| SAML | | | | | | ✓ |
| OIDC | ✓ | ✓ | ✓ | | ✓ | ✓ |

Refresh tokens for OIDC and OAuth 2.0 based providers will be forwarded to
the blocking function if the refresh token checkbox is checked in the
Include token credentials expandable menu in the Cloud Console
Triggers section. However, some identity providers either do not expose
refresh tokens or may require additional parameters to be requested client-side
when the sign-in operation is initiated.

For all providers, when signing in directly with an OAuth credential (eg. ID
token or Access token), as opposed to the 3-legged OAuth flow: The same OAuth
credential provided client-side will be forwarded to the blocking function. No
refresh token will be available in this case.

`javascript
// The same credential provided here will be forwarded to the blocking function.
// In this case, the Google ID token will be forwarded.
const credential = firebase.auth.GoogleAuthProvider.credential(id_token);
firebase.auth().signInWithCredential(credential);
`

The documentation below explains the different behavior between providers when a 3-legged OAuth flow is used for sign-in.

$3

When a user signs in with a generic OIDC provider, the following credentials
will be forwarded:

- OIDC ID token if the id_token flow is selected.
- OIDC ID token and access token if the code flow is selected.

The additional refresh token will also be made available only when the
offline_access
scope is selected.

`javascript
const provider = new firebase.auth.OAuthProvider('oidc.my-provider');
provider.addScope('offline_access');
firebase.auth().signInWithPopup(provider);
`

$3

When a user signs in with Google, only the Google ID token and access tokens
are forwarded. The refresh token will only be available in the following case:

- The access_type=offline custom parameter should be requested.
- If the user previously consented and no new scope was requested, the
prompt=consent custom parameter should be requested.

Learn more about
Google refresh tokens.

`javascript
const provider = new firebase.auth.GoogleAuthProvider();
provider.setCustomParameters({
'access_type': 'offline',
'prompt': 'consent'
});
firebase.auth().signInWithPopup(provider);
`

$3

Facebook identity provider does not return OAuth refresh tokens.
However, Facebook will return an access token that can be exchanged for another
access token. Learn more about the different types of
access tokens
supported by Facebook and how you can exchange them for
long-lived tokens.

$3

GitHub does not support refresh tokens but will return access tokens that do
not expire unless revoked. GitHub access tokens will be forwarded to the
blocking function.

$3

When a user signs in with the Microsoft provider, the Microsoft ID token,
access token will be forwarded to the blocking function.
The additional refresh token will also be made available only when the
offline_access scope is selected, similar to other OIDC based providers.

`javascript
const provider = new firebase.auth.OAuthProvider('microsoft.com');
provider.addScope('offline_access');
firebase.auth().signInWithPopup(provider);
`

$3

When a user signs in with Yahoo, the Yahoo ID token, access token and refresh
token are always forwarded without any additional custom parameters or scopes.

$3

LinkedIn does not return refresh tokens and only an access token is provided.

$3

"Sign in with Apple" will forward the ID token, access token and refresh token
to the blocking function.

Access Control

Modified fields returned in the function response will be propagated to the
user's ID token.

`javascript
exports.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
return {
displayName: 'John Doe',
photoURL: 'https://lh3.googleusercontent.com/-IcZWqgdWEGY/123456789/photo.jpg',
emailVerified: true,
customClaims: {
employee_id: '987654321'
},
sessionClaims: {
role: 'admin',
group_id: '123',
},
};
});
`

The claims are propagated to the ID token as illustrated in the token payload
below.

`javascript
{
"iss": "https://securetoken.google.com/PROJECT_ID",
// Profile changes are also persisted in the database.
"name": "John Doe",
"picture": "https://lh3.googleusercontent.com/-IcZWqgdWEGY/123456789/photo.jpg",
"aud": "PROJECT_ID",
"auth_time": 1528854045,
"user_id": "cxncXcCb84YySchlOOrFjNIOnIY2",
"sub": "cxncXcCb84YySchlOOrFjNIOnIY2",
"iat": 1528922063,
"exp": 1528925663,
"email": "johndoe@gmail.com",
// Profile changes are also persisted in the database.
"email_verified": true,
"firebase": {
"identities": {
"email": [
"johndoe@gmail.com"
],
"google.com": [
"1234567890"
]
},
"sign_in_provider": "password"
},
// sessionClaims apply to the current session only.
"role": "admin",
"group_id": "123",
// customClaims are persisted on all sessions.
"employee_id": "987654321"
}
`

$3

Access control can also be enforced based on the modified claims returned in
the blocking functions.

#### Using the Admin SDK

You can manually verify the ID token of the user if you are using your own
server side code with some external database

Retrieve the ID token on the client (using web client SDK)

`javascript
auth.currentUser.getIdToken().then(function(idToken) {
// Send token to your backend via HTTPS
// ...
}).catch(function(error) {
// Handle error
});
`

Verify the ID token server side after you send it to your server
(using Node.js
Admin SDK)

`javascript
// idToken comes from the client app.
admin.auth().verifyIdToken(idToken)
.then((decodedToken) => {
const uid = decodedToken.uid;
const name = decodedToken.name;
const picture = decodedToken.picture;
const emailVerified = decodedToken.email_verified;
const role = decodedToken.role;
const groupId = decodedToken.group_id;
}).catch((error) => {
// Handle error
});
`

Learn more about ID token verification from our
official documentation.

#### Using Firestore security rules

Access control based on persistent or session claims can be enforced via
Cloud Firestore security rules.

`
service cloud.firestore {
match /databases/{database}/documents {
match /users/{userId} {
allow read: if request.auth.uid == userId;
allow create, update, delete: if request.auth.uid == userId &&
request.auth.token.role == 'admin';

}
}
}
`

Sample blocking functions

The following sample blocking functions illustrate some common use cases.

$3

Only allow users for a specific email domain to sign up.

`javascript
export.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
if (!user.email || user.email.indexOf('@acme.com') === -1) {
throw new gcipCloudFunctions.https.HttpsError(
'invalid-argument', Unauthorized email "${user.email}");
}
});
`

$3

Only allow sign-up via identity providers that verify emails.

`javascript
export.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
if (user.email && !user.emailVerified) {
throw new gcipCloudFunctions.https.HttpsError(
'invalid-argument', Unverified email "${user.email}");
}
});
`

$3

Allow users with unverified emails to sign up. On sign up, send an email
verification to the user. Sign in will be blocked until the user verifies
their email.

`javascript
export.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
const locale = context.locale;
if (user.email && !user.emailVerified) {
// Send custom email verification on sign-up
// https://firebase.google.com/docs/auth/admin/email-action-links
return admin.auth().generateEmailVerificationLink(user.email).then((link) => {
return sendCustomVerificationEmail(user.email, link, locale);
});
}
});

export.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
if (user.email && !user.emailVerified) {
throw new gcipCloudFunctions.https.HttpsError(
'invalid-argument',
"${user.email}" needs to be verified before access is granted.);
}
});
`

$3

On sign up, look up additional claims for the associated user from an external
database and set them as custom claims on the user.

`javascript
const db = admin.firestore();
export.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
return db.collection('adminEmails').doc(user.email).get()
.then((doc) => {
// Set admin to true if the user is an admin.
customClaims: {admin: doc.exists}
});
});
`

$3

If a developer considers certain identity providers as verified, set the email
as verified on sign up.

`javascript
export.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
if (user.email &&
!user.emailVerified &&
context.eventType.indexOf(':facebook.com') !== -1) {
return {
emailVerified: true,
};
}
});
`

$3

Block sign in from certain regions or IP addresses.

`javascript
export.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
if (isSuspiciousIpAddress(context.ipAddress)) {
throw new gcipCloudFunctions.https.HttpsError(
'permission-denied', 'Unauthorized access!');
}
});
`

$3

The IP address could be injected into the ID token claims on sign-in.
This is useful to detect possible token theft. For example if a sign-in event
was detected in one region and then an authenticated request with an ID token
from the same session is sent from a geographically different region,
re-authentication could be required for that user.

`javascript
export.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
return {
sessionClaims: {
signInIpAddress: context.ipAddress,
},
};
});
`

On authenticated access, the sign-in IP address source can be compared relative
to request IP address source.

`javascript
app.post('/getRestrictedData', (req, res) => {
// Get the ID token passed.
const idToken = req.body.idToken;
// Verify the ID token, check if revoked and decode its payload.
admin.auth().verifyIdToken(idToken, true).then((claims) => {
// Get request IP address
const requestIpAddress = req.connection.remoteAddress;
// Get sign-in IP address.
const signInIpAddress = claims.signInIpAddress;
// Check if the request IP address origin is suspicious relative to session
// IP address.
// The current request timestamp and the auth_time of the ID
// token can provide additional signals of abuse especially if the IP
// address suddenly changed. If there was a sudden geographical change in a
// short period of time, then it will give stronger signals of possible
// abuse.
if (!isSuspiciousIpAddressChange(signInIpAddress, requestIpAddress)) {
// Suspicious IP address change. Require re-authentication.
// You can also revoke all user sessions by calling:
// admin.auth().revokeRefreshTokens(claims.sub).
res.status(401).send({error: 'Unauthorized access. Please login again!'});
} else {
// Access is valid. Try to return data.
getData(claims).then(data => {
res.end(JSON.stringify(data);
}, error => {
res.status(500).send({ error: 'Server error!' })
});
}
});
});
`

$3

Give each sign-in attempt its own unique session identifier. This unlocks
session tracking and session management capabilities.

`javascript
export.beforeSignIn = authClient.functions().beforeSignInHandler((user, context) => {
return {
sessionClaims: {
sessionId: createUniqueSessionIdentifier(user),
},
};
});
`

$3

Screen user display names or photos for inappropriate content using machine
learning APIs.

`javascript
export.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
if (user.photoURL) {
// https://cloud.google.com/blog/products/gcp/filtering-inappropriate-content-with-the-cloud-vision-api
return isPhotoAppropriate(user.photoURL)
.then((status) => {
if (!status) {
// Sanitize inappropriate photos by replacing them with guest photos.
// Users could also be blocked from sign-up, disabled, etc.
return {
photoURL: PLACEHOLDER_GUEST_PHOTO_URL,
};
}
});
});
`

$3

Set SAML IdP claims on user's custom and session claims.

`javascript
export.beforeSignIn = authClient.functions().beforeCreateHandler((user, context) => {
if (context.credential &&
context.credential.providerId === 'saml.my-provider-id') {
return {
// Employee ID does not change so save in persistent claims (stored in
// Auth DB).
customClaims: {
eid: context.credential.claims.employeeid,
},
// Copy role and groups to token claims. These will not be persisted.
sessionClaims: {
role: context.credential.claims.role,
groups: context.credential.claims.groups,
}
}
}
});
`

$3

Get Google user's refresh token and call Google APIs.
In this example, the refresh token is stored for offline access and a Google
Calendar event is scheduled.

`javascript
const {OAuth2Client} = require('google-auth-library');
const {google} = require('googleapis');
// ...
// Initialize Google OAuth client.
const keys = require('./oauth2.keys.json');
const oAuth2Client = new OAuth2Client(
keys.web.client_id,
keys.web.client_secret
);

export.beforeCreate = authClient.functions().beforeCreateHandler((user, context) => {
if (context.credential &&
context.credential.providerId === 'google.com') {
// Store the refresh token for later offline use.
// These will only be returned if refresh tokens credentials are included
// (enabled by Cloud Console).
return saveUserRefreshToken(
user.uid,
context.credential.refreshToken,
'google.com'
)
.then(() => {
// Blocking the function is not required. The function can resolve while
// this operation continues to run in the background.
return new Promise((resolve, reject) => {
// For this operation to succeed, the appropriate OAuth scope should
// be requested on sign in with Google, client-side. In this case:
// https://www.googleapis.com/auth/calendar
// You can check granted_scopes from within:
// context.additionalUserInfo.profile.granted_scopes (space joined
// list of scopes).

// Set access token/refresh token.
oAuth2Client.setCredentials({
access_token: context.credential.accessToken,
refresh_token: context.credential.refreshToken,
});
const calendar = google.calendar('v3');
// Setup Onboarding event on user's calendar.
const event = {/* ... /};
calendar.events.insert({
auth: oAuth2Client,
calendarId: 'primary',
resource: event,
}, (err, event) => {
// Do not fail. This is a best effort approach.
resolve();
});
});
})
}
});
``