blob: e17a20e9cd81e30dd65c2a531beca2f2b8d1e45e [file] [log] [blame]
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="../../img/favicon.ico">
<title>UI Authentication - Apache Gearpump(incubating)</title>
<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="../../css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../css/theme_extra.css" type="text/css" />
<link rel="stylesheet" href="../../css/highlight.css">
<script>
// Current page data
var mkdocs_page_name = "UI Authentication";
var mkdocs_page_input_path = "deployment/deployment-ui-authentication.md";
var mkdocs_page_url = "/deployment/deployment-ui-authentication/index.html";
</script>
<script src="../../js/jquery-2.1.1.min.js"></script>
<script src="../../js/modernizr-2.8.3.min.js"></script>
<script type="text/javascript" src="../../js/highlight.pack.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
<div class="wy-side-nav-search">
<a href="../../index.html" class="icon icon-home"> Apache Gearpump(incubating)</a>
<div role="search">
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1">
<a class="" href="../../index.html">Overview</a>
</li>
<li class="toctree-l1">
<span class="caption-text">Introduction</span>
<ul class="subnav">
<li class="">
<a class="" href="../../introduction/submit-your-1st-application/index.html">Submit Your 1st Application</a>
</li>
<li class="">
<a class="" href="../../introduction/commandline/index.html">Client Command Line</a>
</li>
<li class="">
<a class="" href="../../introduction/basic-concepts/index.html">Basic Concepts</a>
</li>
<li class="">
<a class="" href="../../introduction/features/index.html">Technical Highlights</a>
</li>
<li class="">
<a class="" href="../../introduction/message-delivery/index.html">Reliable Message Delivery</a>
</li>
<li class="">
<a class="" href="../../introduction/performance-report/index.html">Performance</a>
</li>
</ul>
</li>
<li class="toctree-l1">
<span class="caption-text">Deployment</span>
<ul class="subnav">
<li class="">
<a class="" href="../deployment-local/index.html">Local Mode</a>
</li>
<li class="">
<a class="" href="../deployment-standalone/index.html">Standalone Mode</a>
</li>
<li class="">
<a class="" href="../deployment-yarn/index.html">YARN Mode</a>
</li>
<li class="">
<a class="" href="../deployment-docker/index.html">Docker Mode</a>
</li>
<li class=" current">
<a class="current" href="index.html">UI Authentication</a>
<ul class="subnav">
<li class="toctree-l3"><a href="#what-is-this-about">What is this about?</a></li>
<li class="toctree-l3"><a href="#how-to-enable-ui-authentication">How to enable UI authentication?</a></li>
<li class="toctree-l3"><a href="#how-many-authentication-methods-gearpump-ui-server-support">How many authentication methods Gearpump UI server support?</a></li>
<li class="toctree-l3"><a href="#user-password-based-authentication">User-Password based authentication</a></li>
<ul>
<li><a class="toctree-l4" href="#configfilebasedauthenticator-built-in-user-password-authenticator">ConfigFileBasedAuthenticator: built-in User-Password Authenticator</a></li>
<li><a class="toctree-l4" href="#how-to-develop-a-custom-user-password-authenticator-for-ldap-database-and-etc">How to develop a custom User-Password Authenticator for LDAP, Database, and etc..</a></li>
</ul>
<li class="toctree-l3"><a href="#oauth2-based-authentication">OAuth2 based authentication</a></li>
<ul>
<li><a class="toctree-l4" href="#terminologies">Terminologies</a></li>
<li><a class="toctree-l4" href="#enable-web-proxy-for-ui-server">Enable web proxy for UI server</a></li>
<li><a class="toctree-l4" href="#google-plus-oauth2-authenticator">Google Plus OAuth2 Authenticator</a></li>
<li><a class="toctree-l4" href="#cloudfoundry-uaa-server-oauth2-authenticator">CloudFoundry UAA server OAuth2 Authenticator</a></li>
</ul>
</ul>
</li>
<li class="">
<a class="" href="../deployment-ha/index.html">High Availability</a>
</li>
<li class="">
<a class="" href="../deployment-msg-delivery/index.html">Reliable Message Delivery</a>
</li>
<li class="">
<a class="" href="../deployment-configuration/index.html">Configuration</a>
</li>
<li class="">
<a class="" href="../deployment-resource-isolation/index.html">Resource Isolation</a>
</li>
<li class="">
<a class="" href="../deployment-security/index.html">YARN Security Guide</a>
</li>
<li class="">
<a class="" href="../get-gearpump-distribution/index.html">How to Get Your Gearpump Distribution</a>
</li>
<li class="">
<a class="" href="../hardware-requirement/index.html">Hardware Requirement</a>
</li>
</ul>
</li>
<li class="toctree-l1">
<span class="caption-text">Programming Guide</span>
<ul class="subnav">
<li class="">
<a class="" href="../../dev/dev-write-1st-app/index.html">Write Your 1st App</a>
</li>
<li class="">
<a class="" href="../../dev/dev-custom-serializer/index.html">Customized Message Passing</a>
</li>
<li class="">
<a class="" href="../../dev/dev-connectors/index.html">Gearpump Connectors</a>
</li>
<li class="">
<a class="" href="../../dev/dev-storm/index.html">Storm Compatibility</a>
</li>
<li class="">
<a class="" href="../../dev/dev-ide-setup/index.html">IDE Setup</a>
</li>
<li class="">
<a class="" href="../../dev/dev-non-streaming-example/index.html">Non Streaming Examples</a>
</li>
<li class="">
<a class="" href="../../dev/dev-rest-api/index.html">REST API</a>
</li>
<li class="">
<a class="" href="../../api/scala/index.html">Scala API</a>
</li>
<li class="">
<a class="" href="../../api/java/index.html">Java API</a>
</li>
</ul>
</li>
<li class="toctree-l1">
<span class="caption-text">Internals</span>
<ul class="subnav">
<li class="">
<a class="" href="../../internals/gearpump-internals/index.html">Gearpump Internals</a>
</li>
</ul>
</li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">Apache Gearpump(incubating)</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html">Docs</a> &raquo;</li>
<li>Deployment &raquo;</li>
<li>UI Authentication</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/incubator-gearpump/edit/master/docs/contents/deployment/deployment-ui-authentication.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main">
<div class="section">
<h2 id="what-is-this-about">What is this about?</h2>
<h2 id="how-to-enable-ui-authentication">How to enable UI authentication?</h2>
<ol>
<li>
<p>Change config file gear.conf, find entry <code>gearpump-ui.gearpump.ui-security.authentication-enabled</code>, change the value to true</p>
<pre class="codehilite"><code class="language-bash">gearpump-ui.gearpump.ui-security.authentication-enabled = true</code></pre>
<p>Restart the UI dashboard, and then the UI authentication is enabled. It will prompt for user name and password.</p>
</li>
</ol>
<h2 id="how-many-authentication-methods-gearpump-ui-server-support">How many authentication methods Gearpump UI server support?</h2>
<p>Currently, It supports:</p>
<ol>
<li>Username-Password based authentication and</li>
<li>OAuth2 based authentication.</li>
</ol>
<p>User-Password based authentication is enabled when <code>gearpump-ui.gearpump.ui-security.authentication-enabled</code>,
and <strong>CANNOT</strong> be disabled.</p>
<p>UI server admin can also choose to enable <strong>auxiliary</strong> OAuth2 authentication channel.</p>
<h2 id="user-password-based-authentication">User-Password based authentication</h2>
<p>User-Password based authentication covers all authentication scenarios which requires
user to enter an explicit username and password.</p>
<p>Gearpump provides a built-in ConfigFileBasedAuthenticator which verify user name and password
against password hashcode stored in config files.</p>
<p>However, developer can choose to extends the <code>org.apache.gearpump.security.Authenticator</code> to provide a custom
User-Password based authenticator, to support LDAP, Kerberos, and Database-based authentication...</p>
<h3 id="configfilebasedauthenticator-built-in-user-password-authenticator">ConfigFileBasedAuthenticator: built-in User-Password Authenticator</h3>
<p>ConfigFileBasedAuthenticator store all user name and password hashcode in configuration file gear.conf. Here
is the steps to configure ConfigFileBasedAuthenticator.</p>
<h4 id="how-to-add-or-remove-user">How to add or remove user?</h4>
<p>For the default authentication plugin, it has three categories of users: admins, users, and guests.</p>
<ul>
<li>admins: have unlimited permission, like shutdown a cluster, add/remove machines.</li>
<li>users: have limited permission to submit an application and etc..</li>
<li>guests: can not submit/kill applications, but can view the application status.</li>
</ul>
<p>System administrator can add or remove user by updating config file <code>conf/gear.conf</code>. </p>
<p>Suppose we want to add user jerry as an administrator, here are the steps:</p>
<ol>
<li>
<p>Pick a password, and generate the digest for this password. Suppose we use password <code>ilovegearpump</code>,
to generate the digest:</p>
<pre class="codehilite"><code class="language-bash">bin/gear org.apache.gearpump.security.PasswordUtil -password ilovegearpump</code></pre>
<p>It will generate a digest value like this:</p>
<pre class="codehilite"><code class="language-bash">CgGxGOxlU8ggNdOXejCeLxy+isrCv0TrS37HwA==</code></pre>
</li>
<li>
<p>Change config file conf/gear.conf at path <code>gearpump-ui.gearpump.ui-security.config-file-based-authenticator.admins</code>,
add user <code>jerry</code> in this list:</p>
<pre class="codehilite"><code class="language-bash">admins = {
## Default Admin. Username: admin, password: admin
## !!! Please replace this builtin account for production cluster for security reason. !!!
&quot;admin&quot; = &quot;AeGxGOxlU8QENdOXejCeLxy+isrCv0TrS37HwA==&quot;
&quot;jerry&quot; = &quot;CgGxGOxlU8ggNdOXejCeLxy+isrCv0TrS37HwA==&quot;
}</code></pre>
</li>
<li>
<p>Restart the UI dashboard by <code>bin/services</code> to make the change effective.</p>
</li>
<li>
<p>Group "admins" have very unlimited permission, you may want to restrict the permission. In that case
you can modify <code>gearpump-ui.gearpump.ui-security.config-file-based-authenticator.users</code> or
<code>gearpump-ui.gearpump.ui-security.config-file-based-authenticator.guests</code>.</p>
</li>
<li>
<p>See description at <code>conf/gear.conf</code> to find more information. </p>
</li>
</ol>
<h4 id="what-is-the-default-user-and-password">What is the default user and password?</h4>
<p>For ConfigFileBasedAuthenticator, Gearpump distribution is shipped with two default users:</p>
<ol>
<li>username: admin, password: admin</li>
<li>username: guest, password: guest</li>
</ol>
<p>User <code>admin</code> has unlimited permissions, while <code>guest</code> can only view the application status.</p>
<p>For security reason, you need to remove the default users <code>admin</code> and <code>guest</code> for cluster in production.</p>
<h4 id="is-this-secure">Is this secure?</h4>
<p>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.</p>
<h3 id="how-to-develop-a-custom-user-password-authenticator-for-ldap-database-and-etc">How to develop a custom User-Password Authenticator for LDAP, Database, and etc..</h3>
<p>If developer choose to define his/her own User-Password based authenticator, it is required that user
modify configuration option:</p>
<pre class="codehilite"><code class="language-bash">## Replace &quot;org.apache.gearpump.security.CustomAuthenticator&quot; with your real authenticator class.
gearpump.ui-security.authenticator = &quot;org.apache.gearpump.security.CustomAuthenticator&quot;</code></pre>
<p>Make sure CustomAuthenticator extends interface:</p>
<pre class="codehilite"><code class="language-scala">trait Authenticator {
def authenticate(user: String, password: String, ec: ExecutionContext): Future[AuthenticationResult]
}</code></pre>
<h2 id="oauth2-based-authentication">OAuth2 based authentication</h2>
<p>OAuth2 based authentication is commonly use to achieve social login with social network account.</p>
<p>Gearpump provides generic OAuth2 Authentication support which allow user to extend to support new authentication sources.</p>
<p>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.</p>
<h3 id="terminologies">Terminologies</h3>
<p>For terms like client Id, and client secret, please refers to guide <a href="https://tools.ietf.org/html/rfc6749">RFC 6749</a></p>
<h3 id="enable-web-proxy-for-ui-server">Enable web proxy for UI server</h3>
<p>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.</p>
<h4 id="if-you-are-on-windows">If you are on Windows</h4>
<pre class="codehilite"><code class="language-bash">set JAVA_OPTS=-Dhttp.proxyHost=xx.com -Dhttp.proxyPort=8088 -Dhttps.proxyHost=xx.com -Dhttps.proxyPort=8088
bin/services</code></pre>
<h4 id="if-you-are-on-linux">If you are on Linux</h4>
<pre class="codehilite"><code class="language-bash">export JAVA_OPTS=&quot;-Dhttp.proxyHost=xx.com -Dhttp.proxyPort=8088 -Dhttps.proxyHost=xx.com -Dhttps.proxyPort=8088&quot;
bin/services</code></pre>
<h3 id="google-plus-oauth2-authenticator">Google Plus OAuth2 Authenticator</h3>
<p>Google Plus OAuth2 Authenticator does authentication with Google OAuth2 service. It extracts the email address
from Google user profile as credentials.</p>
<p>To use Google OAuth2 Authenticator, there are several steps:</p>
<ol>
<li>Register your application (Gearpump UI server here) as an application to Google developer console.</li>
<li>Configure the Google OAuth2 information in gear.conf</li>
<li>Configure network proxy for Gearpump UI server if applies.</li>
</ol>
<h4 id="step1-register-your-website-as-an-oauth2-application-on-google">Step1: Register your website as an OAuth2 Application on Google</h4>
<ol>
<li>Create an application representing your website at <a href="https://console.developers.google.com">https://console.developers.google.com</a></li>
<li>In "API Manager" of your created application, enable API "Google+ API"</li>
<li>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.</li>
</ol>
<p><strong>NOTE:</strong> Callback URL is NOT optional.</p>
<h4 id="step2-configure-the-oauth2-information-in-gearconf">Step2: Configure the OAuth2 information in gear.conf</h4>
<ol>
<li>Enable OAuth2 authentication by setting <code>gearpump.ui-security.oauth2-authenticator-enabled</code>
as true.</li>
<li>Configure section <code>gearpump.ui-security.oauth2-authenticators.google</code> in gear.conf. Please make sure
class name, client ID, client Secret, and callback URL are set properly.</li>
</ol>
<p><strong>NOTE:</strong> Callback URL set here should match what is configured on Google in step1.</p>
<h4 id="step3-configure-the-network-proxy-if-applies">Step3: Configure the network proxy if applies.</h4>
<p>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.</p>
<p>For guide of how to configure web proxy for UI server, please refer to section "Enable web proxy for UI server" above.</p>
<h4 id="step4-restart-the-ui-server-and-try-to-click-the-google-login-icon-on-ui-server">Step4: Restart the UI server and try to click the Google login icon on UI server.</h4>
<h3 id="cloudfoundry-uaa-server-oauth2-authenticator">CloudFoundry UAA server OAuth2 Authenticator</h3>
<p>CloudFoundryUaaAuthenticator does authentication by using CloudFoundry UAA OAuth2 service. It extracts the email address
from Google user profile as credentials.</p>
<p>For what is UAA (User Account and Authentication Service), please see guide: <a href="https://github.com/cloudfoundry/uaa">UAA</a></p>
<p>To use Google OAuth2 Authenticator, there are several steps:</p>
<ol>
<li>Register your application (Gearpump UI server here) as an application to UAA with helper tool <code>uaac</code>.</li>
<li>Configure the Google OAuth2 information in gear.conf</li>
<li>Configure network proxy for Gearpump UI server if applies.</li>
</ol>
<h4 id="step1-register-your-application-to-uaa-with-uaac">Step1: Register your application to UAA with <code>uaac</code></h4>
<ol>
<li>Check tutorial on uaac at <a href="https://docs.cloudfoundry.org/adminguide/uaa-user-management.html">https://docs.cloudfoundry.org/adminguide/uaa-user-management.html</a></li>
<li>
<p>Open a bash shell, set the UAA server by command <code>uaac target</code></p>
<pre class="codehilite"><code class="language-bash">uaac target [your uaa server url]</code></pre>
</li>
<li>
<p>Login in as user admin by</p>
<pre class="codehilite"><code class="language-bash">uaac token client get admin -s MyAdminPassword</code></pre>
</li>
<li>
<p>Create a new Application (Client) in UAA,</p>
<pre class="codehilite"><code class="language-bash">uaac client add [your_client_id]
--scope &quot;openid cloud_controller.read&quot;
--authorized_grant_types &quot;authorization_code client_credentials refresh_token&quot;
--authorities &quot;openid cloud_controller.read&quot;
--redirect_uri [your_redirect_url]
--autoapprove true
--secret [your_client_secret]</code></pre>
</li>
</ol>
<h4 id="step2-configure-the-oauth2-information-in-gearconf_1">Step2: Configure the OAuth2 information in gear.conf</h4>
<ol>
<li>Enable OAuth2 authentication by setting <code>gearpump.ui-security.oauth2-authenticator-enabled</code> as true.</li>
<li>Navigate to section <code>gearpump.ui-security.oauth2-authenticators.cloudfoundryuaa</code></li>
<li>Config gear.conf <code>gearpump.ui-security.oauth2-authenticators.cloudfoundryuaa</code> section.
Please make sure class name, client ID, client Secret, and callback URL are set properly.</li>
</ol>
<p><strong>NOTE:</strong> The callback URL here should match what you set on CloudFoundry UAA in step1.</p>
<h4 id="step3-configure-network-proxy-for-gearpump-ui-server-if-applies">Step3: Configure network proxy for Gearpump UI server if applies</h4>
<p>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.</p>
<p>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.</p>
<h4 id="step4-restart-the-ui-server-and-try-to-click-the-cloudfoundry-login-icon-on-ui-server">Step4: Restart the UI server and try to click the CloudFoundry login icon on UI server.</h4>
<h4 id="step5-you-can-also-enable-additional-authenticator-for-cloudfoundry-uaa-by-setting-config">Step5: You can also enable additional authenticator for CloudFoundry UAA by setting config:</h4>
<pre class="codehilite"><code class="language-bash">additional-authenticator-enabled = true</code></pre>
<p>Please see description in gear.conf for more information.</p>
<h4 id="extends-oauth2authenticator-to-support-new-authorization-service-like-facebook-or-twitter">Extends OAuth2Authenticator to support new Authorization service like Facebook, or Twitter.</h4>
<p>You can follow the Google OAuth2 example code to define a custom OAuth2Authenticator. Basically, the steps includes:</p>
<ol>
<li>
<p>Define an OAuth2Authenticator implementation.</p>
</li>
<li>
<p>Add an configuration entry under <code>gearpump.ui-security.oauth2-authenticators</code>. For example:</p>
<pre class="codehilite"><code>## name of this authenticator
&quot;socialnetworkx&quot; {
&quot;class&quot; = &quot;org.apache.gearpump.services.security.oauth2.impl.SocialNetworkXAuthenticator&quot;
## Please make sure this URL matches the name
&quot;callback&quot; = &quot;http://127.0.0.1:8090/login/oauth2/socialnetworkx/callback&quot;
&quot;clientId&quot; = &quot;gearpump_test2&quot;
&quot;clientSecret&quot; = &quot;gearpump_test2&quot;
&quot;defaultUserRole&quot; = &quot;guest&quot;
## Make sure socialnetworkx.png exists under dashboard/icons
&quot;icon&quot; = &quot;/icons/socialnetworkx.png&quot;
}</code></pre>
</li>
</ol>
<p>The configuration entry is supposed to be used by class <code>SocialNetworkXAuthenticator</code>.</p>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="../deployment-ha/index.html" class="btn btn-neutral float-right" title="High Availability">Next <span class="icon icon-circle-arrow-right"></span></a>
<a href="../deployment-docker/index.html" class="btn btn-neutral" title="Docker Mode"><span class="icon icon-circle-arrow-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<!-- Copyright etc -->
</div>
Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<div class="rst-versions" role="note" style="cursor: pointer">
<span class="rst-current-version" data-toggle="rst-current-version">
<a href="https://github.com/apache/incubator-gearpump" class="fa fa-github" style="float: left; color: #fcfcfc"> GitHub</a>
<span><a href="../deployment-docker/index.html" style="color: #fcfcfc;">&laquo; Previous</a></span>
<span style="margin-left: 15px"><a href="../deployment-ha/index.html" style="color: #fcfcfc">Next &raquo;</a></span>
</span>
</div>
<script src="../../js/theme.js"></script>
</body>
</html>