JSON Web Token (JWT)

Owned by Gerard van der Hoeven
Last updated: Jun 27, 2018 by Denise Hoppenbrouwer (Unlicensed)
3 min read

This part of the iSHARE Scheme is considered normative and is therefore compliant with RFC 2119.


A JSON Web Token (JWT) is used when non-repudiation between parties is required. A statement, of which the data is encoded in JSON, is digitally signed to protect the authenticity and integrity of the statement.


iSHARE uses signed JWTs in the following ways:

  1. In a request for an OAuth Access Token or an OpenID Connect ID token the client sends a signed JWT. The client is authenticated based on the verification of the JWT's signature.
  2. Delegation evidence is presented as a signed JWT. The signature of the Authorization Registry or Entitled Party provides proof to other parties.
  3. In a response from a server iSHARE metadata is presented as a signed JWT. The signature is used to bind the iSHARE metadata (such as license information) in the JWT to the content of the response.
  4. A service from an iSHARE Service Provider MAY require a request to be signed.


On this page the generic requirements for a signed iSHARE JWT are specified.

General

All iSHARE JWTs MUST be signed using the JWS specifications.

Header

For the header of an iSHARE signed JWT the following requirements apply:

  • Signed JWTs MUST use and specify the  RS256  algorithm in the alg header parameter 
  • Singed JWTs MUST contain an array of the complete certificate chain that should be used for validating the JWT's signature in the x5c header parameter
  • Certificates MUST be formatted as base64 encoded DER
  • The certificate of the client MUST be the first in the array, the root certificate MUST be the last
  • Except from the alg, typ and x5c parameter, the JWT header SHALL NOT contain other header parameters
