Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -986,6 +986,35 @@ Google ID tokens are RS256-signed JWTs. The discovery document advertises RS256,

Google authentication is permissive by default for local bearer-token workflows. Set `google.strict_scopes: true` in seed config to require emulator-issued, unexpired access tokens on Gmail, Calendar, Drive, and userinfo routes. Invalid credentials return `401 UNAUTHENTICATED`; missing method scopes return `403` with `insufficientPermissions`. Strict mode distinguishes read, write, send, settings, and metadata scopes, and userinfo includes only granted identity claims. Revoking an access or refresh token invalidates the linked access and refresh credentials. Discovery, signing keys, and the sign-in page remain public. This mode checks method scopes; resource-specific grants such as `drive.file` and Gmail add-on scopes are not modeled.

When OAuth clients are configured, `POST /oauth2/token` takes the client's credentials as `client_id` and `client_secret` in the body (`client_secret_post`) or in an HTTP Basic `Authorization` header (`client_secret_basic`), for both the authorization code and refresh token grants. Body credentials sent with the header must repeat it: a different `client_id` or `client_secret`, or a `client_secret` without `client_id`, returns `400 invalid_request`. As Google does, the emulator compares the Basic username and password as sent, without form-decoding them.

`messages.send` and `drafts.send` deliver the message to each `To`, `Cc`, and `Bcc` recipient who is a user of the emulator. Before delivery, `From` must be a single mailbox whose address is one of the sender's send-as addresses (`GET .../settings/sendAs`). Otherwise it is replaced with their default send-as address. Either way, the message fields and the raw MIME `From` are rebuilt from the checked name and address. The recipient gets a copy labeled `INBOX` and `UNREAD`, without the `Bcc` header, threaded with the messages it replies to in their mailbox, and with their filters applied. Recipients who aren't emulator users are skipped. A message sent to yourself stays one message, labeled `SENT`, `INBOX`, and `UNREAD`, unless your own filters remove those labels. `messages.insert` and `messages.import` don't deliver.

`POST /oauth2/token` accepts the JWT bearer grant (`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`) for service accounts seeded under `google.service_accounts`. Each key takes the `key_id` from the account's key file and its PEM public key or X.509 certificate, so the private key stays with the code under test.

```yaml
google:
users:
- email: alice@example.com
service_accounts:
- client_email: archiver@my-project.iam.gserviceaccount.com
client_id: "104523180291234567890"
keys:
- key_id: 5f0c2b7e9a
public_key: |
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
domain_wide_delegation:
- client_id: "104523180291234567890"
scopes:
- https://www.googleapis.com/auth/gmail.readonly
```

The assertion must be RS256-signed by one of the account's keys, with `iss` set to the account's `client_email`, a space-delimited `scope`, `aud` set to `https://oauth2.googleapis.com/token` or the emulator's own `/oauth2/token` URL, and an `exp` at most 65 minutes after `iat`. A `kid` that names none of the account's keys falls back to trying every key. The response has `access_token`, `expires_in: 3600`, `scope`, and `token_type: Bearer`, and no refresh token. Without `sub`, the token acts as the service account, including under `google.strict_scopes`. With `sub`, it acts as that user, and every requested scope must be granted to the account's `client_id` under `google.domain_wide_delegation`. Under `google.strict_scopes`, Gmail, Calendar, and Drive check the token's scopes as they do for other tokens.

Errors follow Google's JWT error table: `invalid_scope` for an empty `scope`, `invalid_grant` for an unknown `sub` user, an unknown account, a bad signature, a wrong audience, or an expired or too-long-lived assertion, `401 unauthorized_client` when the account has no delegation or none of the requested scopes are delegated, and `403 access_denied` when only some of them are. The other errors return `400`. User suspension, key expiry, and `target_audience` ID tokens are not modeled.

- `GET /o/oauth2/v2/auth` - authorization endpoint
- `POST /oauth2/token` - token exchange
- `GET /oauth2/v2/userinfo` - get user info
Expand Down
31 changes: 31 additions & 0 deletions apps/web/content/docs/google.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,35 @@ Google ID tokens are RS256-signed JWTs. The discovery document advertises RS256,

