In this community call, we discuss mastering JWTs with WSO2 API Manager including - Backend user authentication with JWT - Backend JWT generation - Best practices to validate JWT - User-related claims in JWT - JWT grant

1. WSO2 API Manager Community Call
February 24, 2021
Session 21
Mastering JWTs with WSO2 API Manager

2. Hello!
Meruja Selvamaikkam
Software Engineer
meruja@wso2.com

3. Agenda

4. ● Overview of JWT
⦿ Best practices to validate JWT
● Backend user authentication with JWT
⦿ Backend JWT generation
⦿ User-related claims in JWT
● JWT grant
● Demo - JWT Bearer token
● Q&A
Agenda
4

5. Overview of JWT

6. Overview of JWT
● JSON Web Token (JWT) is used to represent claims that are transferred between two parties, such as the
end-user and the backend.
● The JWT Claims Set represents a JSON object whose members are the claims conveyed by the JWT.
When should you use JSON Web Tokens?
● Authentication: This is the most common scenario for using JWT. Once the user is logged in, each
subsequent request will include the JWT, allowing the user to access routes, services, and resources that
are permitted with that token.
● Information Exchange: JSON Web Tokens are a good way of securely transmitting information between
parties.
6

7. How Do JSON Web Tokens Work?
Browser Server
1. POST/user/login with username and password
3. Return the JWT to the browser
4. Send the JWT on the authorization header
6. Sends response to the client
2. Creates a JWT with a secret
5. Check JWT signature
Get user information from the
JWT
7

8. Best Practices to Validate JWT

9. ● The token is a long string, divided into different parts separated with dots, and each part is base64
encoded.
● If the token is signed it will have three sections:
⦿ header
⦿ payload
⦿ signature
● If the token is encrypted it will consist of five parts:
⦿ header
⦿ encrypted key
⦿ initialization vector
⦿ ciphertext (payload)
⦿ authentication tag
9
Best Practices When Validating JWT

10. ● Algorithm
⦿ The JWA RFC lists all available algorithms that can be used to sign or encrypt JWTs
⦿ The most recommended algorithm is ES256 although still the most popular one is
RS256
● Validate the token
⦿ Always validate an incoming JWT
⦿ If using the implicit flow, and the token is sent back to the client by means of a
redirect URI
10
Best Practices When Validating JWT

11. ● Symmetric signing
⦿ Try to avoid using symmetric signing
⦿ If, for some reason, you have to use symmetric signing try to use ephemeral secrets,
which will help increase security
● Signature
⦿ The signature is used to sign not only the payload of the token but also the header
⦿ Signatures require keys or certificates to be properly validated
11
Best Practices When Validating JWT

12. ● Do not use JWTs for sessions
⦿ JWTs were never considered for use with sessions, and using them in such a way
may actually lower the security of your applications
● Make sure tokens are used as intended
⦿ JWTs can be used as Access Tokens or ID Tokens
● Always check the issuer and the audience
⦿ Be sure that it has been issued by someone you expected to issue it
⦿ The server should expect that the token has been issued for an audience, which the
server is part of
12
Best Practices When Validating JWT

13. Backend User Authentication with JWT

14. Backend JWT Generation
● If you enable JWT generation in WSO2 API Manager, each API request will carry a JWT to
the back-end service
● The JWT is appended as a transport header to the outgoing message
● The back-end service fetches the JWT and retrieves the required information about the
user, application, or token
● You can pass additional attributes to the backend with the JWT or completely change the
default JWT generation logic
● You can change the existing functionality of retrieving end-user related claims to the JWT

15. Enable Backend JWT Generation
● There are some elements that can be configured. If you do not configure these
elements, they take their default values.
⦿ apim.jwt.enable
⦿ apim.jwt.header
⦿ apim.jwt.enable_user_claims
⦿ apim.jwt.claims_extractor_impl
⦿ apim.jwt.claim_dialect
⦿ apim.jwt.convert_dialect
⦿ apim.jwt.signing_algorithm
⦿ apim.jwt.gateway_generator.impl
⦿ apim.jwt.gateway_generator.excluded_claims
15

16. Customizing the User-related Claims in Backend JWT
● Write your own Claim Retriever
implementation by implementing
org.wso2.carbon.apimgt.impl.t
oken.ClaimsRetriever class
● Sample Custom Claim Retriever:
https://github.com/wso2/samples-api
m/blob/master/CustomJWTGenerator/
src/main/java/org/wso2/carbon/test/C
ustomClaimRetriever.java
16

17. Build and Deploy
● Build the project with maven
mvn clean install
● Build the class and copy the jar to <API-M_HOME>/repository/components/lib directory
where the node works as the Key Manager node
● Set the apim.jwt.claims_extractor_impl to your class name
[apim.jwt]
enable_user_claims = true
claims_extractor_impl = "org.wso2.carbon.test.CustomClaimRetriever"
● Start WSO2 API Manager server
./wso2server.sh or wso2server.bat
17

18. JWT Grant

19. 19
JWT contains three parts that are separated by dots ".":
● header
● payload
● signature
header.payload.signature
Sample Header:
JWT Grant

20. 20
The payload contains the following claims:
● iss - Identifies the identity provider that issued the JWT
● sub - Identifies the entity that issued the JWT vouches
● aud - Identifies the authorization server as an intended audience
● exp - Limits the time window during which the JWT can be used
● nbf - Forces a JWT to be used only after a specified time
● iat - Identifies the time at which the JWT was issued
● jti - Provides a unique identifier for the token
● Custom claims — This is the extension point of the JWT specification
JWT Grant - Payload

21. Sample Payload
Source: https://jwt.io/

22. Signature = sign(encodeBase64(header) + '.' + encodeBase64(payload))
assertion = encodeBase64(header) + '.' + encodeBase64(payload) + '.' +
encodeBase64(signature)
If you want to disable the JWT Bearer grant type in the APIM instance, add the following entry to the
deployment.toml file in the <APIM_HOME>/repository/conf/ folder.
[oauth.grant_type.jwt_bearer]
enable = false
Signature

23. Generate JWT Bearer Grant
● Configuring the JWT grant
⦿ Obtain a JWT from an external Identity Provider
⦿ Configure an Identity Provider and a Service Provider in WSO2 API Manager
● Using the JWT grant
⦿ Obtain a JWT from the service provider
⦿ Retrieve the access token from WSO2 API Manager for the generated JWT in the previous
step
23

24. Demo

26. More Info
● How to write a custom JWT generator for WSO2 API Manager
https://www.youtube.com/watch?v=VZ0UER0DR6s
● Best practices to validate JWT
https://curity.io/resources/architect/api-security/jwt-best-practices/
● User-related claims in JWT
https://apim.docs.wso2.com/en/latest/learn/api-gateway/passing-end-user-attributes-to-the-backend/pa
ssing-enduser-attributes-to-the-backend-using-jwt/#customizing-the-user-related-claims-in-jwt
● JWT grants
https://apim.docs.wso2.com/en/latest/learn/api-security/oauth2/grant-types/jwt-grant/#jwt-grant
26

27. Question Time!

28. 28
Next Session
● Thursday, March 25, 2021
● Click on the community call page link to get notified of the next call or submit
your topic suggestions
⦿ Page - https://wso2.com/community/api-management/#CommunityCall
● You can join our ongoing conversations on WSO2 API Manager using the following
channels
⦿ Slack invite - apim-slack.wso2.com
⦿ Twitter - @wso2apimanager
⦿ Email - dev@wso2.org
● You can find out more about our product by visiting
⦿ YouTube - bit.ly/api-life
⦿ Website - WSO2
28

29. wso2.com
Thanks!