1# -*- coding: utf-8 -*-
2# Copyright 2013 Google Inc. All Rights Reserved.
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8#     http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15"""Additional help about types of credentials and authentication."""
16
17from __future__ import absolute_import
18
19from gslib.help_provider import HelpProvider
20
21_DETAILED_HELP_TEXT = ("""
22<B>OVERVIEW</B>
23  gsutil currently supports several types of credentials/authentication, as
24  well as the ability to access public data anonymously (see "gsutil help anon"
25  for more on anonymous access). Each of these type of credentials is discussed
26  in more detail below, along with information about configuring and using
27  credentials via either the Cloud SDK or standalone installations of gsutil.
28
29
30<B>Configuring/Using Credentials via Cloud SDK Distribution of gsutil</B>
31  When gsutil is installed/used via the Cloud SDK ("gcloud"), credentials are
32  stored by Cloud SDK in a non-user-editable file located under
33  ~/.config/gcloud (any manipulation of credentials should be done via the
34  gcloud auth command). If you need to set up multiple credentials (e.g., one
35  for an individual user account and a second for a service account), the
36  gcloud auth command manages the credentials for you, and you switch between
37  credentials using the gcloud auth command as well (for more details see
38  https://developers.google.com/cloud/sdk/gcloud/#gcloud.auth).
39
40  Once credentials have been configured via gcloud auth, those credentials will
41  be used regardless of whether the user has any boto configuration files (which
42  are located at ~/.boto unless a different path is specified in the BOTO_CONFIG
43  environment variable). However, gsutil will still look for credentials in the
44  boto config file if a type of credential is needed that's not stored in the
45  gcloud credential store (e.g., an HMAC credential for an S3 account).
46
47
48<B>Configuring/Using Credentials via Standalone gsutil Distribution</B>
49  If you installed a standalone distribution of gsutil (downloaded from
50  https://pub.storage.googleapis.com/gsutil.tar.gz,
51  https://pub.storage.googleapis.com/gsutil.zip, or PyPi), credentials are
52  configured using the gsutil config command, and are stored in the
53  user-editable boto config file (located at ~/.boto unless a different path is
54  specified in the BOTO_CONFIG environment). In this case if you want to set up
55  multiple credentials (e.g., one for an individual user account and a second
56  for a service account), you run gsutil config once for each credential, and
57  save each of the generated boto config files (e.g., renaming one to
58  ~/.boto_user_account and the second to ~/.boto_service_account), and you
59  switch between the credentials using the BOTO_CONFIG environment variable
60  (e.g., by running BOTO_CONFIG=~/.boto_user_account gsutil ls).
61
62  Note that when using the standalone version of gsutil with the JSON API you
63  can configure at most one of the following types of GCS credentials in a
64  single boto config file: OAuth2 User Account, OAuth2 Service Account. In
65  addition to these, you may also have S3 HMAC credentials (necessary for using
66  s3:// URLs) and GCE Internal Service Account credentials. GCE Internal Service
67  Account credentials are used only when OAuth2 credentials are not present.
68
69
70<B>SUPPORTED CREDENTIAL TYPES</B>
71  gsutil supports several types of credentials (the specific subset depends on
72  which distribution of gsutil you are using; see above discussion).
73
74  OAuth2 User Account:
75    This is the preferred type of credentials for authenticating requests on
76    behalf of a specific user (which is probably the most common use of gsutil).
77    This is the default type of credential that will be created when you run
78    "gsutil config".
79    For more details about OAuth2 authentication, see:
80    https://developers.google.com/accounts/docs/OAuth2#scenarios
81
82  HMAC:
83    This type of credential can be used by programs that are implemented using
84    HMAC authentication, which is an authentication mechanism supported by
85    certain other cloud storage service providers. This type of credential can
86    also be used for interactive use when moving data to/from service providers
87    that support HMAC credentials. This is the type of credential that will be
88    created when you run "gsutil config -a".
89
90    Note that it's possible to set up HMAC credentials for both Google Cloud
91    Storage and another service provider; or to set up OAuth2 user account
92    credentials for Google Cloud Storage and HMAC credentials for another
93    service provider. To do so, after you run the gsutil config command, you
94    can edit the generated ~/.boto config file and look for comments for where
95    other credentials can be added.
96
97    For more details about HMAC authentication, see:
98      https://developers.google.com/storage/docs/reference/v1/getting-startedv1#keys
99
100  OAuth2 Service Account:
101    This is the preferred type of credential to use when authenticating on
102    behalf of a service or application (as opposed to a user). For example, if
103    you will run gsutil out of a nightly cron job to upload/download data,
104    using a service account allows the cron job not to depend on credentials of
105    an individual employee at your company. This is the type of credential that
106    will be configured when you run "gsutil config -e".
107
108    It is important to note that a service account is considered an Editor by
109    default for the purposes of API access, rather than an Owner. In particular,
110    the fact that Editors have OWNER access in the default object and
111    bucket ACLs, but the canned ACL options remove OWNER access from
112    Editors, can lead to unexpected results. The solution to this problem is to
113    add the email address for your service account as a project editor. To find
114    the email address, visit the
115    `Google Developers Console <https://cloud.google.com/console#/project>`_,
116    click on the project you're using, click "APIs & auth", and click
117    "Credentials".
118
119    To create a service account, visit the Google Developers Console and then:
120
121       - Click "APIs & auth" in the left sidebar.
122
123       - Click "Credentials".
124
125       - Click "Create New Client ID".
126
127       - Select "Service Account" as your application type.
128
129       - Save the JSON private key or the .p12 private key and password
130         provided.
131
132    For further information about account roles, see:
133      https://developers.google.com/console/help/#DifferentRoles
134
135    For more details about OAuth2 service accounts, see:
136      https://developers.google.com/accounts/docs/OAuth2ServiceAccount
137
138  GCE Internal Service Account:
139    This is the type of service account used for accounts hosted by App Engine
140    or GCE. Such credentials are created automatically for you on GCE when you
141    run the gcutil addinstance command with the --service_account flag.
142
143    For more details about GCE service accounts, see:
144      https://developers.google.com/compute/docs/authentication;
145
146    For more details about App Engine service accounts, see:
147      https://developers.google.com/appengine/docs/python/appidentity/overview
148""")
149
150
151class CommandOptions(HelpProvider):
152  """Additional help about types of credentials and authentication."""
153
154  # Help specification. See help_provider.py for documentation.
155  help_spec = HelpProvider.HelpSpec(
156      help_name='creds',
157      help_name_aliases=['credentials', 'authentication', 'auth', 'gcloud'],
158      help_type='additional_help',
159      help_one_line_summary='Credential Types Supporting Various Use Cases',
160      help_text=_DETAILED_HELP_TEXT,
161      subcommand_help_text={},
162  )
163