Google authentication is permissive by default for local bearer-token workflows. Set `google.strict_scopes: true` in seed config to require emulator-issued, unexpired access tokens on Gmail, Calendar, Drive, and userinfo routes. Invalid credentials return `401 UNAUTHENTICATED`; missing method scopes return `403` with `insufficientPermissions`. Strict mode distinguishes read, write, send, settings, and metadata scopes, and userinfo includes only granted identity claims. Revoking an access or refresh token invalidates the linked access and refresh credentials. Discovery, signing keys, and the sign-in page remain public. This mode checks method scopes; resource-specific grants such as `drive.file` and Gmail add-on scopes are not modeled.

When OAuth clients are configured, `POST /oauth2/token` takes the client's credentials as `client_id` and `client_secret` in the body (`client_secret_post`) or in an HTTP Basic `Authorization` header (`client_secret_basic`), for both the authorization code and refresh token grants. Body credentials sent with the header must repeat it: a different `client_id` or `client_secret`, or a `client_secret` without `client_id`, returns `400 invalid_request`. As Google does, the emulator compares the Basic username and password as sent, without form-decoding them.

## Service Accounts

`POST /oauth2/token` accepts the JWT bearer grant (`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`) for service accounts seeded under `google.service_accounts`. Each key takes the `key_id` from the account's key file and its PEM public key or X.509 certificate, so the private key stays with the code under test.

```yaml
google:
users:
- email: alice@example.com
service_accounts:
- client_email: archiver@my-project.iam.gserviceaccount.com
client_id: "104523180291234567890"
keys:
- key_id: 5f0c2b7e9a
public_key: |
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
domain_wide_delegation:
- client_id: "104523180291234567890"
scopes:
- https://www.googleapis.com/auth/gmail.readonly
```

The assertion must be RS256-signed by one of the account's keys, with `iss` set to the account's `client_email`, a space-delimited `scope`, `aud` set to `https://oauth2.googleapis.com/token` or the emulator's own `/oauth2/token` URL, and an `exp` at most 65 minutes after `iat`. A `kid` that names none of the account's keys falls back to trying every key. The response has `access_token`, `expires_in: 3600`, `scope`, and `token_type: Bearer`, and no refresh token. Without `sub`, the token acts as the service account, including under `google.strict_scopes`. With `sub`, it acts as that user, and every requested scope must be granted to the account's `client_id` under `google.domain_wide_delegation`. Under `google.strict_scopes`, Gmail, Calendar, and Drive check the token's scopes as they do for other tokens.

Errors follow Google's JWT error table: `invalid_scope` for an empty `scope`, `invalid_grant` for an unknown `sub` user, an unknown account, a bad signature, a wrong audience, or an expired or too-long-lived assertion, `401 unauthorized_client` when the account has no delegation or none of the requested scopes are delegated, and `403 access_denied` when only some of them are. The other errors return `400`. User suspension, key expiry, and `target_audience` ID tokens are not modeled.

## Gmail

- `GET /gmail/v1/users/:userId/messages` - list messages (`q`, `labelIds`, `maxResults`, `pageToken`)
Expand All @@ -30,6 +59,8 @@ Google authentication is permissive by default for local bearer-token workflows.
- `POST /gmail/v1/users/:userId/messages/:id/trash` - trash message
- `POST /gmail/v1/users/:userId/messages/:id/untrash` - untrash message

`messages.send` and `drafts.send` deliver the message to each `To`, `Cc`, and `Bcc` recipient who is a user of the emulator. Before delivery, `From` must be a single mailbox whose address is one of the sender's send-as addresses (`GET .../settings/sendAs`). Otherwise it is replaced with their default send-as address. Either way, the message fields and the raw MIME `From` are rebuilt from the checked name and address. The recipient gets a copy labeled `INBOX` and `UNREAD`, without the `Bcc` header, threaded with the messages it replies to in their mailbox, and with their filters applied. Recipients who aren't emulator users are skipped. A message sent to yourself stays one message, labeled `SENT`, `INBOX`, and `UNREAD`, unless your own filters remove those labels. `messages.insert` and `messages.import` don't deliver.

## Gmail Drafts

