cloudidentity

README

Cloud Identity Utility

This library provides mechanisms for dealing with identities in a cloud environment.

Installing the library dependency

go get -u github.com/qvik/go-cloud-identity

OpenID Connect ID Tokens for server-to-server authentication

This library provides functionality for acquiring an identity token using Google's GCE metadata server and verifying it. It can be used eg. for facilitating authentication and authorization in service-to-service calls in Google Cloud Platform (GCP) environments.

AWS etc. support added when one is needed.

The usual flow is:

1. The calling service creates and ID token with specified AUD value to match the service to be called.
2. The calling service incorporates this token in the method call -- typically, in a HTTP request, in an Authorization: Bearer header
3. The called service extracts the token from the call
4. The called service verifies the token against its expected AUD value.

Acquiring an identity token

Retrieval of the identity token from a GCE metadata server is available for Google Compute Engine, Google AppEngine standard second generation and flexible runtimes.

To acquire an identity token:

import (
    "github.com/qvik/go-cloud-identity/google"
    "log"
)

aud := "https://myapp/myservice" // Free-form string
identity, err := google.FetchMetadataIDToken(aud, "")
if err != nil {
    log.Fatalf("got error: %v", err)
    return
}

Verifying an identity token

Verification of the identity token is available on any platform. It is highly recommended to cache the IDTokenVerifier object for performance reasons.

To verify an identity token:

import (
    "github.com/qvik/go-cloud-identity/google"
    "log"
    "context"
)

ctx := context.Background()
verifier := google.NewVerifier(ctx, aud)
if _, err := verifier.VerifyIDToken(ctx, identity); err != nil {
    log.Fatalf("failed to verify token: %v", err)
}

Getting a signed Google Cloud Storage URL

To get a signed GCS url:

import (
    "github.com/qvik/go-cloud-identity/google"
    "cloud.google.com/go/compute/metadata"
)

saEmail, _ := metadata.Email(google.DefaultAccount)
name := "path/to/my/file"
signBytes := func(payload []byte) ([]byte, error) {
  return google.SignBytes(payload, "", saEmail)
}
expires := time.Now().Add(time.Minute * 60)
signedURL, _ := google.GetSignedURL("bucket1", name, saEmail, "GET",
   expires, signBytes)

License

This library is released under the MIT license.

Contributing

Contributions to this library are welcomed. Any contributions have to meet the following criteria:

• Meaningfulness. Discuss whether what you are about to contribute indeed belongs to this library in the first place before submitting a pull request.
• Code style. Use gofmt and golint and you cannot go wrong with this. Generally do not exceed a line length of 80 characters.
• Testing. Try and include tests for your code.

Contact

Any questions? Contact matti@qvik.fi.

Documentation

Overview

Package cloudidentity provides functionality for dealing with software identities in cloud environments, such as OpenID Connect ID token acquirement and authorization.

Index

• type IDTokenVerifier
  • func NewVerifier(ctx context.Context, issuerURL, aud string) (*IDTokenVerifier, error)
  • func (v *IDTokenVerifier) VerifyIDToken(ctx context.Context, token string) (*oidc.IDToken, error)

Types

type IDTokenVerifier

type IDTokenVerifier struct {
	// contains filtered or unexported fields
}

IDTokenVerifier provides a method for verifying an OpenID Connect ID token. Internally it caches the public key set used for the verification so that the operation is as efficient as possible.

func NewVerifier

func NewVerifier(ctx context.Context,
	issuerURL, aud string) (*IDTokenVerifier, error)

NewVerifier creates a new IDTokenVerifier that internally caches the remote key set used for ID token verification.

func (*IDTokenVerifier) VerifyIDToken

func (v *IDTokenVerifier) VerifyIDToken(ctx context.Context,
	token string) (*oidc.IDToken, error)

VerifyIDToken verifies an ID token. The parameter token is the JWT string. Returns IDToken and nil error when verify succeeds.