Change config file gear.conf, find entry gearpump-ui.gearpump.ui-security.authentication-enabled
, change the value to true
gearpump-ui.gearpump.ui-security.authentication-enabled = true
Restart the UI dashboard, and then the UI authentication is enabled. It will prompt for user name and password.
Currently, It supports:
User-Password based authentication is enabled when gearpump-ui.gearpump.ui-security.authentication-enabled
, and CANNOT be disabled.
UI server admin can also choose to enable auxiliary OAuth2 authentication channel.
User-Password based authentication covers all authentication scenarios which requires user to enter an explicit username and password.
Gearpump provides a built-in ConfigFileBasedAuthenticator which verify user name and password against password hashcode stored in config files.
However, developer can choose to extends the org.apache.gearpump.security.Authenticator
to provide a custom User-Password based authenticator, to support LDAP, Kerberos, and Database-based authentication...
ConfigFileBasedAuthenticator store all user name and password hashcode in configuration file gear.conf. Here is the steps to configure ConfigFileBasedAuthenticator.
For the default authentication plugin, it has three categories of users: admins, users, and guests.
System administrator can add or remove user by updating config file conf/gear.conf
.
Suppose we want to add user jerry as an administrator, here are the steps:
Pick a password, and generate the digest for this password. Suppose we use password ilovegearpump
, to generate the digest:
bin/gear org.apache.gearpump.security.PasswordUtil -password ilovegearpump
It will generate a digest value like this:
CgGxGOxlU8ggNdOXejCeLxy+isrCv0TrS37HwA==
Change config file conf/gear.conf at path gearpump-ui.gearpump.ui-security.config-file-based-authenticator.admins
, add user jerry
in this list:
admins = { ## Default Admin. Username: admin, password: admin ## !!! Please replace this builtin account for production cluster for security reason. !!! "admin" = "AeGxGOxlU8QENdOXejCeLxy+isrCv0TrS37HwA==" "jerry" = "CgGxGOxlU8ggNdOXejCeLxy+isrCv0TrS37HwA==" }
Restart the UI dashboard by bin/services
to make the change effective.
Group “admins” have very unlimited permission, you may want to restrict the permission. In that case you can modify gearpump-ui.gearpump.ui-security.config-file-based-authenticator.users
or gearpump-ui.gearpump.ui-security.config-file-based-authenticator.guests
.
See description at conf/gear.conf
to find more information.
For ConfigFileBasedAuthenticator, Gearpump distribution is shipped with two default users:
User admin
has unlimited permissions, while guest
can only view the application status.
For security reason, you need to remove the default users admin
and guest
for cluster in production.
Firstly, we will NOT store any user password in any way so only the user himself knows the password. We will use one-way hash digest to verify the user input password.
If developer choose to define his/her own User-Password based authenticator, it is required that user modify configuration option:
## Replace "org.apache.gearpump.security.CustomAuthenticator" with your real authenticator class. gearpump.ui-security.authenticator = "org.apache.gearpump.security.CustomAuthenticator"
Make sure CustomAuthenticator extends interface:
trait Authenticator { def authenticate(user: String, password: String, ec: ExecutionContext): Future[AuthenticationResult] }
OAuth2 based authentication is commonly use to achieve social login with social network account.
Gearpump provides generic OAuth2 Authentication support which allow user to extend to support new authentication sources.
Basically, OAuth2 based Authentication contains these steps:
For terms like client Id, and client secret, please refers to guide RFC 6749
To enable OAuth2 authentication, the Gearpump UI server should have network access to OAuth2 server, as some requests are initiated directly inside Gearpump UI server. So, if you are behind a firewall, make sure you have configured the proxy properly for UI server.
> set JAVA_OPTS=-Dhttp.proxyHost=xx.com -Dhttp.proxyPort=8088 -Dhttps.proxyHost=xx.com -Dhttps.proxyPort=8088 > bin\services
$ export JAVA_OPTS="-Dhttp.proxyHost=xx.com -Dhttp.proxyPort=8088 -Dhttps.proxyHost=xx.com -Dhttps.proxyPort=8088" $ bin/services
Google Plus OAuth2 Authenticator does authentication with Google OAuth2 service. It extracts the email address from Google user profile as credentials.
To use Google OAuth2 Authenticator, there are several steps:
NOTE: Callback URL is NOT optional.
gearpump.ui-security.oauth2-authenticator-enabled
as true.gearpump.ui-security.oauth2-authenticators.google
in gear.conf. Please make sure class name, client ID, client Secret, and callback URL are set properly.NOTE: Callback URL set here should match what is configured on Google in step1.
To enable OAuth2 authentication, the Gearpump UI server should have network access to Google service, as some requests are initiated directly inside Gearpump UI server. So, if you are behind a firewall, make sure you have configured the proxy properly for UI server.
For guide of how to configure web proxy for UI server, please refer to section “Enable web proxy for UI server” above.
CloudFoundryUaaAuthenticator does authentication by using CloudFoundry UAA OAuth2 service. It extracts the email address from Google user profile as credentials.
For what is UAA (User Account and Authentication Service), please see guide: UAA
To use Google OAuth2 Authenticator, there are several steps:
uaac
.uaac
Check tutorial on uaac at https://docs.cloudfoundry.org/adminguide/uaa-user-management.html
Open a bash shell, set the UAA server by command uaac target
uaac target [your uaa server url]
Login in as user admin by
uaac token client get admin -s MyAdminPassword
Create a new Application (Client) in UAA,
uaac client add [your_client_id] --scope "openid cloud_controller.read" --authorized_grant_types "authorization_code client_credentials refresh_token" --authorities "openid cloud_controller.read" --redirect_uri [your_redirect_url] --autoapprove true --secret [your_client_secret]
gearpump.ui-security.oauth2-authenticator-enabled
as true.gearpump.ui-security.oauth2-authenticators.cloudfoundryuaa
gearpump.ui-security.oauth2-authenticators.cloudfoundryuaa
section. Please make sure class name, client ID, client Secret, and callback URL are set properly.NOTE: The callback URL here should match what you set on CloudFoundry UAA in step1.
To enable OAuth2 authentication, the Gearpump UI server should have network access to Google service, as some requests are initiated directly inside Gearpump UI server. So, if you are behind a firewall, make sure you have configured the proxy properly for UI server.
For guide of how to configure web proxy for UI server, please refer to please refer to section “Enable web proxy for UI server” above.
additional-authenticator-enabled = true
Please see description in gear.conf for more information.
You can follow the Google OAuth2 example code to define a custom OAuth2Authenticator. Basically, the steps includes:
Define an OAuth2Authenticator implementation.
/** * * Uses OAuth2 social-login as the mechanism for authentication. * @see [[https://tools.ietf.org/html/rfc6749]] to find what is OAuth2, and how it works. * * Basically flow for OAuth2 Authentication: * 1. User accesses Gearpump UI website, and choose to login with OAuth2 server. * 2. Gearpump UI website redirects user to OAuth2 server domain authorization endpoint. * 3. End user complete the authorization in the domain of OAuth2 server. * 4. OAuth2 server redirects user back to Gearpump UI server. * 5. Gearpump UI server verify the tokens and extract credentials from query * parameters and form fields. * * @note '''Thread-safety''' is a MUST requirement. Developer need to ensure the sub-class is thread-safe. * Sub-class should have a parameter-less constructor. * * @note OAuth2 Authenticator requires access of Internet. Please make sure HTTP proxy are * set properly if applied. * * @example Config proxy when UI server is started on Windows: * {{{ * > set JAVA_OPTS=-Dhttp.proxyHost=xx.com -Dhttp.proxyPort=8088 -Dhttps.proxyHost=xx.com -Dhttps.proxyPort=8088 * > bin\services * }}} * * @example Config proxy when UI server is started on Linux: * {{{ * $ export JAVA_OPTS="-Dhttp.proxyHost=xx.com -Dhttp.proxyPort=8088 -Dhttps.proxyHost=xx.com -Dhttps.proxyPort=8088" * $ bin/services * }}} * */ trait OAuth2Authenticator { /** * Inits authenticator with config which contains client ID, client secret, and etc.. * * Typically, the client key and client secret is provided by OAuth2 Authorization server when user * register an application there. * @see [[https://tools.ietf.org/html/rfc6749]] for definition of client, client Id, * and client secret. * * See [[https://developer.github.com/v3/oauth/]] for an actual example of how Github * use client key, and client secret. * * @note '''Thread-Safety''': Framework ensures this call is synchronized. * * @param config Client Id, client secret, callback URL and etc.. */ def init(config: Config): Unit /** * Returns the OAuth Authorization URL so for redirection to that address to do OAuth2 * authorization. * * @note '''Thread-Safety''': This can be called in a multi-thread environment. Developer * need to ensure thread safety. */ def getAuthorizationUrl: String /** * After authorization, OAuth2 server redirects user back with tokens. This verify the * tokens, retrieve the profiles, and return [[UserSession]] information. * * @note This is an Async call. * @note This call requires external internet access. * @note '''Thread-Safety''': This can be called in a multi-thread environment. Developer * need to ensure thread safety. * * @param parameters HTTP Query and Post parameters, which typically contains Authorization code. * @return UserSession if pass authentication. */ def authenticate(parameters: Map[String, String]): Future[UserSession] /** * Clean resource */ def close(): Unit }
Add an configuration entry under gearpump.ui-security.oauth2-authenticators
. For example:
## name of this authenticator "socialnetworkx" { "class" = "org.apache.gearpump.services.security.oauth2.impl.SocialNetworkXAuthenticator" ## Please make sure this URL matches the name "callback" = "http://127.0.0.1:8090/login/oauth2/socialnetworkx/callback" "clientId" = "gearpump_test2" "clientSecret" = "gearpump_test2" "defaultUserRole" = "guest" ## Make sure socialnetworkx.png exists under dashboard/icons icon = "/icons/socialnetworkx.png" }
The configuration entry is supposed to be used by class SocialNetworkXAuthenticator
.