Request verification

Requests from Acronis to the callback handler additionally include the Authorization header that allows vendors to verify the request origin and accept the request.

The Authorization header contains a JWT (JSON Web Token) signed by Acronis. The vendor must take the following steps to ensure that JWT is valid and originated from Acronis:

Fetch JWKs (JSON Web Keys)

Send a GET request to the https://cloud.acronis.com/api/idp/v1/keys endpoint to get the list of public JWKs.

The following example demonstrates a response from this endpoint:

{
    "keys": [
        {
            "use": "sig",
            "kty": "RSA",
            "kid": "f9294926-b89b-460b-9c50-8f2e74e6d3db",
            "alg": "RS256",
            "n": "xDm80_tNLSuJxBETvhfyTm5miZqn08fJwPRo0UghBRfYotTAhPma3Uj2hvCO2jOB1777D3-OMmhlJ7oxXOFZcYRElw6FOYTZzfix_jtd6ButcUkfWBQuUUE51w-WGxVhbNagF5no2W4b9zQCLs3Omg1VdA-q1KJe6lIsKdE0ZXEQyfDh2rDFd1mbVj2DkyRrjWoLlpWIZbH--NMO2od047om14oTsaF2Xv6rlm4GMwTs6EKAGtXAKMxX1nu0U3lpgF_8n9fJf98N3nETjIUS5v85-Qxy1kzranzWqZHxt-fxin3GXukifuYF4m5QTb1By5sSiQVL8keZGb1rt-_XpQ",
            "e": "AQAB"
        },
        "..."
    ]
}

Note that you may cache the JWKs to reduce the number of requests and update them according to our keys rotation policy. The JWKs are updated every 24 hours.

Verify the received JWT

When the callback handler receives a request:

1. Fetch the value of the Authorization header and extract the JWT. The format is Bearer <jwt>, where <jwt> is the JWT.

2. Decode the JWT’s header using the library of your choice and fetch the value of the kid field. It may look as follows:

   {
       "alg": "RS256",
       "iri": "ac294f6ec37c7857ba95371bc43d95cd",
       "kid": "c2618afb-9881-472e-a4e4-683f5f057b62"
   }
   

3. Find the corresponding key among stored JWKs by matching the value of the kid field.

4. Decode and verify the JWT’s signature. If the signature is invalid - deny the request.

5. Decode the JWT’s payload. It may look as follows:

   {
       "aud": "cloud.acronis.com",
       "exp": 1710855607,
       "jti": "0e8c4f42-b3f6-4585-8137-880c95f49eff",
       "iat": 1710852007,
       "iss": "https://cloud.acronis.com",
       "sub": "0d780ce3-adcc-5bce-9904-3be60cbd1b9d",
       "scope": [
           {
               "role": "cti.a.p.acgw.endpoint.v1.0~vendor.app.endpoint.v1.0"
           }
       ],
       "ver": 2,
       "sub_type": "platform-acgw"
   }
   

6. Verify that the JWT issuer is https://cloud.acronis.com in the iss field. If the issuer does not match - deny the request.

7. Verify that the JWT is not expired based on the exp field. If the token is expired - deny the request.