Source code

001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase;
019
020import java.io.IOException;
021import java.net.UnknownHostException;
022import org.apache.hadoop.conf.Configuration;
023import org.apache.hadoop.hbase.security.User;
024import org.apache.hadoop.hbase.security.UserProvider;
025import org.apache.hadoop.hbase.util.DNS;
026import org.apache.hadoop.hbase.util.Strings;
027import org.apache.hadoop.security.UserGroupInformation;
028import org.apache.yetus.audience.InterfaceAudience;
029import org.slf4j.Logger;
030import org.slf4j.LoggerFactory;
031
032/**
033 * Utility methods for helping with security tasks. Downstream users may rely on this class to
034 * handle authenticating via keytab where long running services need access to a secure HBase
035 * cluster. Callers must ensure:
036 * <ul>
037 * <li>HBase configuration files are in the Classpath
038 * <li>hbase.client.keytab.file points to a valid keytab on the local filesystem
039 * <li>hbase.client.kerberos.principal gives the Kerberos principal to use
040 * </ul>
041 *
042 * <pre>
043 * {
044 *   &#64;code
045 *   ChoreService choreService = null;
046 *   // Presumes HBase configuration files are on the classpath
047 *   final Configuration conf = HBaseConfiguration.create();
048 *   final ScheduledChore authChore = AuthUtil.getAuthChore(conf);
049 *   if (authChore != null) {
050 *     choreService = new ChoreService("MY_APPLICATION");
051 *     choreService.scheduleChore(authChore);
052 *   }
053 *   try {
054 *     // do application work
055 *   } finally {
056 *     if (choreService != null) {
057 *       choreService.shutdown();
058 *     }
059 *   }
060 * }
061 * </pre>
062 *
063 * See the "Running Canary in a Kerberos-enabled Cluster" section of the HBase Reference Guide for
064 * an example of configuring a user of this Auth Chore to run on a secure cluster.
065 *
066 * <pre>
067 * </pre>
068 *
069 * This class will be internal used only from 2.2.0 version, and will transparently work for
070 * kerberized applications. For more, please refer
071 * <a href="http://hbase.apache.org/book.html#hbase.secure.configuration">Client-side Configuration
072 * for Secure Operation</a>
073 * @deprecated since 2.2.0, to be marked as
074 *             {@link org.apache.yetus.audience.InterfaceAudience.Private} in 4.0.0.
075 * @see <a href="https://issues.apache.org/jira/browse/HBASE-20886">HBASE-20886</a>
076 */
077@Deprecated
078@InterfaceAudience.Public
079public final class AuthUtil {
080  private static final Logger LOG = LoggerFactory.getLogger(AuthUtil.class);
081
082  /** Prefix character to denote group names */
083  private static final String GROUP_PREFIX = "@";
084
085  /** Client keytab file */
086  public static final String HBASE_CLIENT_KEYTAB_FILE = "hbase.client.keytab.file";
087
088  /** Client principal */
089  public static final String HBASE_CLIENT_KERBEROS_PRINCIPAL = "hbase.client.keytab.principal";
090
091  /** Configuration to automatically try to renew keytab-based logins */
092  public static final String HBASE_CLIENT_AUTOMATIC_KEYTAB_RENEWAL_KEY =
093    "hbase.client.keytab.automatic.renewal";
094  public static final boolean HBASE_CLIENT_AUTOMATIC_KEYTAB_RENEWAL_DEFAULT = true;
095
096  private AuthUtil() {
097    super();
098  }
099
100  /**
101   * For kerberized cluster, return login user (from kinit or from keytab if specified). For
102   * non-kerberized cluster, return system user.
103   * @param conf configuartion file n * @throws IOException login exception
104   */
105  @InterfaceAudience.Private
106  public static User loginClient(Configuration conf) throws IOException {
107    UserProvider provider = UserProvider.instantiate(conf);
108    User user = provider.getCurrent();
109    boolean securityOn = provider.isHBaseSecurityEnabled() && provider.isHadoopSecurityEnabled();
110
111    if (securityOn) {
112      boolean fromKeytab = provider.shouldLoginFromKeytab();
113      if (user.getUGI().hasKerberosCredentials()) {
114        // There's already a login user.
115        // But we should avoid misuse credentials which is a dangerous security issue,
116        // so here check whether user specified a keytab and a principal:
117        // 1. Yes, check if user principal match.
118        // a. match, just return.
119        // b. mismatch, login using keytab.
120        // 2. No, user may login through kinit, this is the old way, also just return.
121        if (fromKeytab) {
122          return checkPrincipalMatch(conf, user.getUGI().getUserName())
123            ? user
124            : loginFromKeytabAndReturnUser(provider);
125        }
126        return user;
127      } else if (fromKeytab) {
128        // Kerberos is on and client specify a keytab and principal, but client doesn't login yet.
129        return loginFromKeytabAndReturnUser(provider);
130      }
131    }
132    return user;
133  }
134
135  private static boolean checkPrincipalMatch(Configuration conf, String loginUserName) {
136    String configuredUserName = conf.get(HBASE_CLIENT_KERBEROS_PRINCIPAL);
137    boolean match = configuredUserName.equals(loginUserName);
138    if (!match) {
139      LOG.warn("Trying to login with a different user: {}, existed user is {}.", configuredUserName,
140        loginUserName);
141    }
142    return match;
143  }
144
145  private static User loginFromKeytabAndReturnUser(UserProvider provider) throws IOException {
146    try {
147      provider.login(HBASE_CLIENT_KEYTAB_FILE, HBASE_CLIENT_KERBEROS_PRINCIPAL);
148    } catch (IOException ioe) {
149      LOG.error("Error while trying to login as user {} through {}, with message: {}.",
150        HBASE_CLIENT_KERBEROS_PRINCIPAL, HBASE_CLIENT_KEYTAB_FILE, ioe.getMessage());
151      throw ioe;
152    }
153    return provider.getCurrent();
154  }
155
156  /**
157   * For kerberized cluster, return login user (from kinit or from keytab). Principal should be the
158   * following format: name/fully.qualified.domain.name@REALM. For non-kerberized cluster, return
159   * system user.
160   * <p>
161   * NOT recommend to use to method unless you're sure what you're doing, it is for canary only.
162   * Please use User#loginClient.
163   * @param conf configuration file n * @throws IOException login exception
164   */
165  private static User loginClientAsService(Configuration conf) throws IOException {
166    UserProvider provider = UserProvider.instantiate(conf);
167    if (provider.isHBaseSecurityEnabled() && provider.isHadoopSecurityEnabled()) {
168      try {
169        if (provider.shouldLoginFromKeytab()) {
170          String host = Strings.domainNamePointerToHostName(
171            DNS.getDefaultHost(conf.get("hbase.client.dns.interface", "default"),
172              conf.get("hbase.client.dns.nameserver", "default")));
173          provider.login(HBASE_CLIENT_KEYTAB_FILE, HBASE_CLIENT_KERBEROS_PRINCIPAL, host);
174        }
175      } catch (UnknownHostException e) {
176        LOG.error("Error resolving host name: " + e.getMessage(), e);
177        throw e;
178      } catch (IOException e) {
179        LOG.error("Error while trying to perform the initial login: " + e.getMessage(), e);
180        throw e;
181      }
182    }
183    return provider.getCurrent();
184  }
185
186  /**
187   * Checks if security is enabled and if so, launches chore for refreshing kerberos ticket.
188   * @return a ScheduledChore for renewals.
189   */
190  @InterfaceAudience.Private
191  public static ScheduledChore getAuthRenewalChore(final UserGroupInformation user,
192    Configuration conf) {
193    if (!user.hasKerberosCredentials() || !isAuthRenewalChoreEnabled(conf)) {
194      return null;
195    }
196
197    Stoppable stoppable = createDummyStoppable();
198    // if you're in debug mode this is useful to avoid getting spammed by the getTGT()
199    // you can increase this, keeping in mind that the default refresh window is 0.8
200    // e.g. 5min tgt * 0.8 = 4min refresh so interval is better be way less than 1min
201    final int CHECK_TGT_INTERVAL = 30 * 1000; // 30sec
202    return new ScheduledChore("RefreshCredentials", stoppable, CHECK_TGT_INTERVAL) {
203      @Override
204      protected void chore() {
205        try {
206          user.checkTGTAndReloginFromKeytab();
207        } catch (IOException e) {
208          LOG.error("Got exception while trying to refresh credentials: " + e.getMessage(), e);
209        }
210      }
211    };
212  }
213
214  /**
215   * Checks if security is enabled and if so, launches chore for refreshing kerberos ticket.
216   * @param conf the hbase service configuration
217   * @return a ScheduledChore for renewals, if needed, and null otherwise.
218   * @deprecated Deprecated since 2.2.0, this method will be
219   *             {@link org.apache.yetus.audience.InterfaceAudience.Private} use only after 4.0.0.
220   * @see <a href="https://issues.apache.org/jira/browse/HBASE-20886">HBASE-20886</a>
221   */
222  @Deprecated
223  public static ScheduledChore getAuthChore(Configuration conf) throws IOException {
224    if (!isAuthRenewalChoreEnabled(conf)) {
225      return null;
226    }
227    User user = loginClientAsService(conf);
228    return getAuthRenewalChore(user.getUGI(), conf);
229  }
230
231  private static Stoppable createDummyStoppable() {
232    return new Stoppable() {
233      private volatile boolean isStopped = false;
234
235      @Override
236      public void stop(String why) {
237        isStopped = true;
238      }
239
240      @Override
241      public boolean isStopped() {
242        return isStopped;
243      }
244    };
245  }
246
247  /**
248   * Returns whether or not the given name should be interpreted as a group principal. Currently
249   * this simply checks if the name starts with the special group prefix character ("@").
250   */
251  @InterfaceAudience.Private
252  public static boolean isGroupPrincipal(String name) {
253    return name != null && name.startsWith(GROUP_PREFIX);
254  }
255
256  /**
257   * Returns the actual name for a group principal (stripped of the group prefix).
258   */
259  @InterfaceAudience.Private
260  public static String getGroupName(String aclKey) {
261    if (!isGroupPrincipal(aclKey)) {
262      return aclKey;
263    }
264
265    return aclKey.substring(GROUP_PREFIX.length());
266  }
267
268  /**
269   * Returns the group entry with the group prefix for a group principal.
270   */
271  @InterfaceAudience.Private
272  public static String toGroupEntry(String name) {
273    return GROUP_PREFIX + name;
274  }
275
276  /**
277   * Returns true if the chore to automatically renew Kerberos tickets (from keytabs) should be
278   * started. The default is true.
279   */
280  static boolean isAuthRenewalChoreEnabled(Configuration conf) {
281    return conf.getBoolean(HBASE_CLIENT_AUTOMATIC_KEYTAB_RENEWAL_KEY,
282      HBASE_CLIENT_AUTOMATIC_KEYTAB_RENEWAL_DEFAULT);
283  }
284}