When creating features like Paths, Queries, or Events in Creator Studio, users’ should integrate with third-party systems while enforcing proper permissions for both users and the bot. This ensures that users cannot access data or perform actions they are not authorized to, maintaining security and functionality.
While configuring a third-party system using Creator Studio, Moveworks recommends choosing the JSON Web Tokens (JWT) authentication mechanism or OAuth2. We support a number of authentication mechanisms, so if JWT or OAuth2 are not available, you could also choose other secure mechanisms such as PKI, NTLM.
What is JWT?
JWT, or JSON Web Token, is a standard for creating access tokens that allow users to securely authenticate and access protected resources. JWTs are widely used in web applications and APIs, as they provide a simple, flexible, and secure way to transmit authentication and authorization data between different parties. This JWT Introduction is a great place to learn more, and comes with a built-in JWT Debugger to explore what JWTs look like.
At its core, a JWT is simply a string of characters that represents a JSON object. This object contains a set of claims that describe the identity and permissions of a user or application. These claims typically include:
- Issuer (iss): The entity that issued the token, typically a server or authentication service. An example issuer would be “AcmeCorp”
- Subject (sub): The unique identifier of the user or application the token represents. An example subject would be “GetUserPTOBalanceToken”
- Audience (aud): The intended recipient of the token, typically a specific application or API. An example audience would be “MoveworksCreatorStudio”
- Expiration time (exp): The time after which the token is no longer valid. An example expiration time would be 15 minutes
- Not before (nbf): The time before which the token cannot be used. An example not before value would be prior to the current time at time of creation, usually by 3-4 minutes to account for clock skew
- Issued at (iat): The time at which the token was issued. The time the token was issued
- Custom claims (Public or Private): Custom data that can be included in the token to provide additional context or information. An example would be the users’ email address
- JWT Identifier (jti): A unique identifier for this specific JWT (Forces token to only be allowed to be used once) An example would be a UUIDv4 token, such as 848cef2e-7b80-4b94-XXXX-1f6dac232f5f Together, these claims allow JWTs to serve as self-contained and stateless authentication tokens that can be easily verified and trusted by different parties.
How JWT Works?
The process of creating and verifying a JWT typically involves three steps:
- Token Creation - When Moveworks bot requests access to a protected resource on behalf of the user, the server or authentication service creates a JWT containing the necessary claims. This JWT is typically signed using a secret key or public/private key pair, which ensures that the token cannot be tampered with.
- Token Transmission - Once the JWT has been created, it will be appended to the third party request setup within Creator Studio. This can be done in a variety of ways depending upon the third-party application, though we would recommend sending it as a HTTPS header.
- Token Verification - When the bot sends a request to access a protected resource, the third-party application server or API must verify the JWT to ensure that it is valid and authorized. This typically involves checking the signature of the JWT to ensure that it has not been tampered with, as well as verifying the claims to ensure that they match the expected values.
Advantages of JWT
There are several advantages to using JWTs in web applications and APIs:
- Stateless: JWTs are self-contained and do not require server-side state, which can make them more scalable and easier to manage.
- Secure: JWTs are typically signed and encrypted, which makes them resistant to tampering and interception by unauthorized parties.
- Flexible: JWTs can include custom claims that provide additional context or information, which can be useful in a variety of scenarios.
- Standardized: JWTs are a widely adopted standard, which means that many libraries and frameworks support them out of the box.
- Timely: JWTs expire at whatever time range you are comfortable with (We would recommend 15-20 minutes), which makes it significantly harder to abuse stolen or leaked JWTs due to them expiring so quickly.
ACLs in Creator Studio: Currently, we have the ability to limit who can trigger the Path, Event, or Query via the ACL configuration step (the final step when setting up any action within Creator Studio). It provides users a mechanism to prevent large scale impersonation, as they can limit who can query what.
Questions to avoid creating: While building a Path or Query, it is important to consider the type of data users will be required to provide to the bot. In general, data that could be used as an identifier for the third-party connector should be scrutinized. For example, build Paths so they don’t require users to enter their email address, as Moveworks currently does not have the capability to validate that the email address being used by the Path or Query belongs to the user who triggered it.