Design and Implementation
Implementation Details
- User client sends third party JWT token in the Authorization header of the API call along with the Mashery API Key.
- Connector authenticates based on api key retrieved from the incoming API request.
- If API call is authenticated at Mashery successfully, then Connector looks for token in the Authorization header, otherwise the request is blocked from Mashery and error response with message is returned.
- If JWT token is not missing then Connector fetches the JSON web key (JWK) from the public key URL specified in the input configuration that holds JSON Web Key Set (JWKS).
- JSON Web Key Set is cached in Mashery Memcache for fixed time in order to fulfill future calls or transactions for faster response.
- if http_proxy_server specified in the pre-input configurations, call to retrieve JSON Web Key Set (JWKS) is made through proxy server.
Block Authorization Header Feature
Inject Headers Feature
- In case JWT validation is successful, inject_headers values are retrieved from pre-input.
- From JWT token, claim value for specified claim or JSON Path expression, in the pre-input is retrieved and added into request header.
- Example -
inject_headers: {"X-Mashery-User-Context":"uctx","X-Mashery-Scope":"aud","X-Mashery-App-Id":"$.pib.master_app_id"} . In this case, three headers are added in the request:
- Header Name - X-Mashery-User-Context and Header Value - "uctx" claim value in jwt token.
- Header Name - X-Mashery-Scope and Header Value - "aud" claim value in jwt token.
- Header Name - X-Mashery-App-Id and Header Value - Claim value retrieved from JWT payload using provided JSON Path expression: $.pib.master_app_id
- JSON Path expression can extract value from JWT payload for non-standard claims only.
- Header value is UTF-8 encoded.
- In case specified claim or value fetched from JSON Path expression, is not present in JWT token, then no corresponding header is added in the request.
- Specified claims in pre-inputs which are present in JWT payload, only those claims is added as header in the request.
- In case any claims specified in the pre-input is present inside JWT header, it is not added to the request. For example: inject_headers: {"X-Mashery-JWT-Algorithm":"alg"}. In this case, "X-Mashery-JWT_Algorithm" header is not added in the request as "alg" claim is present in JWT token header.
Token Validation Rules and Checks
JWT Token Validation Flow Supported Claims- exp
- iat
- iss
- aud
- The "aud" (audience) claim identifies the recipients that the JWT is intended for.
- Each principal intended to process the JWT MUST identify itself with a value in the audience claim.
- If the principal processing the claim does not identify itself with a value in the "aud" claim when this claim is present, then the JWT MUST be rejected.
- In the general case, the "aud" value is an array of case-sensitive strings, each containing a StringOrURI value.
- In the special case when the JWT has one audience, the "aud" value MAY be a single case-sensitive string containing a StringOrURI value.
- The interpretation of audience values is generally application specific.
- Use of this claim is OPTIONAL.
- nbf
- The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing.
- The processing of the "nbf" claim requires that the current date/time MUST be after or equal to the not-before date/time listed in the "nbf" claim.
- Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew.
- Its value MUST be a number containing a NumericDate value.
- Use of this claim is OPTIONAL.
- nonstandard_claims (custom claims)
Token Structure Verification
- Connector verifies the third party JWT token structure. In case JWT structure is malformed, an error response with message is returned.
- Mashery decodes JWT token using standard base64 decode library to retrieve header and payload.
- In JWT token, JWT header standard fields (typ, cty, alg, jku, jwk, x5c, x5t, kid) is not allowed in the JWT token payload.
- In JWT token, JWT standard claims (sub, nbf, iat, iss, aud, exp, jti) is not allowed in the JWT token header.
- In case JSON Web Key/key id is unavailable or inaccessible from URL path specified in pre-inputs, then an error response with message is returned.
Token Signature Verification
- Connector validates the JWT signature using the algorithm and JSON Web Key information.
- It needs 'kty' claim in JSON Web Key to check algorithm key type.
- Connector retrieves 'alg' claim from JWT header to verify the signature.
- Connector verifies algorithm mentioned in JSON Web Key and JWT token header should match in case algorithm is specified in JSON Web Key.
- Algorithms supported are as follows. These are compliant to JSON Web Algorithms (JWA) RFC.
https://tools.ietf.org/html/RFC7518
'alg' param value Digital Signature or MAC Algorithm Expected 'kty' in JSON Web Key Expected Parameters in JSON Web Key for Signature Validation RS256 SHA256withRSA RSA Modulus Parameter - n Exponent Parameter - e
RS384 SHA384withRSA RSA Modulus Parameter - n Exponent Parameter - e
RS512 SHA512withRSA RSA Modulus Parameter - n Exponent Parameter - e
ES256 SHA256withECDSA EC Curve Parameter - crv : P-256 X-Coordinate of Elliptic Curve Point - x
Y-Coordinate of Elliptic Curve Point - y
ES384 SHA384withECDSA EC Curve Parameter - crv : P-384 X-Coordinate of Elliptic Curve Point - x
Y-Coordinate of Elliptic Curve Point - y
ES512 SHA512withECDSA EC Curve Parameter - crv : P-521 X-Coordinate of Elliptic Curve Point - x
Y-Coordinate of Elliptic Curve Point - y
PS256 SHA256withRSAandMGF1 NA NA PS384 SHA384withRSAandMGF1 NA NA PS512 SHA512withRSAandMGF1 NA NA
Token Claims Verification
- If the incoming JWT token header is having 'kid' claim, then Connector matches incoming 'kid' value with the JWK kid value. If both are matching, then claim verifications is done.
- JWT token expiry is checked as per the 'iat' (issued at) and 'exp' (expiry) claims coming in JWT token.
- Expiry time can also be (optionally) configurable under pre-inputs for overriding default JWT token expiry.
Error Handling and Messages
- All JWT errors is returned as "403" type errors.
- Error contains information depending on the point of error, for example:
- Connector checks the data integrity of the JWT token using defined validation rules & checks above.
- On successful validation Connector will route call to the customer backend resources, otherwise returns 403 not authorized error.
Business Rules and Assumptions
- nonstandard_claims in JWT token payload format should be in string value only:
"groups":"b83c8150-cbf9-4767-bb65-fee0809292f1"
- Audiences in JWT token payload format should be in array of strings or string format only:
"aud": [ "Google", "Facebook" ]
"aud":"Facebook"
- JWT token should be generated in the same time zone as the local system time zone; otherwise, there will be a time zone difference which will impact the expected behavior.