- `GET /gmail/v1/users/:userId/drafts` - list drafts
Expand Down
1 change: 1 addition & 0 deletions apps/web/tests/fixtures/docs-baseline.json
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,7 @@
"ogTitle": "Google API | emulate",
"headings": [
"OAuth & OpenID Connect",
"Service Accounts",
"Gmail",
"Gmail Drafts",
"Gmail Threads",
Expand Down
31 changes: 31 additions & 0 deletions packages/@emulators/google/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,35 @@ npm install @emulators/google
- `GET /.well-known/openid-configuration` — OIDC discovery document
- `GET /oauth2/v3/certs` — JSON Web Key Set (JWKS) with the RSA public key for ID token verification

When OAuth clients are configured, `POST /oauth2/token` takes the client's credentials as `client_id` and `client_secret` in the body (`client_secret_post`) or in an HTTP Basic `Authorization` header (`client_secret_basic`), for both the authorization code and refresh token grants. Body credentials sent with the header must repeat it: a different `client_id` or `client_secret`, or a `client_secret` without `client_id`, returns `400 invalid_request`. As Google does, the emulator compares the Basic username and password as sent, without form-decoding them.

### Service accounts

`POST /oauth2/token` accepts the JWT bearer grant (`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`) for service accounts seeded under `google.service_accounts`. Each key takes the `key_id` from the account's key file and its PEM public key or X.509 certificate, so the private key stays with the code under test.

```yaml
google:
users:
- email: alice@example.com
service_accounts:
- client_email: archiver@my-project.iam.gserviceaccount.com
client_id: "104523180291234567890"
keys:
- key_id: 5f0c2b7e9a
public_key: |
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
domain_wide_delegation:
- client_id: "104523180291234567890"
scopes:
- https://www.googleapis.com/auth/gmail.readonly
```

The assertion must be RS256-signed by one of the account's keys, with `iss` set to the account's `client_email`, a space-delimited `scope`, `aud` set to `https://oauth2.googleapis.com/token` or the emulator's own `/oauth2/token` URL, and an `exp` at most 65 minutes after `iat`. A `kid` that names none of the account's keys falls back to trying every key. The response has `access_token`, `expires_in: 3600`, `scope`, and `token_type: Bearer`, and no refresh token. Without `sub`, the token acts as the service account, including under `google.strict_scopes`. With `sub`, it acts as that user, and every requested scope must be granted to the account's `client_id` under `google.domain_wide_delegation`. Under `google.strict_scopes`, Gmail, Calendar, and Drive check the token's scopes as they do for other tokens.

Errors follow Google's JWT error table: `invalid_scope` for an empty `scope`, `invalid_grant` for an unknown `sub` user, an unknown account, a bad signature, a wrong audience, or an expired or too-long-lived assertion, `401 unauthorized_client` when the account has no delegation or none of the requested scopes are delegated, and `403 access_denied` when only some of them are. The other errors return `400`. User suspension, key expiry, and `target_audience` ID tokens are not modeled.

### Gmail
- `GET /gmail/v1/users/:userId/messages` — list messages with `q`, `labelIds`, `maxResults`, and `pageToken`
- `GET /gmail/v1/users/:userId/messages/:id` — fetch message in `full`, `metadata`, `minimal`, or `raw` formats
Expand All @@ -31,6 +60,8 @@ npm install @emulators/google
- `POST /gmail/v1/users/:userId/messages/:id/trash` — trash message
- `POST /gmail/v1/users/:userId/messages/:id/untrash` — untrash message

`messages.send` and `drafts.send` deliver the message to each `To`, `Cc`, and `Bcc` recipient who is a user of the emulator. Before delivery, `From` must be a single mailbox whose address is one of the sender's send-as addresses (`GET .../settings/sendAs`). Otherwise it is replaced with their default send-as address. Either way, the message fields and the raw MIME `From` are rebuilt from the checked name and address. The recipient gets a copy labeled `INBOX` and `UNREAD`, without the `Bcc` header, threaded with the messages it replies to in their mailbox, and with their filters applied. Recipients who aren't emulator users are skipped. A message sent to yourself stays one message, labeled `SENT`, `INBOX`, and `UNREAD`, unless your own filters remove those labels. `messages.insert` and `messages.import` don't deliver.

### Drafts
- `GET /gmail/v1/users/:userId/drafts` — list drafts
- `POST /gmail/v1/users/:userId/drafts` — create draft
Expand Down
Loading
Loading