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 17 from __future__ import absolute_import 18 19 from 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 151 class 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
