Skip to content

Security for Crowdin Apps

To ensure the high level of security for cases when the Crowdin app works with the data from Crowdin (i.e. uses the authorization via crowdin_app), we’ve developed a security mechanism. The main principle of this security mechanism is based on the exchange of the JWT token between Crowdin and the Crowdin app. JWT token is signed with an OAuth Client Secret known only to the two final parties. This way, the Crowdin app can get a confirmation that the page is opened precisely in Crowdin.

Implementation

To implement the authorization and authentication in your Crowdin app, follow these steps:

  • Add the authorization via crowdin_app to your app descriptor and add the OAuth Client ID that will be used for authorization.
  • Add the callback to your Crowdin app that will handle the Installed Event.
  • Specify the necessary set of scopes in your app descriptor needed for your Crowdin app. The specified set of scopes shouldn’t exceed the scopes specified in the OAuth.

Using the above methods, on each request to the Crowdin app, Crowdin will pass a set of parameters along with a security token, which can be validated by a secret from the OAuth.

Below you can see an example of the URL used by Crowdin to open a module page.

Terminal window
https://example.com/app-module?jwtToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJCcjRhMmhwUW……MX0.yt-lbv3Z8JyIGX4jG405mjZvX8lwc1q0EfWdTtm9GCc&origin=https://{domain}.crowdin.com&clientId=your-client-id

Query parameters:

jwtToken

Type: string

Description: JWT token used for authorization.

origin

Type: string (url)

Description: Host used for opening a module page.

clientId

Type: string

Description: The ID of the OAuth Client used for authorization.

The best practice would be adding middleware to the Crowdin app to verify whether each request has a token with a valid signature and expiry. You can use one of the existing libraries to validate the authenticity of the token.

JWT Token Structure

JWT token consists of the following parts:

  • Header - contains information about the type of the token and encoding algorithms.
  • Payload - contains additional information about the issue and expiration dates of the token, the information about the token issuer and requestor, and other contextual information.
  • Signature - the part with a signature based on the header and payload.

JWT token payload example:

{
"aud": "Br4a2hpQiNW96anuuO4a",
"sub": "1",
"domain": null,
"context": {},
"iat": 1600000000,
"exp": 1600000900
}

Properties:

aud

Type: string

Description: ID of the OAuth Client that issued the token.

sub

Type: string

Description: Identifier of the user that is making a request to the Crowdin app.

domain

Type: string|null

Required: yes

Description: The name of the organization from which the app is accessed. For Crowdin the domain value is always null

context

Type: object

Description: The information about the environment where the Crowdin app module is opened (e.g. project, locale, user’s timezone, etc.).

iat

Type: integer

Description: Identifies the issue time of the token.

exp

Type: integer

Description: Identifies the expiration time of the token.

Was this page helpful?