mittwald-flow / jwt-auth
Authenticate users with JSON web tokens
Installs: 38
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 5
Forks: 1
Open Issues: 0
Type:typo3-flow-package
Requires
- firebase/php-jwt: ~3.0
- typo3/flow: *
This package is auto-updated.
Last update: 2024-03-12 21:39:33 UTC
README
Author and Copyright
Martin Helmich
Mittwald CM Service GmbH & Co. KG
This package is MIT-licensed.
Synopsis
This package implements an authentication provider for TYPO3 Flow that
authenticates users based on JSON Web Tokens. JWTs can be
supplied using a configurable custom HTTP header (X-JWT
per default), a
cookie or a query parameter.
Installation
You can install this package using Composer:
$ composer require mittwald-flow/jwt-auth
Basic considerations and design choices
-
This package does authentication only. It will not issue new tokens. This package's only purpose is to authenticate users by JSON Web Tokens that are issued by a trusted, third-party identity provider.
-
JWT authentication is stateless. This means that when using JWT authentication, Flow will not start any kind of session, but authenticate you each time anew based on the access token.
-
Accounts authenticated by this package are not persistent. This is done on purpose, since claims for a user might change when the same user authenticates with a different token.
Configuration
There are several settings that you need to configure in your TYPO3 Flow settings.
Verification key
This package needs a key to authenticate tokens. This can either be a random character string for tokens that use a symmetric authentication code (HMAC) or an RSA public key. To configure this key, you can use one of two settings:
-
Mw.JwtAuth.security.key
to directly specify the key:Mw: JwtAuth: security: key: | -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuurXQ9FbDxK9EQL9gw/f KJVdo/33j8zDOxemH6fV/KWp/fEMwez77GC3J5ze/A1o/ue4FVz/8fJ8PMGO3ag9 drIHyWgs4FYBpQZ1BqA78b6nWJeJ8Zbsv71r+Bpb5UUJBBHZ85Sa13sl3ZN0L0E0 XD/NYD1Sh31qoccZU57l6g4PWScxUZYGWc/OeT07HbUjaFzL/YpQZUKH+KoqoIOD UiZkf44ear4dGzNeR0UQ01VIZj7RaJ1uhAZVsNLoqPKGyjmgEZz70DDbMlxEXiMi Q/2Thd3bklr0IpZpL7JwHw9MrVS32NkustFgG6uYv/mvw10Zll9CCAUib3QIGlZV uQIDAQAB -----END PUBLIC KEY-----
-
Mw.JwtAuth.security.keyUrl
to specify afopen
-able URL from which the key can be retrieved:Mw: JwtAuth: security: keyUrl: https://identity.service.consul/key
When you specify both settings, the Mw.JwtAuth.security.key
setting will
take precedence.
Claim-to-account mapping
You can also configure how the claims encoded in the JWT should be mapped to the TYPO3 Flow user account. For instance, when the JWT claims contain a field that describes a user type, you can map this on a TYPO3 Flow role.
Consider a JWT claim like the following:
{ "sub": "my-username", "type": "customer" }
By default, the sub
claim will be used as account identifier for the Flow
user. You can change this by setting the Mw.JwtAuth.claimMapping.accountIdentifierField
option.
Furthermore, you can configure which claim contains the user role and how to map claim values to known user roles:
Mw: JwtAuth: claimMapping: roleField: type roles: customer: My.ExamplePackage:Customer employee: My.ExamplePackage:Employee
Token sources
You can also configure how the authentication provider should extract the
JWT from the HTTP request. A JWT can be contained within a cookie, a custom
request header or a query argument. You can configure the token sources
using the Mw.JwtAuth.security.tokenSources
:
Mw: JwtAuth: security: tokenSources: - from: header name: X-Your-Custom-Header - from: cookie name: MyCookieName
This setting can contain a list of multiple token sources. Each of those will be tried in sequence until one of them matches.