Connectivity Notification Service
/
Setting up authentication
Last updated

Setting up authentication

Connectivity Notifications Service (CNS) requires you to implement a token-based authentication service that issues JSON Web Tokens (JWTs) upon request. This follows the OAuth 2.0 protocol flow, with CNS acting as the client and your system as the authorization server.

When CNS needs to push a notification, it uses a pre-fetched JWT with the Bearer Authentication scheme with the request.

You must provide your authentication endpoint details and the initial client secrets to Booking.com through the Provider Portal interface. These credentials will enable CNS to request JWT tokens from the partner's authentication service as needed.

Authentication flow

The following diagram shows the authentication initialization and usage flow for notification delivery:

Authentication Flows

Step-by-step process

A1. Generate authentication credentials:

  • You generate client credentials (client ID and client secret) using your authentication system.

A2: Share with Booking.com

  • Using the Provider Portal share the credentials with Booking.com.
  • Share the authentication token endpoint.
  • Share the endpoint to receive notifications.
  • For more details, see Configuring Notification subscriptions.

A3: CNS requests token

  • CNS sends a request to your token endpoint, which is part of your OAuth 2.0 authorization server implementation.
  • The request includes client ID, client secret (for authentication), and 'grant type' parameter set to client_credentials.

Example request:

curl --location 'https://auth-endpoint-url' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={clientId}' \
--data-urlencode 'client_secret={clientSecret}'

Example response body:

{
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NDE5NjgzNTEsImV4cCI6MTc0MTk3MTk1MSwiY2xpZW50IjoiQi5jb20ifQ.HQ1zj6v18RErPJLUaGFhxcxl9JhLjsxyydKZQyGa9oH30Y5HSLjQk06SDgSocZ-8Fs98rUBn-3GUm_DRn-vTeKJl5869xtDfzLFETesUHuBJpdFM4hevsm97APDqzMJ3wzjRajkgzjjurQpw0AiPpcgAPLTRmjIn14iwTUN5myfdcnlzvKuAASh0a224ooM1nLornaub3oChKubxaWy0Pmq3A4bdaTuHtz20E_CBcfTU1JEfcEHguSV61iLteDU6sc53aRsVtlcmXBObzq_ARohDPur3pyJSBmbJuU-7JOA4Yt4_u9mlM7RcVScGibZgah2AkoZxT10ECbn_6Y-ytQ",
    "ruid": "980ceb59-2790-7841-b172-57f1c9489653"
}

A4: Validate credentials and return a JWT

  • Your authorization server validates the credentials.
  • If valid, it generates and returns a JWT access token. (Example: request and response)
  • The token contains relevant claims (expiration time, scope, issuer, etc.).
  • The server returns the token to CNS as a JSON response.

B1: CNS includes the JWT in subsequent API requests using the Bearer scheme.

  • While pushing a notification, Booking.com adds the Bearer JWT token onto the Authorization header of the request.

Example request:

curl -X POST 'https://endpoint-url' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NDE5NjgzNTEsImV4cCI6MTc0MTk3MTk1MSwiY2xpZW50IjoiQi5jb20ifQ.HQ1zj6v18RErPJLUaGFhxcxl9JhLjsxyydKZQyGa9oH30Y5HSLjQk06SDgSocZ-8Fs98rUBn-3GUm_DRn-vTeKJl5869xtDfzLFETesUHuBJpdFM4hevsm97APDqzMJ3wzjRajkgzjjurQpw0AiPpcgAPLTRmjIn14iwTUN5myfdcnlzvKuAASh0a224ooM1nLornaub3oChKubxaWy0Pmq3A4bdaTuHtz20E_CBcfTU1JEfcEHguSV61iLteDU6sc53aRsVtlcmXBObzq_ARohDPur3pyJSBmbJuU-7JOA4Yt4_u9mlM7RcVScGibZgah2AkoZxT10ECbn_6Y-ytQ' \
-d '{
  "metadata": {
    "uuid": "message-uuid",
    "type": "message-type",
    "payloadVersion": "1.0"
  },
  "payload": {
    // Message specific payload
  }
}'