Example JWT header
{
  "alg": "RS256",
  "typ": "JWT",
  "x5c": [ "MIIGCDCCA/CgAwIBAgICEAQwDQYJKoZIhvcNAQELBQAwgZAxCzAJBgNVBAYTAk5MMQswCQYDVQQIDAJOSDEPMA0GA1UECgwGaVNIQVJFMREwDwYDVQQLDAhTZWN1cml0eTEoMCYGA1UEAwwfaVNIQVJFIE5MIENlcnRpZmljYXRlIEF1dGhvcml0eTEmMCQGCSqGSIb3DQEJARYXaW5mb0Bpc2hhcmUtcHJvamVjdC5vcmcwHhcNMTcwNjI3MDgyOTIzWhcNMTgwNzA3MDgyOTIzWjCBnDELMAkGA1UEBhMCTkwxCzAJBgNVBAgMAk5IMRIwEAYDVQQHDAlBbXN0ZXJkYW0xDzANBgNVBAoMBmlTSEFSRTERMA8GA1UECwwIU2VjdXJpdHkxIDAeBgNVBAMMF2lTSEFSRSBTY2hlbWUgT3duZXIgUE9DMSYwJAYJKoZIhvcNAQkBFhdpbmZvQGlzaGFyZS1wcm9qZWN0Lm9yZzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALp1Yk0cu6U7M13mcQupWj+TADy/hwEHWmmGGFFRaLMURuujDsKCHeu89Lvq71QQWkxxJWAHP6oRe3UCzCdMjXh6PoEQnnyC3dUgX3pGjQG1oT0a7tyMdMWzAW92MJW2BF8P7ZRMlDskf7BJh1QPrF/p53+S0uexZNNSB3/ZZjLpantIL3iF9mxPKBJX2c5dY666rt3+fadLhGf0AtG950M6BV3GmMNbx8sNQV+hCQ0OeIirhkIi+08ovcHTE7DP7+3BB2edDoCgSXStLHrodB8wZBBGLBgm7tqcDz5pkaDetIrsYKNXQqERFjU2TYurBlnll64pce/SOUiy+KDxhjcCAwEAAaOCAVwwggFYMAkGA1UdEwQCMAAwEQYJYIZIAYb4QgEBBAQDAgZAMDMGCWCGSAGG+EIBDQQmFiRPcGVuU1NMIEdlbmVyYXRlZCBTZXJ2ZXIgQ2VydGlmaWNhdGUwHQYDVR0OBBYEFBEdKZ61hpM+ZDLNWLKlbxbBlIVoMIG+BgNVHSMEgbYwgbOAFI5GTdMUiapXImVUi9T21ZsCN9zroYGWpIGTMIGQMQswCQYDVQQGEwJOTDELMAkGA1UECAwCTkgxEjAQBgNVBAcMCUFtc3RlcmRhbTEPMA0GA1UECgwGaVNIQVJFMREwDwYDVQQLDAhTZWN1cml0eTEUMBIGA1UEAwwLaVNIQVJFIFJvb3QxJjAkBgkqhkiG9w0BCQEWF2luZm9AaXNoYXJlLXByb2plY3Qub3JnggIQADAOBgNVHQ8BAf8EBAMCBaAwEwYDVR0lBAwwCgYIKwYBBQUHAwEwDQYJKoZIhvcNAQELBQADggIBAANm0QHtsbfkVqxr6jJgtDvvIGQqmuryMpue1Log6HZZ2QowZWrG8o/4SAglpMPTuVU0UfABk5dVfOXnmBa5lRMI7hl9dSM1HNle6C9WA7RQtNV/v4qBe0OlgfaD4cUAJDkHsIwWSMlcelOoxVZNcdOwadXAQHgYduzBSdR8/Ps3plvIDIE9lrGt7GkUzxS3WU1XVss6nKZFWlZktqQH5Y+WEG//60+1Wf4aI6VHIuoRj10/NlEvjct0Zx0yiZU2RrqwPqsrtBYbCPIuO+Cl9QM73pHY3zYqkWY4CLaewvyPZaY5KDBh7nZOp9NJ1Z2XWFuVIDTZReH2ARXFpkWDaHmhAcMZ9BiqM+hx4IXeC68Vvwua+guypPJZfRyE33sox/lu8ecL2L7/ehDgji8IESymUPI32CpKfMN1KKNL/KEtftGPpuV+6iQNTE4hTCBcBaSf3dxsGHclOSC6Ke9tL4YRLiX3+YsHqYD98vLRRObIQZGWXiqvSFsLCwK0M1RIwsfb6B9S+XMRAiwr1iezBdHxXaH81lT+WxJfnDun6uxXUz4xTuzaVXsV0gvcY3quYp64LR6Rrhnc2DkNDzZU6JHyF7LX70rn8Lj180jjG1ge6ll9DLPQTkVyShTqCUV+9wrU2aE16rqe2YAq/lLJ0dWOHS2pJcQjh1iDpAqGObwT",
"MIIGBDCCA+ygAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwgZAxCzAJBgNVBAYTAk5MMQswCQYDVQQIDAJOSDESMBAGA1UEBwwJQW1zdGVyZGFtMQ8wDQYDVQQKDAZpU0hBUkUxETAPBgNVBAsMCFNlY3VyaXR5MRQwEgYDVQQDDAtpU0hBUkUgUm9vdDEmMCQGCSqGSIb3DQEJARYXaW5mb0Bpc2hhcmUtcHJvamVjdC5vcmcwHhcNMTcwNjI3MDYxNDM0WhcNMjcwNjI1MDYxNDM0WjCBkDELMAkGA1UEBhMCTkwxCzAJBgNVBAgMAk5IMQ8wDQYDVQQKDAZpU0hBUkUxETAPBgNVBAsMCFNlY3VyaXR5MSgwJgYDVQQDDB9pU0hBUkUgTkwgQ2VydGlmaWNhdGUgQXV0aG9yaXR5MSYwJAYJKoZIhvcNAQkBFhdpbmZvQGlzaGFyZS1wcm9qZWN0Lm9yZzCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAKiuQXA3R14zhAZ59xu4J6j8h5LaMYoMzFIRzeV+665E8bnoK2eQSC5aYMvsb80o8DxHHjiqPJiJW1n1oT86UAKgaEEnJ8/GhF+2kyOlybdpM21Q6bNwkJ5vL4SD/GYBPmWsVt7X6pLAkFsweXu6wRzvrYXWcVm/z/3SHX9AZFg6HDZRsGGDnnRw14nHYpb/oh7p5h6atI+X0aOD4HhQJ1ahQLVozIbbCFDfpKu9mrDXzKYDaNstrYn2DmbtV40BC5FW1OT0HLO/texnnhtNrjq6IVgUkZ54NHT8Y2EQNmajy8RilrLU1FHS/ka03w8sV0sXDsLeBwbxl3BYHpisPMWpMJDFU8b92tlYjk2lUDnHqDUi5BHRdRYqVZeWBSL+Qevpezr3mCL9ynhGPy+tNyDjyVjb/y7hlftAzZzodRwItQPzpKHCWQLsWX+JwM9lwu5uq6lcqxHGPSAB0o/ME80KE3a4KnjCGYvlZiPJtrad0HZDRR/hEAnen3HE3fTZE42u2wBLTfZB1D8Kxjc44vJv8L4JOaLlt/ooMT913sGCSJDPQUwv+/VvYDV8ngkgzRCpFng2NrPaWao6RKJ99bBMkKFQ4vsdtvwi42GK2OBK7ozXnNS7B5qcljdVnrmmH8fCPJ/s7L9BDYw/IKrd5wHaSH1kZ7/DRa0fa2mMJjfLAgMBAAGjZjBkMB0GA1UdDgQWBBSORk3TFImqVyJlVIvU9tWbAjfc6zAfBgNVHSMEGDAWgBRLYazzoNpuBb//4Sr1Ior0iP04RjASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBhjANBgkqhkiG9w0BAQsFAAOCAgEAQ7GRIQ3Q+TRUumxOXc+dGJnx98EK1qD8E1uEptlS+VROWAZ22QeLCPk/nNDVs2AmCADZF0JoX2+RJNjq7pX2+AxcL1owWQoi3GRtL6GABHByulTfJfvodYjUipI1zmIvcWKzNnNCC9A0rdtUJyRjZvGZt32K77aiRNGiSCtVyCBuFBPtqCkXIz86e/wzQ1fwBeCRB0WDMoSdXbSkt/tapyGoU7oAj2DVWbtKaCnkKiysE19r1RCiZI2WAHLcuU9iLvNM1Mfowv9avI+rVq2YlKUOuCIrD7s/ILRLXg55VwqMJT33/50NFnu3H8ebmqEhkGYStk7p3FGRxgptd2OJnqAt5nG1pspHQuD+vYBoKkkMw40qvy+eeYkhyzKcJTKeOsfI29fyQx/eFSmWRheT188+jZQyCqEQpZRgtku+2KPQbCBxVeCfHacyS16+9ZOVs1zXWGfIqXKXwZF1v6CDyL7bedJZEuTU1wUpkEUJH/IPmdp2ZMNMcss/BIdyf/+pYwyMnB6DJocDwMjlm3cUEsbtT393wIie0mohWiu8myTxkCfN1VJs4W9chSx5/DxVwDtFoT4nsqVK9F6DKYJAJ95UR+C+RiCS+x7t4r8cup0AiJpg7JEGr5I9kdlBXKAk78Pr/oqZogFymWPzoWUy48Ye6WxaAA1s+h6hVQ22MCg=",
"MIIGCDCCA/CgAwIBAgIJAN7kMSjuGT9KMA0GCSqGSIb3DQEBCwUAMIGQMQswCQYDVQQGEwJOTDELMAkGA1UECAwCTkgxEjAQBgNVBAcMCUFtc3RlcmRhbTEPMA0GA1UECgwGaVNIQVJFMREwDwYDVQQLDAhTZWN1cml0eTEUMBIGA1UEAwwLaVNIQVJFIFJvb3QxJjAkBgkqhkiG9w0BCQEWF2luZm9AaXNoYXJlLXByb2plY3Qub3JnMB4XDTE3MDYyNzA2MDY1NFoXDTM3MDYyMjA2MDY1NFowgZAxCzAJBgNVBAYTAk5MMQswCQYDVQQIDAJOSDESMBAGA1UEBwwJQW1zdGVyZGFtMQ8wDQYDVQQKDAZpU0hBUkUxETAPBgNVBAsMCFNlY3VyaXR5MRQwEgYDVQQDDAtpU0hBUkUgUm9vdDEmMCQGCSqGSIb3DQEJARYXaW5mb0Bpc2hhcmUtcHJvamVjdC5vcmcwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAwggIKAoICAQCuvV8gSQDx7g1PYvxcuK6uDIwWZNZKdF0wJoGjcIlqPJWF3pP2xCJq5ZRnUQnpW0WTCWw9A4uZfCIWqJSoISh4nE7UmMmfw45ms+7SwJxfc7E+Y4ffMDMyLcmvHYYLqGDoZu4qnpytsz+Xs1e8ESyNtIlXooZ6O+C1he+XmXpSChOjh5Pnz7RHz4cS7Zw38B9aNA3WktF+yR7ijkTUN887aZAplmrNZoioGnM/E1RFwnLqrk5E84kOTzexsNILBpBzoZkLPz8yYI0OJ42/RT5m9YPOIRWMwWcgQqmBHIgMCaUOjAslex2Bx1uQtBJcti+DIf+ZIGPm/TcwsaCC+RbE51SmMqwXYe/BoAlAZKYSgG8outN+Fd3Ew3h3YJcA86wDT9bKMzS9oSV1EjXc8v+40pp//AdWMPf2q15i/QotTj+SGP2cJQvcfRBJ94IfG41IBolEK7jEUN2JUcowAdNsYfM7EdoKGhIn+bkCXnZR3bnfBKBAXH64MOp7Ii1NukjPpEqemyM3//XKn/1lXzU43rbazwbxyGBYq3AHv5io7MS1TwegD/hNmTOEGHffZ/CzJghm6WvgmcmUALu2IFcDpmYZI3UI3SKzwaddi7/vcGer5VVDglRtVtvHk3eJRT0L9SFqHIWsLunI/dZSJE8pKpStG5Lzj7Y/psOlBpahnwIDAQABo2MwYTAdBgNVHQ4EFgQUS2Gs86DabgW//+Eq9SKK9Ij9OEYwHwYDVR0jBBgwFoAUS2Gs86DabgW//+Eq9SKK9Ij9OEYwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAYYwDQYJKoZIhvcNAQELBQADggIBABt+I4ZnS45c2IFsKV+BA8JP5OWCPoaJyl3PCELjedVfB4rXyF946+ILARcBZg35F07WzHtmi/afXh6entvVMEAlEmH6ln8sR9hoM3rHnYRtSIJmJs2gSF8wgCOZd1pyfrBVu3f3SXbUgNjoe5tEW6xsOQsjjqNnQiJMJx6ea56L2kbW7E6kOs+Mck9Kz8ZQQB58iPGyx3ahMLOrxbPoItbqKuyDwco7AzLf7ea9zye0up8ubNDYFaKJfiIDsnVbUPA6FbTn4fSQpeeOK1fjrzSaUpeMOdOomj0Zjwt6K7W7ckxoIfOecW4dcPENpXImkBPQXsGxvClDf/6e/jPti3CPgxJF3747Hq6tBSH0GzCrYv4bForQu43MzqZKHbX8FF1PpHSaiXJK/Hu8WJDXXBq5Pedel/lJSajdTsUDsiFXkj/pY0uJ6M0x/EonozaCPcHwdPsvr6nrrHWQXo4ayP7ntegJA3GrGXcaP+peEQmF9nWgVwPq33C1TrPNaiMxHz5toxl0YhnbA+5eH2CTBjDFJnr2uaeh8BzbkdE29WkOsqJZAIUEMmRwxcxBW20JGAlhF6MPFADjPYG0Ljdjbwq2H+LQtRf+tE6Z7nwM/cAT4dEB7Me1uJrYucVjLLSNXCRKQaDKKZMoHhAciLeKLMrSgUDaAi0AUKXduCymUw3n"
]
}

