1"use strict";(self.webpackChunkmia_platform_docs=self.webpackChunkmia_platform_docs||[]).push([["11428"],{780407(e,n,i){i.r(n),i.d(n,{metadata:()=>s,default:()=>h,frontMatter:()=>r,contentTitle:()=>a,toc:()=>d,assets:()=>l});var s=JSON.parse('{"id":"runtime-components/plugins/jwt-token-validator/overview_and_usage","title":"JWT Token Validator","description":"The JWT Token Validator service allows verifying if a given JWT token is valid.","source":"@site/versioned_docs/version-15.2.0/runtime-components/plugins/jwt-token-validator/10_overview_and_usage.md","sourceDirName":"runtime-components/plugins/jwt-token-validator","slug":"/runtime-components/plugins/jwt-token-validator/overview_and_usage","permalink":"/docs/15.2.0/runtime-components/plugins/jwt-token-validator/overview_and_usage","draft":false,"unlisted":false,"tags":[],"version":"15.2.0","sidebarPosition":10,"frontMatter":{"id":"overview_and_usage","title":"JWT Token Validator","sidebar_label":"Overview and Usage"},"sidebar":"marketplace","previous":{"title":"CHANGELOG","permalink":"/docs/15.2.0/runtime-components/plugins/invoice-service/changelog"},"next":{"title":"CHANGELOG","permalink":"/docs/15.2.0/runtime-components/plugins/jwt-token-validator/changelog"}}'),t=i(474848),o=i(28453);let r={id:"overview_and_usage",title:"JWT Token Validator",sidebar_label:"Overview and Usage"},a,l={},d=[{value:"Usage",id:"usage",level:2},{value:"Configuration",id:"configuration",level:2}];function c(e){let n={code:"code",em:"em",h2:"h2",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"JWT Token Validator"})," service allows verifying if a given JWT token is valid."]}),"\n",(0,t.jsx)(n.h2,{id:"usage",children:"Usage"}),"\n",(0,t.jsxs)(n.p,{children:["The service exposes the ",(0,t.jsx)(n.code,{children:"GET-/verify"})," endpoint that validates a JWT token.\nThe JWT token is passed to the endpoint inside the header ",(0,t.jsx)(n.code,{children:"Authorization: Bearer <JWT token>"}),".\nAlternatively JWT token can be passed inside the ",(0,t.jsx)(n.code,{children:"sid"})," cookie."]}),"\n",(0,t.jsx)(n.p,{children:"The endpoint will return:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:"if the JWT is valid, its payload,"}),"\n",(0,t.jsx)(n.li,{children:"an error indicating that the JWT is malformed or is not valid, and why."}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,t.jsx)(n.p,{children:"The service needs to be configured using the Mia-Platform Console.\nThe environment variables needed are:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"JWKS_ENCRYPTION_KEYS_PATH"}),": path to the file containing all the information required to decrypt the JWE."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"ISSUER_CONFIGURATION_PATH"}),": the runtime mount path of the ",(0,t.jsx)(n.code,{children:"ConfigMap"})," containing the configuration file of the service (e.g. ",(0,t.jsx)(n.code,{children:"./configs"}),")."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"ISSUER_CONFIGURATION_FILENAME"}),": the file name of the configuration (e.g. ",(0,t.jsx)(n.code,{children:"./issuer-config"}),"). It must be a ",(0,t.jsx)(n.code,{children:"json"})," file.\nNote: remove the file format in the environment variable as the service will append ",(0,t.jsx)(n.code,{children:".json"})," at the end."]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["As described above, the service requires a ",(0,t.jsx)(n.code,{children:"ConfigMap"})," configuration.\nThe configuration is a ",(0,t.jsx)(n.code,{children:"json"})," object with a ",(0,t.jsx)(n.strong,{children:"jwtConfig"})," field which is an array of objects.\nEach object has the following fields:"]}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"JWKSSignatureEndpoint"}),": the endpoint supplied by the issuer that contains the public keys information in JWKS format. They are needed to validate the signature of the JWT token."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"requiredClaims"}),": list of required claims (e.g. ",(0,t.jsx)(n.code,{children:"aud,iss"}),"). It could be an empty string.\nIf a claim is not required, its validation will return true if the value is valid or is unset.\nThese are the claims validated by the service: ",(0,t.jsx)(n.code,{children:"exp"}),", ",(0,t.jsx)(n.code,{children:"iat"}),", ",(0,t.jsx)(n.code,{children:"nbf"}),", ",(0,t.jsx)(n.code,{children:"aud"}),", ",(0,t.jsx)(n.code,{children:"iss"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"issuer"}),": the issuer of the JWT"]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"audience"}
1),": a string or an array of strings that lists all the audiences. In case the JWT token inside its ",(0,t.jsx)(n.code,{children:"aud"})," claim has different values from the ones defined in this field, it won't be valid.\nThe ",(0,t.jsx)(n.code,{children:"aud"})," claim identifies the recipients that the JWT is intended for. This means that the service tells that it's identifying itself with the defined value."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.strong,{children:"customGroups"}),": array of strings that allow to set one or more custom groups to a issuer. The values are added to the response of the ",(0,t.jsx)(n.code,{children:"/verify"})," when the issuer is in the JWT claims. In case the claim ",(0,t.jsx)(n.code,{children:"groups"})," is already present in the JWT payload, a union of the values is returned."]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["Given the example below, the service is identifying itself with a ",(0,t.jsx)(n.em,{children:"dih"})," value for a JWT coming from the issuer ",(0,t.jsx)(n.em,{children:"issuer-one"}),". Supposing that the JWT has an ",(0,t.jsx)(n.code,{children:"aud"})," value that does not appear in the audience list, the JWT will be rejected as it is not meant for the service."]}),"\n",(0,t.jsx)(n.p,{children:"Following is an example of the configuration:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-json",children:'{\n "jwtConfig": [\n {\n "JWKSSignatureEndpoint": "https://endpoint-issuer/.well-known/jwks.json",\n "requiredClaims": "aud,iss",\n "issuer": "issuer-one",\n "audience": "dih",\n "customGroups": []\n },\n {\n "JWKSSignatureEndpoint": "https://endpoint-issuer-two/.well-known/jwks.json",\n "requiredClaims": "",\n "issuer": "issuer-two",\n "audience": [\n "dih",\n "another_audience"\n ],\n "customGroups": [\n "groupA",\n "groupB"\n ]\n }\n ]\n}\n'})}),"\n",(0,t.jsx)(n.p,{children:"With this configuration, you can support as many issuers as you need for JWT tokens.\nAt the moment, it's only possible to support JWE supplied by a single issuer."})]})}function h(e={}){let{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(c,{...e})}):c(e)}},28453(e,n,i){i.d(n,{R:()=>r,x:()=>a});var s=i(296540);let t={},o=s.createContext(t);function r(e){let n=s.useContext(o);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:r(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.