text: ## What is this about?
  
  ## How to enable UI authentication?
  
  1. Change config file gear.conf, find entry `gearpump-ui.gearpump.ui-security.authentication-enabled`, change the value to true
  
      	:::bash	
      	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.
  
  ## How many authentication methods Gearpump UI server support?
  
  Currently, It supports:
  
  1. Username-Password based authentication and
  2. OAuth2 based authentication.
  
  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
  
     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: built-in User-Password Authenticator
  
  ConfigFileBasedAuthenticator store all user name and password hashcode in configuration file gear.conf. Here
  is the steps to configure ConfigFileBasedAuthenticator.
  
  #### How to add or remove user?
  
  For the default authentication plugin, it has three categories of users: admins, users, and guests.
  
  * admins: have unlimited permission, like shutdown a cluster, add/remove machines.
  * users: have limited permission to submit an application and etc..
  * guests: can not submit/kill applications, but can view the application status.
  
  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:
    
  1. Pick a password, and generate the digest for this password. Suppose we use password `ilovegearpump`, 
     to generate the digest:
     
      	:::bash
      	bin/gear org.apache.gearpump.security.PasswordUtil -password  ilovegearpump
      
     
      It will generate a digest value like this:
     
      	:::bash
      	CgGxGOxlU8ggNdOXejCeLxy+isrCv0TrS37HwA==
      
  
  2. Change config file conf/gear.conf at path `gearpump-ui.gearpump.ui-security.config-file-based-authenticator.admins`,
     add user `jerry` in this list:
     
      	:::bash
  	    admins = {
  	      ## Default Admin. Username: admin, password: admin
  	      ## !!! Please replace this builtin account for production cluster for security reason. !!!
  	      "admin" = "AeGxGOxlU8QENdOXejCeLxy+isrCv0TrS37HwA=="
  	      "jerry" = "CgGxGOxlU8ggNdOXejCeLxy+isrCv0TrS37HwA=="
  	    }
      
  
  3. Restart the UI dashboard by `bin/services` to make the change effective.
  
  4. 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`.
  
  5. See description at `conf/gear.conf` to find more information.   
     
  #### What is the default user and password?
  
  For ConfigFileBasedAuthenticator, Gearpump distribution is shipped with two default users:
  
  1. username: admin, password: admin
  2. username: guest, password: guest
  
  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.
  
  #### Is this secure?
  
  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.
  
  ### How to develop a custom User-Password Authenticator for LDAP, Database, and etc..
  
  If developer choose to define his/her own User-Password based authenticator, it is required that user
      modify configuration option:
  
  	:::bash
  	## 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:
  
  	:::scala
  	trait Authenticator {
  	
  	  def authenticate(user: String, password: String, ec: ExecutionContext): Future[AuthenticationResult]
  	}
  
  
  ## OAuth2 based authentication
  
  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:
   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.
  
  ### Terminologies
  
  For terms like client Id, and client secret, please refers to guide [RFC 6749](https://tools.ietf.org/html/rfc6749)
  
  ### Enable web proxy for UI server
  
  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.
  
  #### If you are on Windows
  
  	:::bash
  	set JAVA_OPTS=-Dhttp.proxyHost=xx.com -Dhttp.proxyPort=8088 -Dhttps.proxyHost=xx.com -Dhttps.proxyPort=8088
  	bin/services
  
  
  #### If you are on Linux
  
  	:::bash
      export JAVA_OPTS="-Dhttp.proxyHost=xx.com -Dhttp.proxyPort=8088 -Dhttps.proxyHost=xx.com -Dhttps.proxyPort=8088"
      bin/services
  
  
  ### Google Plus OAuth2 Authenticator
  
  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:
  
  1. Register your application (Gearpump UI server here) as an application to Google developer console.
  2. Configure the Google OAuth2 information in gear.conf
  3. Configure network proxy for Gearpump UI server if applies.
  
  #### Step1: Register your website as an OAuth2 Application on Google
  
  1. Create an application representing your website at [https://console.developers.google.com](https://console.developers.google.com)
  2. In "API Manager" of your created application, enable API "Google+ API"
  3. Create OAuth client ID for this application. In "Credentials" tab of "API Manager",
  choose "Create credentials", and then select OAuth client ID. Follow the wizard
  to set callback URL, and generate client ID, and client Secret.
  
  **NOTE:** Callback URL is NOT optional.
  
  #### Step2: Configure the OAuth2 information in gear.conf
  
  1. Enable OAuth2 authentication by setting `gearpump.ui-security.oauth2-authenticator-enabled`
  as true.
  2. Configure section `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.
  
  #### Step3: Configure the network proxy if applies.
  
  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.
  
  #### Step4: Restart the UI server and try to click the Google login icon on UI server.
  
  ### CloudFoundry UAA server OAuth2 Authenticator
  
  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](https://github.com/cloudfoundry/uaa)
  
  To use Google OAuth2 Authenticator, there are several steps:
  
  1. Register your application (Gearpump UI server here) as an application to UAA with helper tool `uaac`.
  2. Configure the Google OAuth2 information in gear.conf
  3. Configure network proxy for Gearpump UI server if applies.
  
  #### Step1: Register your application to UAA with `uaac`
  
  1. Check tutorial on uaac at [https://docs.cloudfoundry.org/adminguide/uaa-user-management.html](https://docs.cloudfoundry.org/adminguide/uaa-user-management.html)
  2. Open a bash shell, set the UAA server by command `uaac target`
  
  	    :::bash
  	    uaac target [your uaa server url]
      
      
  3. Login in as user admin by
  
  	    :::bash
  	    uaac token client get admin -s MyAdminPassword
  	    
      
  4. Create a new Application (Client) in UAA,
      
  	    :::bash
  	    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]
  	    
  
  #### Step2: Configure the OAuth2 information in gear.conf
  
  1. Enable OAuth2 authentication by setting `gearpump.ui-security.oauth2-authenticator-enabled` as true.
  2. Navigate to section `gearpump.ui-security.oauth2-authenticators.cloudfoundryuaa`
  3. Config gear.conf `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.
  
  #### Step3: Configure network proxy for Gearpump UI server if applies
  
  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.
  
  #### Step4: Restart the UI server and try to click the CloudFoundry login icon on UI server.
  
  #### Step5: You can also enable additional authenticator for CloudFoundry UAA by setting config:
  
  	:::bash
  	additional-authenticator-enabled = true
  	
  
  Please see description in gear.conf for more information.
  
  #### Extends OAuth2Authenticator to support new Authorization service like Facebook, or Twitter.
  
  You can follow the Google OAuth2 example code to define a custom OAuth2Authenticator. Basically, the steps includes:
  
  1. Define an OAuth2Authenticator implementation.
  
  2. 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`.