Payload

For the payload of an iSHARE signed JWT the following requirements apply:

  • The JWT payload MUST conform to the private_key_jwt method as specified in OpenID Connect 1.0 Chapter 9 1 2
  • The JWT MUST always contain the iat claim
  • The iss and sub claims MUST contain the valid iSHARE identifier of the client 1
  • The aud claim MUST contain only the valid iSHARE identifier of the server. (Including multiple audiences creates a risk of impersonation and is therefore not allowed)
  • The JWT MUST be set to expire in 30 seconds. The combination of iat and exp claims MUST reflect that. See Dates and times for requirements
  • Depending on the use of the JWT other JWT payload data MAY be defined

Additional rationale

1 In OAuth 2.0 clients are generally pre-registered. Since in iSHARE servers interact with clients that have been previously unknown this is not a workable requirement. Therefore iSHARE implements a generic client identification and authentication scheme, based on iSHARE whitelisted PKIs.

2 Since OAuth 2.0 doesn't specify a PKI based authentication scheme, but OpenID Connect 1.0 does, iSHARE chooses to use the scheme specified by OpenID Connect in all use cases. This is preferred above defining a new proprietary scheme.

Example JWT payload
{
  "iss": "EU.EORI.NL123456789",
  "sub": "EU.EORI.NL123456789",
  "aud": "NL.KVK.12345678",
  "jti": "378a47c4-2822-4ca5-a49a-7e5a1cc7ea59", // Note this is not necessary a GUID
  "exp": 1504683475, // Equals iat + 30 seconds
  "iat": 1504683445
}

Processing a JWT

  • A server SHALL NOT accept a JWT more than once for authentication of the Client. However within it's time to live a Service Provider MAY forward a JWT from a Service Consumer to one or more other servers (Entitled Party or Authorization Registry) to obtain additional evidence on behalf of the Service Consumer. These other servers SHALL accept the JWT for indirect authentication of the Service Consumer during the JWT's complete time to live
  • A server SHALL only accept a forwarded JWT if the aud claim of the forwarded JWT matches the iss claim of the JWT from the client that forwards the JWT
  • JWT contents that are not specified within the iSHARE scope SHOULD be ignored