Migrating from getToken to getIdToken

To improve security and performance, we are introducing the getIdToken method to the Miro Web SDK and deprecating the getToken method on March 17, 2021. If your Miro Web SDK application currently uses the getToken method, you must update your web-plugin to use the getIdToken method no later than September 1, 2021.

What this means for you

The getIdToken method returns a JSON Web Token (JWT), an encoded form of JSON data, signed by the application secret. You can use JWTs to authenticate requests from your Miro web-plugin to your backend services. You can use an existing JWT library to decode the token and establish the communication between your Miro web-plugin and your backend services.

A JWT token contains the following three Base64-encoded parts that are concatenated by periods ("."):

  • Header
  • Payload
  • Signature

The payload contains the following elements, which provide contextual information about the call:

Claim Description
sub ID of the web-plugin for which the JWT token is issued. This is the Client ID on the Miro App Settings page. App dashboard →
iss Issuer: OAuth Client ID. In this scenario, Miro.
team ID of the team to which the JWT token is assigned.
exp Identifies the expiration time on or after which the JWT must not be accepted for processing. The exp claim’s processing requires that the current date/time is before the expiration date/time provided in the exp claim. Implementers can account for some small leeway, usually no more than a few minutes, to account for clock skew. The exp claim value must be a number containing a NumericDate value.

NumericDate

A JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date/time, ignoring leap seconds. This is equivalent to the IEEE Std 1003.1, 2013 Edition [POSIX.1] definition "Seconds Since the Epoch."

user ID of the user to which the JWT token is assigned.
iat Timestamp indicating when the JWT token was issued.

Note that JWTs are credentials that can grant access to resources. Do not share your JWTs and store them securely.

Calls from your Miro Web-plugin frontend to your backend services using JWT Sample

The Miro Javascript SDK includes the getIdToken method so your Miro web-plugin can retrieve a JWT to communicate with your backend services:

miro.onReady(async () => {
  try {
    // You might have used the getToken method in your old code here
    // Here is how you can use getIdToken method instead of getToken
    // Use getIdToken() to retrieve a JWT
    const token = await miro.getIdToken()
    // Include this token in a call to your backend services
    const response = await fetch('/your-web-plugin-server-endpoint', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        authorization: `Bearer ${token}`
      },
      body: JSON.stringify(data) // some custom data
    })
  } catch (e) {
    // Error handling
  }
})

Here are the steps to handle a JWT on your backend:

  1. Extract the JWT token from the Authorization parameter in the HTTP request header.
  2. Decode the Base64-encoded JWT token and verify it with your application secret.
  3. Lookup the user data received via OAuth flow for the user and team.
  4. Perform the required application logic.

For example, using Node.js:

const jsonwebtoken = require('jsonwebtoken')
 
// Retrieve secret
const appSecret = process.env.APPLICATION_SECRET
// ......
// Request handler
let token = ''
if (req.headers && req.headers.authorization) {
 const parts = req.headers.authorization.split(' ')
 if (parts.length == 2) {
   const scheme = parts[0]
   const credentials = parts[1]
 
   if (/^Bearer$/i.test(scheme)) {
     token = credentials
   }
 }
}
 
jsonwebtoken.verify(token, appSecret, (err, jwtPayload) => {
 if (err) {
   // Error handling
 } else {
   const user = userStore.find(jwtPayload.user, jwtPayload.team)
   if (user) {
     // Perform the required application logic
   }
 }
})

Need help?

Have any questions about the upcoming changes or need any assistance? Ask a question in the Miro community, and we'll make sure to assist as quickly as we can. Have fun building with Miro web-plugins, and make sure to let us know what you're building!


Did this page help you?