Git Product home page Git Product logo

googlesource-auth-tools's Introduction

Git auth helpers for googlesource.com / source.developers.google.com

This is a collection of tools / libraries for making a request to googlesource.com and source.developers.google.com with an OAuth2 tokens.

This comes with three tools and a library for programmatic access.

  • git-credential-googlesource: A gitcredentials helper
  • googlesource-askpass: A GIT_ASKPASS helper
  • googlesource-cookieauth: A tool to create a gitcookie file
  • credentials: A library for creating a TokenSource

These tools work without any configuration by default as long as you have gcloud installed. For choosing which one to use, see the usage guide below.

This is not an official Google product (i.e. a 20% project).

Install

Install like other Go tools.

Usage

There are two things to consider for setting this up.

  1. Which account to use and how to obtain the credentials
  2. How to run these auth helpers

Which account to use and how to obtain the credentials

  • Use on a personal machine

    If you use these tools on your workstation, which means that you use these tools for non-production jobs, you can just use your Google Account. Install Google Cloud SDK, and set up your account with gcloud auth login. These tools automatically use the default account. If you have multiple accounts, and you want to use different accounts for different repositories, see the configurations section below.

  • Use on GCE

    If you use these tools on GCE, you must use a service account. You can specify a service account for each GCE instance when you start one, and the machine can get a credential of that account from a special IP address that is internal to GCE. Use https://www.googleapis.com/auth/cloud-platform as the OAuth2 scope. If you have gcloud installed in the machine, you don't need further configuration. If you do not want to install gcloud, you can specify application-default for google.account in git-config. See the configurations section below.

  • Use on an on-premise servers

    If you use these tools on on-premise machines, you must use a service account as well. In Google Cloud Platform Console, you can create a service account and you can download a credential JSON file for the account. You can distribute this credential file to your on-premise machines and specify the file path in GOOGLE_APPLICATION_CREDENTIALS. Specify application-default for google.account in your .gitconfig. See Application Default Credentials for details.

How to run these auth helpers

  • Run googlesource-cookieauth as a cron job

    If you don't mind running a small background cron job on your machine once per hour, running googlesource-cookieauth as a cron job will be most convenient and reliable option.

    Setting up a cron job depends on your operating system. Explaining how to set up one is beyond this help. For Linux, you might be able to use systemd or crontab. For Mac OS X, you might be able to use launchd or crontab. For Windows, you might be able to use Task Scheduler.

  • Run googlesource-cookieauth right before running Git commands

    The OAuth2 tokens written by googlesource-cookieauth are usually valid for an hour. If you need to access Git repositories in a CI/CD pipeline and you cannot modify the worker image for running a cron job, you can run this command once at the beginning.

  • Use git-credential-googlesource

    If you install git-credential-googlesource to the $PATH, you can specify googlesource to credential.helper in git-config. You can specify the full path as well.

    Due to the nature of git-credential mechanism, this doesn't work well for googlesource.com repositories. This is because Git invokes credential helpers only when it sees 401 Unauthorized. For public repositories, you can always access them and Git won't use the credential. You can change the repository URL path with /a/ for force authentication. For example, you can use https://gerrit.googlesource.com/a/gerrit instead of https://gerrit.googlesource.com/gerrit. The googlesource.com server returns 401 Unauthorized if the request is not authenticated.

    In Mac OS X, the operating system specifies git-credential-osxkeychain as a system default credential helper. This credential helper caches the OAuth2 access token returned by git-credential-googlesource. Since OAuth2 access tokens are valid only for a short period, the cached credential will become invalid quickly. This causes many confusions and it's better to disable it if you use git-credential-googlesource. (A patch for disabling cache is sent to git upstream https://public-inbox.org/git/[email protected]/T/#u)

  • Use googlesource-askpass

    You can specify the path to googlesource-askpass to GIT_ASKPASS environment variable or core.askPass in git-config.

    The same restriction applies for googlesource-askpass, and this doesn't work well for googlesource.com repositories.

Configurations

