Enable authentication

Flow does not provide a user interface for managing users or roles. Instead, it relies on the Management Center (MC) for identity management, utilizing MC security providers as identity providers. When a user attempts to access Flow, they will be redirected to the identity provider’s login page as configured with the MC.

Single Sign-On (SSO) and Single Logout (SLO) are pre-configured between Flow and MC, ensuring a seamless login and logout experience. This means that when a user logs in or out of one product, they are automatically logged in or out of the other.

Identity provider configuration through Management Center

Users must configure their identity providers through MC. This can be done using either the MC user interface or the Management Center Configuration Tool.

There are 2 ways to use MC as an identity provider:

  1. MC can act as the identity provider itself for the following security providers:

  2. MC can be configured to use an external identity provider for the following security providers:

Steps to run Flow with Management Center as the identity provider:

  1. Run one of the Docker Compose files given below to spin up Flow and MC. The security provider can be configured in 2 ways:

    1. Through the Management Center Configuration Tool. An example can be found below.

    2. Through the user interface of MC. To do this, open the landing page of Flow or MC. An example can be found below.

  2. After the security provider is configured through MC, go to the landing page of Flow or MC.

  3. Enter your credentials and login. Thanks to SSO, you are logged into both applications.

Below you can find example Docker Compose files where MC is the identity provider and a more complex scenario where MC is configured to use an external identity provider.

MC is preconfigured as the identity provider for Flow with the configuration prefixed flow.security and FLOW_SECURITY in the Docker Compose files below. Please update specified properties only when necessary; changing others may lead to unexpected results.

Potential modification of security pre-configuration

The following properties can be changed or not; please consider your use case carefully.

  1. --flow.security.openIdp.issuerUrl: The openIdp issuer endpoint. This should be set to the MC’s address. The browser will redirect to this endpoint, so ensure the DNS entry is accessible via browser traffic. localhost is possibly OK here. Example: Unless overridden, MC runs on http://localhost:8080. This property can be set to http://localhost:8080.

  2. --flow.security.openIdp.jwks-uri: A URL to load the set of JWKs used to verify signatures of presented tokens. This URL is called by Flow’s server, so ensure that the DNS entry is accessible to Flow. localhost is unlikely to work here. Example: Assume that MC is configured to run in a Docker Compose file with management-center service name. This property can be set to http://management-center:8080/oauth2/jwks.

  3. --flow.security.openIdp.executorRoleTokenUrl: The openIdp access token endpoint. This URL is called by Flow’s server, so ensure that the DNS entry is accessible to Flow. localhost is unlikely to work here. Example: Assume that MC is configured to run in a Docker Compose file with management-center service name. This property can be set to http://management-center:8080/oauth2/token.

  4. --flow.security.openIdp.executorRoleScopes: Scopes that need to be passed to access token request. openid email profile should always be set. Flow-specific roles can be modified. For example, for the Executor user to have the PlatformManager and Viewer roles, this should be set to openid email profile flow:PlatformManager flow:Viewer. See Flow roles.

  5. --flow.security.openIdp.executorRoleClientSecret: The Client Secret to authenticate with. This value must be the same as the MC_APPLICATION_CLIENT_SECRET environment variable in the MC’s environment.

  6. --flow.security.openIdp.require-https: Indicates if auth must be performed over https. Set this to true if MC and Flow runs on https servers.

  7. hazelcast.mc.flow.addresses: Value of public Flow node addresses. This value can only be used if the Flow node addresses are directly accessible from the current environment. For example, if a Flow address can be reached via http://localhost:9021 and needs to be accessed from the browser. If this property is not set correctly, users may see CORS issues.

  8. hazelcast.mc.flow.internalAddress: Value of internal Flow service address. This value can only be used if the Flow node’s service address is directly accessible from the MC environment. For example, if Flow is running in a container called hazelcast-flow, which can be accessed via http://hazelcast-flow:9021 and needs to be accessed from MC running in another container. This value should be set to the service address of a single Flow node or an address that can receive the updated license from MC and forward it to a single Flow node (for example, a load balancer). If this property is not set correctly, Flow will not be able to receive license updates from MC. See License management for Flow.

Example: Local security pre-configuration with via hz-mc tool

Run this Docker Compose file with usernames admin, user, user, readonly or metricsonly and password changeMe!135.

Notice usage of ./bin/mc-conf.sh in the Docker Compose file.

Once the containers have started, go to the landing page of MC or Flow, and you will see the following login screen:

mc local security provider login

Example: External identity provider configuration through user interface

Run this Docker Compose file.

Once the containers have started, configure your external identity provider with OIDC or SAML, go to the landing page of MC or Flow, and you will see the following login screen:

external idp oidc login

Example: Identity provider configuration for multiple Flow nodes

Run this Docker Compose file.

Notices:

  • Flow service has 3 replicas and runs on port 9021, 9022, 9023.

  • hazelcast.mc.flow.addresses system property is configured with public addresses of Flow nodes.

  • hazelcast.mc.flow.internalAddress system property is configured with service address of a Flow node.

Obtain an Access Token

If your application needs machine-to-machine communication with Flow, MC utilizes client credentials flow under the hood. Here are the steps:

  1. Set the MC_APPLICATION_CLIENT_SECRET environment variable, MC will create a client with a client credential grant type named application-client. For simplicity, let’s assume the environment variable is set to qqq for a quick example.

  2. Run this Docker Compose file.

  3. Get an access token from MC and use it as bearer token in subsequent requests to Flow. Example curl request for Viewer role:

curl --location '\{MC-host\}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic YXBwbGljYXRpb24tY2xpZW50OnFxcQ==' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=openid email profile flow:Viewer'

Notices:

  • MC_APPLICATION_CLIENT_SECRET can be omitted from the environment variables to disable client credential grants

  • MC_APPLICATION_CLIENT_SECRET should be treated as a secret and set to a secure string. Consider using the following or similar to generate a secure secret
    openssl rand -base64 32

  • The {MC-host} in the example should be set to the Management Center hostname. The default config listens on http://localhost:8080 unless overridden

  • The example Authorization header: YXBwbGljYXRpb24tY2xpZW50OnFxcQ== is the base64 encoded version of application-client:qqq

  • If flow is not set in scope, the admin role will be assigned

  • Multiple roles are also supported, example curl request for Viewer and MetricsViewer:

curl --location '{MC-host}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic YXBwbGljYXRpb24tY2xpZW50OnFxcQ==' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=openid email profile flow:Viewer flow:MetricsViewer'

See also

lifebuoy

Help and support