Authentication Configuration

This page shows a brief overview of the authentication in Enterprise Server services:

Service	End-user authentication	Admin authentication	Service authentication
FES	Google OIDC	any IdP OIDC	-
WKD	-	any IdP OIDC	From EKM Push Sync to WKD
EKM	Google OIDC	any IdP OIDC	From EAP Orchestrator to EKM
EAP	-	any IdP OIDC	-

Configuration in a .properties file

Please follow the default .properties file format you have received in your build to understand the required authentication configuration type for each service.

End-user properties for FES and EKM

End-user properties are set up for Google OIDC which is the only option at the moment. You shouldn’t change them, otherwise, FlowCrypt client apps won’t be able to authenticate.

Property	Description
auth.enduser.type	For end users the OidcAuthenticator is the only authenticator option. Users will be asked to authenticate themselves in the client app, and the retrieved OpenID token will be used to authenticate the user with the FES or EKM service. Example: OidcAuthenticator
auth.enduser.idps	A comma-separated list of Identity Provider names for end-users. Should be left google for end-users. Example: google
auth.enduser.<idp>.issuer	The expected issuer of the authentication JWT token. Should be left unchanged for end-users. Example: https://accounts.google.com/
auth.enduser.<idp>.jwks optional	The JWKS (JSON Web Key Set) containing the public keys to validate the authentication JWTs against. When not provided, WKM will try to poll [issuer]/.well-known/openid-configuration to retrieve the JWKS URL during startup. Should be left as is provided in the default properties file. Example: https://www.googleapis.com/oauth2/v3/certs

Admin properties

Admins can use any IdP that supports OIDC. You’ll need to set up an OIDC app in your IdP regardless of which one you choose. To set up an admin IdP for EAP, depending on the chosen IdP, you will need to configure settings similar to the following:

Property for IdP App	Value
App Type	Open ID Connect, OIDC, Web Application, or oAuth2. Your choice depends on your IdP. Don’t choose SPA, you’ll need a client secret, that SPA doesn’t have.
Name	FlowCrypt Enterprise Admin Panel (customizable)
Rectangular icon	Download the icon
Square icon	Download the icon
Authorized JavaScript origins	(none)
Redirect/callback URL	<services.eap.url EAP property>/login. For example, https://eap.example.com/login if services.eap.url is set to https://eap.example.com in the EAP properties file.
Token Endpoint Authentication Method	POST
Login URL	(blank)
ID Token Expiration	Recommended 20-60 minutes (1200 to 3600 seconds).
JWT signing algorithm	RS256
Grant Types	Authorization Code & Refresh Token (Implicit should be unchecked)
Proof Key for Code Exchange (PKCE)	The value should be set as required if IdP allows it.

Once the app is configured with your Identity Provider, you may set the admin authentication properties as follows:

Property	Description
auth.admin.type	For administrators OidcAuthenticator is the only authenticator option. Admins will be asked to authenticate themselves on the EAP, and the retrieved OpenID token will be used to authenticate the admin when EAP is making requests to EKM and FES. Example: OidcAuthenticator
auth.admin.idps	A comma-separated list of Identity Provider names for admins. Possible names could be default, onelogin, auth0, okta, or any other simple string. Example:default
auth.admin.<idp>.issuer	Substitute <idp> for the IdP name. The expected issuer of the authentication JWT token. Example: https://accounts.google.com/
auth.admin.<idp>.audience	Substitute <idp> for the IdP name. The expected JWT token aud claim. This should match the client ID for the OIDC application. This can have multiple comma-separated values if you have registered multiple applications for the same provider. Example: audience
auth.admin.<idp>.jwks optional	Substitute <idp> for the IdP name. The JWKS (JSON Web Key Set) containing the public keys to validate the authentication JWTs against. When not provided, the service will try to poll [issuer]/.well-known/openid-configuration to retrieve the JWKS URL during startup. Example: https://www.googleapis.com/oauth2/v3/certs

The following OAuth properties are only needed on EAP:

Property for EAP only	Description
auth.admin.<idp>.oauth.client.secret	Substitute <idp> for the IdP name. The client secret for your application as provided by your IdP (see the Client Credentials section). Example: HqSiCE1588WGDyBo1yytk66J3cOyrF4TNjN0GKwK
auth.admin.<idp>.oauth.authorize.url optional	Substitute <idp> for the IdP name. The authorize endpoint as provided by your IdP. The default is obtained automatically using OIDC discovery. Example: https://yourapp.yourissuer.com/authorize
auth.admin.<idp>.oauth.token.url optional	Substitute <idp> for the IdP name. The token endpoint as provided by your IdP. The default is obtained automatically using OIDC discovery. Example: https://yourapp.yourissuer.com/token
auth.admin.<idp>.oauth.automatic.session.refresh optional	Automatically refreshes the session using an OAuth 2 refresh token. true for automatic refresh, false for session to expire on id token expiration. Default is false. Example: true

Please note that for EAP the OIDC application client ID must match the first auth.admin.<idp>.audience value.

Access control list

In the current implementation, SimpleAcl is the only ACL option. Depending on the size of your deployment and your needs, we can integrate with your existing ACL service for more fine-grained or dynamic access control.

Property for FES, EKM and WKD	Description
acl.type	SimpleAcl means each end-user may access their own data, and each admin may access all data. Example: SimpleAcl
acl.simple.admins	A comma-separated list of user email addresses that have admin privileges. Example: admin1@domain.test,admin2@domain.test

Service authentication

These are for communication between services when enabled: Push Sync of public keys from EKM to WKD, and EAP Orchestrator to EKM for automatic key lifecycle management. Please see the authentication section of the appropriate service for details, as well as your default properties file for each service.

• Email Key Manager
• FlowCrypt External Service

Supported mechanisms

Admin users can use any IdP that supports OIDC. Claims must be sent as part of the id_token as there is no further interaction (beyond verifying the JWT) to retrieve claims.

End users can only use Google IdP. We would consider adding support for non-Google IdP authentication of end-users for a larger deployment. Please let us know if you require this.

JWT requirements

Currently, we support only the RS256 JWT signing algorithm. Please let us know if you’d like us to support other algorithms.

JWT Claims

The following claims are required for both admin and end-user JWT tokens:

• aud (audience)
• exp (expiration)
• iat (issued at)
• iss (issuer)
• sub (subject)
• email

OIDC Scopes

The following scopes are requested from the Oidc provider for all JWT tokens:

• openid - returns the sub, iss, aud, exp, iat, at_hash claims.
• email - returns the email and email_verified claims.
• profile - returns the name, family_name, given_name, middle_name, nickname, picture, and updated_at claims.
• offline_access - returns a refresh token when swapping an authorization code for tokens. This scope will only be requested if the auth.admin.<idp>.oauth.automatic.session.refresh property is set to true.