Most of the configurations can be done via git-config. Consult the git manual pages on how to configure the options.

  • google.account

    An account to be used. This can take one of the following values. If empty, it defaults to gcloud.

    • gcloud

      Use the default account of gcloud.

    • application-default

      Use the applicaiton default credentials.

    • Google Account emails

      Get an access token by using gcloud auth print-access-token EMAIL. The account specified here must be registered in gcloud by using gcloud auth login

    • Service account emails (SERVICE_ACCOUNT@YOUR_PROJECT.iam.gserviceaccount.com)

      Start from the application default credentials, use IAM Service Account Credentials API to obtain the specified service account credentials. The account used for the application default service account must have iam.serviceAccounts.getAccessToken for the account specified here.

      In a rare situation where you need a multi-hop delegation, you can specify a list of delegated service account emails in google.serviceAccountDelegateEmails.

  • google.scopes

    Comma separated values of OAuth2 scopes. If empty, it defaults to https://www.googleapis.com/auth/cloud-platform.

    This config is usually not effective unless you use service account emails for google.account.

  • google.allowHTTPForCredentialHelper

    A boolean value that is used only for git-credential-googlesource. If true, it allows returning a credential for HTTP URLs. Usually this is not needed, but this comes handy if you have an HTTP proxy.

  • google.cookieFile

    A file path to a cookie file. googlesource-cookieauth writes Netscape cookies to this file. If you specify "-", it writes to stdout. If empty, it defaults to $HOME/.git-credential-cache/googlesource-cookieauth-cookie.

  • google.gcloudPath

    A file path to gcloud. If empty, it defaults to the one in the $PATH.

All configurations above, except google.cookieFile, can be scoped to a URL by using google.<url>.* syntax. For example, if you want to use your Gmail address by default, and use your chromium.org account only for chromium.googlesource.com, you can write the following .gitconfig.

[google]
  account = [email protected]
[google "https://chromium.googlesource.com"]
  account = [email protected]

For googlesource-cookieauth, you can specify google.cookieFile via a command line flag, too. Specify a file path via --output. The commandline flag takes a precedence over git-config.

googlesource-auth-tools's People

Contributors

draftcode avatar josieang avatar wlynch avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

googlesource-auth-tools's Issues

Security Policy violation Binary Artifacts

This issue was automatically created by Allstar.

Security Policy Violation
Project is out of compliance with Binary Artifacts policy: binaries present in source code

Rule Description
Binary Artifacts are an increased security risk in your repository. Binary artifacts cannot be reviewed, allowing the introduction of possibly obsolete or maliciously subverted executables. For more information see the Security Scorecards Documentation for Binary Artifacts.

Remediation Steps
To remediate, remove the generated executable artifacts from the repository.

Artifacts Found

  • googlesource-cookieauth/googlesource-cookieauth

Additional Information
This policy is drawn from Security Scorecards, which is a tool that scores a project's adherence to security best practices. You may wish to run a Scorecards scan directly on this repository for more details.


Allstar has been installed on all Google managed GitHub orgs. Policies are gradually being rolled out and enforced by the GOSST and OSPO teams. Learn more at http://go/allstar

This issue will auto resolve when the policy is in compliance.

Issue created by Allstar. See https://github.com/ossf/allstar/ for more information. For questions specific to the repository, please contact the owner or maintainer.

Incomplete gcloud print-access-token error

Trying to run the following in a docker container:

FROM gcr.io/google.com/cloudsdktool/cloud-sdk
ENTRYPOINT ["bash"]
WORKDIR /app
RUN git clone https://github.com/google/googlesource-auth-tools.git githelper
RUN chmod +x githelper/googlesource-cookieauth/googlesource-cookieauth
RUN githelper/googlesource-cookieauth/googlesource-cookieauth

and gets the following error:

Cannot write cookies: cannot create a token for https://googlesource.com: credentials: cannot get a token: credentials: incomplete gcloud print-access-token result: &{ {}}

Any guidance as to what I'm doing wrong?

The context is:

  • We have a private repo in golang, hosted on Google Source Repository (GSR)
  • The go mod download uses git in the background
  • and therefore requires the credential helper to connect to GSR
  • I was hoping one could solve this with the above google-auth-tools library
  • The above runs as part of a Google Cloud Build step (which has --network=cloudbuild set and therefore access to default credentials.)

[Docs] Possible outdated documentation

We have identified 1 possible instance of outdated documentation:

About

This is part of a research project that aims to automatically detect outdated documentation in GitHub repositories. We are evaluating the validity of our approach by identifying instances of outdated documentation in real-world projects.

We hope that this research will be a step towards keeping documentation up-to-date. If this has been helpful, consider updating the documentation to keep it in sync with the source code. If this has not been helpful, consider updating this issue with an explanation, so that we can improve our approach. Thanks!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.