security:
tokenExpirationTime: 3600
keystorePassword: "secret"
keystorePath: "keystore.jceks"
algorithm: "HS256"Table of Contents
Overview
Gentics Mesh provides multiple ways of authentication:
-
Authentication via login
-
Authentication via API token
-
Authentication via OAuth2
-
No authentication - Access via anonymous user
| Currently, all data including media assets such as images, videos, and documents are secured and need authentication to be retrieved. |
| Sending user credentials as base64 encoded string, or as plaintext is highly insecure to be used on an open network. This method MUST not be used in scenarios other than debugging and development when the connection between server and client is trusted. |
Authentication Configuration
Gentics Mesh uses JWT (JSON Web Token) to handle authentication. It is thus required to create a cryptograph key to sign and verify the generated JWT’s.
Typically, if no keystore file has been provided, Gentics Mesh will create one on the basis of the configuration details in mesh.ymlkeystorePassword
Alternatively, you can use the Java keytool to create a new keystore. Here is an example on how to create a keystore which contains a HMacSHA256 key:
keytool -genseckey -keystore keystore.jceks -storetype jceks -storepass secret -keyalg HMacSHA256 -keysize 2048 -alias HS256 -keypass secretAfter creating the keystore, you need to set the keystore password, the path to the keystore file, and the used algorithm in the mesh.yml
JWT
In order to be able to store and retrieve content, a Gentics Mesh user needs to authenticate (username:password).
Each way will store a JWT in a cookie which is used to authenticate the user for succeeding requests.
The token only lasts a certain amount of time (which can be configured in the mesh.ymltokenExpirationTime
Login
A user can be logged in via a basic authentication request to GET /api/v2/auth/login.
Basic Authentication Header
In basic authentication, when a client requests a URL that requires authentication, the server requests the client to authenticate itself by sending a 401-Not Authorized code. The client, in return, answers with login credentials sent in the authorization
authorization: Basic {base64_encode(username:password)}In Gentics Mesh, a user can be authenticated by invoking a regular GET/api/v2/auth/login
Example:
curl -v -X GET http://localhost:8080/api/v2/auth/login -H 'authorization: Basic YWRtaW46YWRtaW4='The response will be a valid JWT as well as set a cookie with the token.
{
"token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczMDYzLCJleHAiOjE0OTE3NzY2NjN9.8iG3I0Pe1M7J43pwbsBXiBOd6p0sn9dRxO3NfazVbOk="
}POST JSON Data
Alternatively, the user can POST/api/v2/auth/login
-
username -
password
If authentication has been successful, the server will respond with a JSON object containing a single property:
-
token
Additionally, the token will also be provided in a cookie.
Example:
curl -v -X POST \
http://localhost:8080/api/v2/auth/login \
-H 'content-type: application/json' \
-d '{
"username" : "admin",
"password" : "admin"
}'* Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> POST /api/v2/auth/login HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.50.3
> Accept: */*
> content-type: application/json
> Content-Length: 50
>
* upload completely sent off: 50 out of 50 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
< Cache-Control: no-cache
< Content-Length: 208
< Set-Cookie: mesh.token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczODU0LCJleHAiOjE0OTE3Nzc0NTR9._qt3Eufi7-3jnvgQ8lfe_KwJbd5ePwx5jOFrCK9w76A=; Max-Age=3600; Expires=Sun, 9 Apr 2017 22:37:34 GMT; Path=/
<
{
"token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzczODU0LCJleHAiOjE0OTE3Nzc0NTR9._qt3Eufi7-3jnvgQ8lfe_KwJbd5ePwx5jOFrCK9w76A="
* Curl_http_done: called premature == 0
* Connection #0 to host localhost left intact
}Both login methods will yield a JSON web token.
For further requests, the JWT can be provided in two ways. By default it is passed along with a cookie value. E.g., this is useful for embedding binary image nodes directly in HTML, since the browser will automatically handle authentication on the basis of the cookie.
Alternatively, the token can be passed along within the AuthorizationBearer <Token><Token>
curl -X GET \
http://localhost:8080/api/v2/demo/nodes \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzY1NDEzLCJleHAiOjE0OTE3NjkwMTN9.UY8OgjiK5qyZobAWt6X1Vd1Z-zg68BeJgGZKbW4Ucj0=' \API Token
An API token will never expire. This is different from regular tokens which will be issued when calling /api/v2/auth/login.
| Leaking an API token is potentially dangerous and thus the API token should only be used in combination with a secure connection. |
Typical use cases for API tokens are backend implementations which constantly communicate with Gentics Mesh using a secure or local connection.
The token can be issued per user with POST /api/v2/users/:userUuid/token
| Creating a new API token will automatically invalidate a previously issued token. |
Since the token is just a regular JWT you just need to add it to your request Authorization header field.
curl -X GET \
http://localhost:8080/api/v2/demo/nodes \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyVXVpZCI6IjNjYjY2YzU0MmFlMzRiMDFiNjZjNTQyYWUzY2IwMWRiIiwiaWF0IjoxNDkxNzY1NDEzLCJleHAiOjE0OTE3NjkwMTN9.UY8OgjiK5qyZobAWt6X1Vd1Z-zg68BeJgGZKbW4Ucj0=' \It is possible to manually revoke a previously issued token via DELETE /api/v2/users/:userUuid/token
Anonymous Access
Gentics Mesh first and foremost keeps your content safe - all data including media assets such as images, videos, and documents are secured and need authentication to be retrieved. However, sometimes it may be desirable to serve public content with Gentics Mesh.
That is why Gentics Mesh instances ship with an included anonymousanonymous
Try our Gentics Mesh demo instance without authenticating yourself: |
You can assign readPublishedanonymous
| Assigning further permissions would of course allow for other operations to be granted. |
Anonymous access can be configured in the mesh.yml
security:
enableAnonymousAccess: true
Recreating a previously deleted |
Forcing user to change password
Since Gentics Mesh 0.31.5 it is possible to force a user to change their password on their next login.
This is useful in situations when you want to create a user for someone else but want the user to set their password for themselves.
To do so, create or update a user and make sure to set the forcedPasswordChange flag to true.
Now, when the user tries to login in regularly they will receive an error message with status code 400 telling them to provide a new password in the login request.
The user has to additionally set the newPassword property when sending the login request. Then the password is changed and the user is logged in.
OAuth2 / OIDC
Gentics Mesh supports OAuth2 / OIDC. Authorized users can pass their JWT to the API. Gentics Mesh will act as a resource server and process the provided access token. The token will be validated and the user request processed.
| Gentics Mesh will just utilize provided access tokens. The needed OAuth2 sign-in and token refresh handling must be done by the client. |
The provided OAuth2 user information will automatically be kept in-sync with the user that is present in Gentics Mesh. The synchronization process will also take care of creating new users and even roles and groups.
Limitations
| The Gentics Mesh UI is currently not Keycloak aware. The UI will thus not redirect you to the Keycloak login page. This functionality will be part of a future release of the Gentics Mesh UI. |
Configuration
The list of public keys which will be used to validate and accept JWT’s can be added to the config/public-keys.json file. The path to this file can be configured via the security.publicKeysPath setting in the mesh.yml file or via the MESH_AUTH_PUBLIC_KEYS_PATH environment variable.
public-keys.json
{
"keys": [
{
"alg": "RS256",
"kty": "RSA",
"use": "sig",
"x5c": [
"MIIC/TCCAeWgAwIBAgIJA3kWNismjx1FMA0GCSqGSIb3DQEBCwUAMBwxGjAYBgNVBAMTEWpvdHNjaGkuYXV0aDAuY29tMB4XDTE5MDgyMDE4MTA0OVoXDTMzMDQyODE4MTA0OVowHDEaMBgGA1UEAxMRam90c2NoaS5hdXRoMC5jb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDKs/QbFvLs43ZRT4LzbrMVWgHfmJ/gOtkVZxCdznHXFa9b8B4JNKLHvAZiK9L5JXA2D0jDYDHTbEYQiisZb52zpqWFRaHD8vt9fxDbqIFZDljseEJT9/FXlKFBjl2XwVLqnmBBhRo5k0iu5PPSYY6zfzSmg5IY4Tw9FA81zO3ZeJPxazyIsFhldcCauCiK87N+ifocjL139NwJCtrWBoExnAVsMD4wrp++N36iplsZTSlzBd9Fqo4OZtHThJk2CHMv506l/dlHfl1KSK+8By97DXBmPk4DWSCqEThfDD+So3DFBhn/B5pofN3zL0YaCiD6oBB+Y+wFc3nInv+cjTFnAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFCZuptNeNaVwG8cEYHv2ApQyqFEeMA4GA1UdDwEB/wQEAwIChDANBgkqhkiG9w0BAQsFAAOCAQEAPoh8yvw8nPKzhFWR2JnEmuLU8vK1azn822dIY4ZulHpoS8ATQod8Z+jB8ejszezOr3/JeMYRsvrwisQgbXJQTahwg6Xudx4NDJvEFZowOJ4nvRLRp0ZZGVFeKZFI/dxdcNntk+nCkcLCiO78Wq2mdjSnMp83ueO2X/YtRczjNsbUXGyeUoXkZMRydaqkAJDuSrGDLr12iOKw4hk/162AiUs4n6v2Wbfdh7PtE+PPutHWBSvKCMkSCh8exQ9h0MllgsBj6YzdOnhicv0g5BjM3qlp+1PlwNQmunVy5qcPu1ZNqbmrMnf7d6KjKw1iW0v3TnHaC09if4qFnj82J46m/g=="
],
"n": "yrP0Gxby7ON2UU-C826zFVoB35if4DrZFWcQnc5x1xWvW_AeCTSix7wGYivS-SVwNg9Iw2Ax02xGEIorGW-ds6alhUWhw_L7fX8Q26iBWQ5Y7HhCU_fxV5ShQY5dl8FS6p5gQYUaOZNIruTz0mGOs380poOSGOE8PRQPNczt2XiT8Ws8iLBYZXXAmrgoivOzfon6HIy9d_TcCQra1gaBMZwFbDA-MK6fvjd-oqZbGU0pcwXfRaqODmbR04SZNghzL-dOpf3ZR35dSkivvAcvew1wZj5OA1kgqhE4Xww_kqNwxQYZ_weaaHzd8y9GGgog-qAQfmPsBXN5yJ7_nI0xZw",
"e": "AQAB",
"kid": "MDFCQ0E3RDM4QzIyNkIwNTNEQUQ4QzcxMDQ4NjM5NkFCOUMxNzY3Nw",
"x5t": "MDFCQ0E3RDM4QzIyNkIwNTNEQUQ4QzcxMDQ4NjM5NkFCOUMxNzY3Nw"
}
]
}Mapping
The access token properties will be used to synchronize the user data with Gentics Mesh.
| By default the authenticated user will automatically be created within Gentics Mesh. |
Currently the following fields will be kept in sync with Gentics Mesh:
| Token Field | Gentics Mesh |
|---|---|
User email |
|
given_name |
User firstname |
family_name |
User lastname |
preferred_username |
User username |
The preferred_username field is the main id property which will be used to locate a user.
| If the username changes a new user will be created in Gentics Mesh. |
Authentication plugins can override this field via the extractUsername() methods.
|
Authentication Service Plugin API
By default groups and roles will not be handled by the synchronization process. It is however possible to provide a custom authentication plugin which can extract role and group information from the access token information. This way groups and roles can be directly created.
It is also possible to write or use plugins which provide JWK’s to Gentics Mesh.
The AuthServicePlugin API provides methods which can be used to supply JWKs to Gentics Mesh.
You can read more on this topic in the Authentication Service Plugin API section.
OAuth2 Providers
Keycloak
The public keys can be loaded from keycloak via the certs endpoint:
https://localhost:8443/auth/realms/realmName/protocol/openid-connect/certsAuth0
-
Applications → Settings → Show Advanced Settings → Endpoints → JSON Web Key Set
https://yourName.auth0.com/.well-known/jwks.jsonOkta
The keys can be downloaded via:
https://yourName.okta.com/oauth2/v1/keysOther
For other providers it is required to find the matching JWK and add it to the list of accepted public keys. Public keys which are provided in PEM format can be converted to the JWK format using third party tools.