B2: Your system verifies the JWT token while processing the pushed notification.

  • Your resource server validates the token before processing requests.

C1: Booking.com is responsible for refreshing the Bearer JWT tokens before they expire.

Generating JWTs

The generated JWTs should contain a header, a payload, and a signature.

The header should exactly contain the following:

{
    "alg": "RS256",
    "typ": "JWT"
}

The payload should contain at least the creation (iat, issued at) and expiration times (exp) as Unix timestamps. It's acceptable to include more metadata if required. Bear in mind that the payload does not get encrypted, only encoded. So avoid sharing any sensitive data.

Example payload:

{
    "iat": 1741968351,
    "exp": 1741971951,
    "client": "B.com"
}

The signature should be generated through the RSA SHA256 algorithm, with a private key, similar to:

RSA_SHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    secret
)

A full JWT token should contain the header, the payload, and the signature strings, separated by periods, all base-64 encoded.

JWT token example

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NDE5NjgzNTEsImV4cCI6MTc0MTk3MTk1MSwiY2xpZW50IjoiQi5jb20ifQ.HQ1zj6v18RErPJLUaGFhxcxl9JhLjsxyydKZQyGa9oH30Y5HSLjQk06SDgSocZ-8Fs98rUBn-3GUm_DRn-vTeKJl5869xtDfzLFETesUHuBJpdFM4hevsm97APDqzMJ3wzjRajkgzjjurQpw0AiPpcgAPLTRmjIn14iwTUN5myfdcnlzvKuAASh0a224ooM1nLornaub3oChKubxaWy0Pmq3A4bdaTuHtz20E_CBcfTU1JEfcEHguSV61iLteDU6sc53aRsVtlcmXBObzq_ARohDPur3pyJSBmbJuU-7JOA4Yt4_u9mlM7RcVScGibZgah2AkoZxT10ECbn_6Y-ytQ

with public key:
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6S7asUuzq5Q/3U9rbs+P
kDVIdjgmtgWreG5qWPsC9xXZKiMV1AiV9LXyqQsAYpCqEDM3XbfmZqGb48yLhb/X
qZaKgSYaC/h2DjM7lgrIQAp9902Rr8fUmLN2ivr5tnLxUUOnMOc2SQtr9dgzTONY
W5Zu3PwyvAWk5D6ueIUhLtYzpcB+etoNdL3Ir2746KIy/VUsDwAM7dhrqSK8U2xF
CGlau4ikOTtvzDownAMHMrfE7q1B6WZQDAQlBmxRQsyKln5DIsKv6xauNsHRgBAK
ctUxZG8M4QJIx3S6Aughd3RZC4Ca5Ae9fd8L8mlNYBCrQhOZ7dS0f4at4arlLcaj
twIDAQAB
-----END PUBLIC KEY-----

You can use the token.dev JWT debugger for development purposes.

Requirements and recommendations

This section contains recommendations and any requirements for a smooth authentication flow.

Functional requirements

  • Connectivity Partners should provide the authentication endpoint that serves back JWTs (short-lived tokens).
  • Connectivity Partner should sign the JWTs using the RS256 algorithm.
  • Connectivity Partner should implement a secret-generator that can generate secure UUID4 secrets for the long-term client secret, while also configuring the authentication endpoint to recognize the said secrets.
  • Connectivity Partner’s systems should support TLS 1.2 or higher.
  • If an invalid token is received, Connectivity Partner’s system should return a HTTP 401 error.

Non-functional requirements

The following are a few recommendations:

  • A one hour JWT time-to-live duration.
  • Rotating client secrets once a year.

Best practices

This section lists the Best practices around setting up the authentication endpoint.

  • Monitor authentication errors (HTTP 401) with an automatic alert.
Previous page
Next page