Skip to content
This repository was archived by the owner on Mar 19, 2025. It is now read-only.

Authentication

Jump to bottom
Martin Paljak edited this page Nov 21, 2016 · 44 revisions

OpenID X509 ID Token (JWT)

(for discussion, please use https://github.com/open-eid/hwcrypto.js/issues/27)

Abstract

Most eID smart cards in European Union and elsewhere make use of a PKI with X509 certificates. User authentication with these cards is traditionally implemented via browser-facilitated TLS Client Certificate Authentication. This functionality it not always available, feasible or convenient for the user.

An alternative client authentication scheme is proposed for X509 certificates, building upon the well established OpenID Connect specification for the token format and the emerging WebExtensions specification with Native Messaging to implement support in browsers. Alternatively, local applications can be used as authentication agents generating the tokens and communicated with via localhost services or URL handlers (on mobile devices).

This specification defines the X509 ID token JWT profile, to be used by compatible User-Agents or local IdP-s.

Background

For various reasons (poor UX, resistance from browser vendors, lack of support on mobile platforms, server configuration requirements etc) using TLS CCA (Client Certificate Authentication) for end-user authentication with eID smart cards is not feasible in the long run, even if this type of session establishment has desirable security properties (like implicit MITM protection via mutual authentication).

Current alternative efforts that have potential horizontal reach, seem to focus around IdP-s (3rd party on-line service providers, OAuth etc), XML based schemes (SAML2, ISO 24727 etc), low level "PKCS#11 style API-s" or require an all-in commitment to a very different scheme like FIDO. Initiatives like WebCryptoAPI have failed to deliver, no support for existing infrastructure (hardware tokens with pre-distributed, cross-origin keys) is planned.

Having simple, web-scale implementations means omitting overly complex architectures and XML in favour of JSON and one of the requirements for a fail-safe solution is to be able to function in a "peer to peer" fashion, without a dependence on an on-line third party.

Much like the situation with online signature schemes is a messy, fragmented zoo (retired Java applets, ActiveX components, NPAPI plugins, native messaging extensions, localhost services etc, all with different interfaces on different platforms) there do exist implementations right now that implement some sort of authentication capabilities, but there is no visible standardisation effort.

Thus it seems sensible to define an authentication scheme that relies on client-side capability of providing JWT ID tokens with authentication information to websites, and to define requirements for client and server side implementations.

This does make the server-side a bit more complex, but also more transparent, as the authentication step is also more explicit than with TLS, which is often implemented implicitly in an off-loading appliance and not in the application itself.

The outcome of this effort will be a JavaScript library/API for website developers to call, to get browser extension generated JWT ID tokens, signed by PKI eID smart cards with X509 certificates. Similar tokens could be issued by a locally running self-hosted OpenID Connect provider

Sample usage session

  • User navigates to a secure origin, https://foobar.example.com/site/
  • Application generates a page that includes an unique session identifier
  • User clicks "Log me in" button
  • JavaScript on the websites communicates with the browser extension, to initiate the authentication for the session identifier
  • Browser extension utilizes Native Messaging (or alternatively, localhost service or mobile app), native companion application shows the user a list of possible X509 certificates (if there are many to choose from)
  • User has the ability to cancel the authentication request or to chosen certificate and remember the choice
  • Any local authentication procedures are made (PIN entry etc)
  • Native companion application returns the signed X509 JWT ID Token to the browser extension, which binds the request (nonce) and origin (extension-verified "aud" field)
  • Browser extension calls back to the website context, where the token gets posted back (resolving the Promise) to the application
  • Application verifies the X509 JWT token and sets the authenticated state and identity of the session

Calling on https://foobar.example.com/site/ 

hwcrypto.authenticate('NONCEVALUE'); // returns a Promise
                                     // that resolves to an ID token
  • The nonce MUST be generated by the backend application and MUST contain at least 256 bits of entropy
  • The consuming backend application MUST check that the nonce in the returned claim equals the nonce of the authentication request.
  • Browser implementation MUST reject nonces shorter than 256 bits
  • Browser implementation MUST reject origins that are not secure
  • The session ID used for the nonce SHOULD be cryptographically bound to the client session (e.g. utilising the SSL Session ID in addition to a signed session cookie)

Sample token

  • Token format is based on OpenID Connect ID Token with refinements in header fields and allowed semantics of the token fields. All fields required by ID Token are present for compatibility, but the interpretation of the fields differs.
  • The main value of the token is the combination of x5c + aud + nonce + signature; iat, exp, iss and sub provide additional filtering capabilities and are only present for compatibility with OpenID ID Token
  • For debugging: http://kjur.github.io/jsjws/sample_verify2.html

Header:

{
 "typ": "JWT",
 "alg": "RS256",
 "x5c": {"MIIFozCCA4ugAwIBAgIQHFpdK-zCQsFW4scOqWZOaDANBgkqhkiG9w0BAQsFADBjMQswCQYDVQQGEwJFRTEiMCAGA1UECgwZQVMgU2VydGlmaXRzZWVyaW1pc2tlc2t1czEXMBUGA1UEYQwOTlRSRUUtMTA3NDcwMTMxFzAVBgNVBAMMDkVTVEVJRC1TSyAyMDE1MB4XDTE2MDMxMTEzMjQzMFoXDTE3MTEyMzIxNTk1OVowgZMxCzAJBgNVBAYTAkVFMQ8wDQYDVQQKDAZFU1RFSUQxFzAVBgNVBAsMDmF1dGhlbnRpY2F0aW9uMSIwIAYDVQQDDBlQQUxKQUssTUFSVElOLDM4MjA3MTYyNzIyMQ8wDQYDVQQEDAZQQUxKQUsxDzANBgNVBCoMBk1BUlRJTjEUMBIGA1UEBRMLMzgyMDcxNjI3MjIwggEjMA0GCSqGSIb3DQEBAQUAA4IBEAAwggELAoIBAQCsCGcTOvHb44kbOoIJjbmmtdIL1qLPTxeBHWpCjHKXNVyW7xu84dRKFeAgue4-auN7qJorAy7hELtZ1AHOdAWKCLCL_xFjKJg_TqLkLw_CvxdiAfalXr-wkn5UFfT6tcHSo_Xf6337DPHSgq0n1YSU2m522BXUr87D4Hl0o2UJKfojBVKARNtkAUjfA78NYBrJ_v1z3Y4k3eLJmTpxNaGoWDeOUHemJ-0Dqi_-QtzDye1h0K43KKvU03YqVx6uKCtujPQnyQ6ctduS7Ia2qp6nXxAtHbpS3JpuRnxsoJmdANNofmTxknpaHwNp5ccbzHvjm95eI6a8rvEMlKhnAjeBAgQmoAaro4IBHzCCARswCQYDVR0TBAIwADAOBgNVHQ8BAf8EBAMCBLAwOwYDVR0gBDQwMjAwBgkrBgEEAc4fAQEwIzAhBggrBgEFBQcCARYVaHR0cHM6Ly93d3cuc2suZWUvY3BzMCEGA1UdEQQaMBiBFm1hcnRpbi5wYWxqYWtAZWVzdGkuZWUwHQYDVR0OBBYEFL-lc3l1ixB1ZyPeANAvMc7NHXMZMCAGA1UdJQEB_wQWMBQGCCsGAQUFBwMCBggrBgEFBQcDBDAfBgNVHSMEGDAWgBSzq4i8mdVipIUqCM20HXI7g3JHUTA8BgNVHR8ENTAzMDGgL6AthitodHRwOi8vd3d3LnNrLmVlL2NybHMvZXN0ZWlkL2VzdGVpZDIwMTUuY3JsMA0GCSqGSIb3DQEBCwUAA4ICAQBvZ1pGY0v7gMAnFeEirkqG0_En6xUkVI2ctyqLR2OY49qt-X8gNlrfwYtVTKRRMN4FZYJz8C3HsdTyE9iYFKJ1Nzhg_XM1-SBR2FLAivXF2IEDSRt_590VHLb2xEUFJaCGZmubYLFEH4L30-xwTYvziDv4ncfp0kyAKOmW41l8e8SZ3c37ilCPwDy5EL4fRqmL1JiqhtpuzWxcU_sekN-Jv6ei0_9gJL0bBHI3Dpr_S8rzupEYKfKcGztVasLBIkUXrZ2dhIk8NloNgqtCEht4hhINek7i5DY-oRviV7jQEKcGBAxfBFHetcsTw_9_d4TPFEAzGL-FYD-MIJCgRWgss-yEP-S7aAHQ78oyqrdMt94RP1gyA8dGBaOCEAqUNcuoL9h5RmcYKsybOPBXg_19q2AH_sPiDpmWTKg-CPUVRp0pa8iiygPJVbIJa0HxZfn-6l0QoagO8K0iuvitY2RHFldgR2wTvTzM5QCbcCQJwqh5uGywpGDqaKkelyJ_6HLjVrQ_Qjm3odzA8cDxJXHTe2kHOz3wb5A6E6PwqKyELovM9qjoeTmBlwo43CpQF6nB60bU8EuLLSXr7VRFJNvoRO9yFT664LrtMWpf8E7pFWVdj7vvOwcwLbRGkTuyZnyCpIZCErjyJujxmuM5GiDDX0UjEgH9abDTul5ZucVkig"}
}
  • Remark about "alg": algorithm depends on the capabilities of the card (e.g. MAY be ES256 or any other algorithm mentioned in JWA section 3.1). A list of REQUIRED algorithms will be specified.
  • Remark about "x5c": while OpenID Connect Core tells that "ID Tokens SHOULD NOT use the JWS x5c Header Parameter field", the possibility and need to relay the used certificate in the same message justifies ignoring the suggestion.

Payload:

{
 "exp": "1479621923",
 "iat": "1479621900",
 "aud": "https://foobar.example.com/",
 "iss": "https://self-issued.me",
 "sub": "EE:38207162722",
 "nonce": "NONCEVALUE",
}
  • Remark about "iss": TBS, https://self-issued.me for OpenID compatibility?
  • Remark about "exp": recommended value is 5 minutes. Care must be taken with TZ and clock skew of client machines
  • Remark about "iat": the time of the claim MUST NOT be trusted.
  • Remark about "sub": TBS, the value is informative and MUST NOT be used for authentication purposes, actual vetted identity is signed by certificate issuer and MUST be extracted from the certificate. SHOULD BE base64url(sha256(der(x5c)))
  • Remark about "aud": the origin of the website that initiated the authentication request. MUST be validated by consumer. MUST be the full origin with path, UI SHOULD display the full path but MAY only use the origin part (domain)

User-Agent requirements

  • Implementations SHOULD follow CCA UX:
    • asking for permission before sending authentication
    • keeping a mapping of "remembered sites"

TODO

  • RFC 2629 for the token description, to be submitted to OIDF as Implementer's Draft
  • postMessage interface description for WebExtensions

Reading materials:

Clone this wiki locally