Migrating to FCM v1 endpoint

Sinch currently requests FCM push notifications using the FCM legacy endpoint, which is deprecated and will reach End of Life in June 2024 (see Firebase FAQ). To continue using FCM, your Sinch application must be migrated to use the FCM v1 API instead, which is the current supported method from Firebase/Google.

If you want Sinch to keep sending FCM push notifications to your Android devices after June 2024, you must follow this migration guide. If you don't, Sinch won't be able to request FCM push messages on your behalf.

OAuth2.0 authentication in FCM v1

The main difference between the FCM legacy endpoint and FCM v1 is the authentication method, as FCM v1 only supports short-lived access tokens, according to the OAuth2 security mode. This means you'll have to provide Sinch with those access tokens, which will then in turn be used by Sinch to authenticate with FCM v1 API.

Compared with the current authentication method (that requires you to share a private key with Sinch), this is a more secure approach because:

• your FCM private key is stored privately in your backend, and it's never shared with anyone
• in case an access token is leaked, it can only be used by malicious actors until it expires

Sinch will request you short-lived access tokens for FCM using OAuth 2.0 Client Credentials flow (see overview of Client Credential flow).

Providing FCM tokens to Sinch

In broad terms, the key steps you have to follow to provide FCM tokens are:

1. Implement an OAuth2.0 Authorization Server endpoint (your organization might already have one in place that you can leverage).
2. Implement another endpoint, protected by a standard OAuth2.0 Client Credentials flow, that provides FCM tokens ("FCM token endpoint") valid for FCM v1 API
3. Provide Sinch with:
   • OAuth2.0 Client Credentials ( client_id , client_secret , scope ) that are valid within your own OAuth domain
   • URL of your Auth Server
   • URL of the FCM tokens endpoint
   • The ID of the FCM project you're using in your app (more info about that in Providing OAuth configuration to Sinch )

Overview

The desired flow after the migration is complete is the following:

Key takeaways from the diagram above

1. When Sinch needs a new access_token_FCM (required to request a push message via FCM v1 API), it will first make a request to your Authorization Server to obtain a access_token_RO valid for your security domain ( RO as in Resource Owner ).
2. Having obtained an access_token_RO , Sinch will make a subsequent request to your FCM access token endpoint, providing access_token_RO as a Bearer token.
3. Your Resource Server should obtain the access_token_FCM using one of the methods recommended in the Firebase documentation .
4. Your Resource Server should pass the access_token_FCM (as received from Firebase) in the response back to Sinch.

Sinch will only make requests to "Your Auth Server" endpoint and "Your FCM Token endpoint" as needed, not for every push message sent. Sinch will cache the FCM access token in accordance to the value of expires_in.

Contextualizing the diagram in the OAuth2.0 standard

1. The component labeled "Your FCM Token endpoint" is your OAuth2.0 Resource Server , with the resource being the FCM tokens.
2. The scope mentioned in the diagram is OAuth2.0 Scope , and its default value is https://www.googleapis.com/auth/firebase.messaging .
3. The tokens provided by "Your Auth server" and "Your FCM token endpoint" are OAuth2.0 Access Tokens .
4. The requests to "Your Auth server" and "Your FCM Token endpoint" will have Content-Type: application/x-www-form-urlencoded , according to OAuth2 standard .

Providing OAuth configuration to Sinch

Select your app in the Sinch Dashboard, and the In-app Voice & Video SDKs tab. The configuration for FCM consists of the following fields:

Implementing the FCM Token Endpoint

As described in the overview, Sinch will make a request to your Resource Server FCM token endpoint, requesting an FCM access token. The request will be of the following form:

    POST /<your FCM token endpoint>
    Authorization: Bearer <Access token obtained from your Authorization Server>
    Content-Type: application/x-www-form-urlencoded

    grant_type=client_credentials
    fcm_project_id=<Your FCM Project Id>

Example response to Sinch:

    HTTP/1.1 200 OK
    Content-Type: application/json;charset=utf-8
    {
      "access_token": "<access token acquired from Firebase>",
      "expires_in": 3600,
      "token_type": "Bearer"
    }

Notes:

• Sinch will be able to use this access_token to send push messages to your end-user devices until the token expires, upon which Sinch will issue a new token request to your Authorization Server and Resource Server ; the recommendation is that you obtain a new FCM access token every time Sinch requests it.
• Your implementation of this resource endpoint should obtain an FCM access_token using one of the methods recommended by the Firebase documentation .
• You will receive your fcmProjectId as a request parameter ( fcm_project_id ).

Resources

• FCM documentation
• OAuth2.0 official website
• OAuth2.0 RFC
• Client Credentials flow
• Google client libraries , to support FCM token generation