Google Cloud Platform (Cloud KMS, IAM API, & AppEngine App Identity API) jwt-go implementations
Google Cloud KMS now supports signatures and support has been added to gcp-jwt-go!
- Switched to new iamcredentials API - this no longer allows signBlob to be used on the service account the client is authenticated as.
IAMConfig.OAuth2HTTPClientis deprecrated and unused - UseIAMConfig.IAMClientinstead.IAMConfig.ProjectIDis deprecrated and unused. The API will infer the project from the service account name.
- Dropping support for AppEngine Go 1.9 environment (last version with AppEngine App Identity support will be for Go 1.11)
- KMSConfig no longer takes an optional HTTP Client, but rather the kms gRPC based client
- Middleware will now return a 401 response for unauthenticated requests (previously was returning a 403 response)
- Package name changed from gcp_jwt to gcpjwt
- Refactoring of code (including exported functions/structs)
- Certificate caching is now opt-in vs opt-out
- Helper jwt.Keyfunc implementations introduced
- Expected key for sign/verify changed
- KeyID() helper functions
- Basic oauth2.TokenSource and http middleware sub packages for basic service-to-service authentication (currently only supports IAM Api)
To continue using the older version, please import as follows: import "gopkg.in/someone1/gcp-jwt-go.v1"
gcp-jwt-go has basic implementations of using Google Cloud KMS, Google IAM API (both signJwt and signBlob), and the App Identity API from AppEngine Standard on Google Cloud Platform to sign JWT tokens using the dgrijalva/jwt-go package. Should work across virtually all environments, on or off of Google's Cloud Platform.
Please read the documentation at https://pkg.go.dev/github.com/someone1/gcp-jwt-go/v2
There are many tradeoffs which the various signing mechanism available from Google's Cloud Platform. Below you will find a chart of performance for the different algorithms and APIs. Here are some overall takeaways:
- AppEngine: The fastest option available though limited in that it can only sign on behalf of the default service account and only runs on AppEngine Standard. Keys are auto-rotated, limited to RS256.
- IAM Api: Flexible in that you can sign on behalf of various service accounts (see Tips below), runs on any platform, keys are auto-rotated, but is the slowest option available and limited to RS256.
- Cloud KMS: Fast (enough?), highly flexible (come up with your own keys/usage/algorithm/etc.), runs on any platform, however key rotation is left to the user.
note: all latency numbers are ordered as (50th %ile, 95th %ile, 99th %ile). Tests were run on a F1 AppEngine Standard instance in the us-central region. All Cloud KMS keys are set to global.
| Signer | Signature Length | Sign Latency | Samples |
|---|---|---|---|
| AppEngine | 342 | 9.14 ms, 17.56 ms, 79.15 ms | 100 |
| IAMBlob | 342 | 198.37 ms, 217.42 ms, 244.91 ms | 100 |
| IAMJWT | 342 | 109.03 ms, 208.46 ms, 212.65 ms | 100 |
| KMSES256 | 86 | 31.57 ms, 44.09 ms, 44.54 ms | 50 |
| KMSES384 | 128 | 34.67 ms, 51.16 ms, 59.48 ms | 50 |
| KMSPS256 (2048) | 342 | 38.20 ms, 57.75 ms, 70.47 ms | 50 |
| KMSPS256 (3072) | 512 | 42.77 ms, 58.24 ms, 62.86 ms | 50 |
| KMSPS256 (4096) | 683 | 52.02 ms, 64.70 ms, 92.15 ms | 50 |
| KMSRS256 (2048) | 342 | 37.94 ms, 61.94 ms, 77.33 ms | 50 |
| KMSRS256 (3072) | 512 | 39.85 ms, 50.52 ms, 56.17 ms | 50 |
| KMSRS256 (4096) | 683 | 50.19 ms, 68.48 ms, 86.02 ms | 50 |
| Verifier | Cache | Verify Latency | Samples |
|---|---|---|---|
| AppEngineVerify | false | 6.42 ms, 9.33 ms, 10.86 ms | 50 |
| AppEngineVerify | true | 0.87 ms, 1.05 ms, 25.03 ms | 50 |
| IAMVerify | false | 12.52 ms, 21.45 ms, 30.63 ms | 100 |
| IAMVerify | true | 0.86 ms, 1.01 ms, 53.19 ms | 100 |
| KMSVerify (2048-PS256) | always | 0.88 ms, 1.01 ms, 32.15 ms | 50 |
| KMSVerify (2048-RS256) | always | 0.93 ms, 1.11 ms, 19.96 ms | 50 |
| KMSVerify (3072-PS256) | always | 1.53 ms, 1.71 ms, 43.35 ms | 50 |
| KMSVerify (3072-RS256) | always | 1.61 ms, 2.11 ms, 42.39 ms | 50 |
| KMSVerify (4096-PS256) | always | 2.94 ms, 66.88 ms, 71.60 ms | 50 |
| KMSVerify (4096-RS256) | always | 2.70 ms, 55.25 ms, 72.34 ms | 50 |
| KMSVerify (ES256) | always | 0.15 ms, 0.20 ms, 0.29 ms | 50 |
| KMSVerify (ES384) | always | 181.21 ms, 193.25 ms, 195.08 ms | 50 |
Where cache=false is where we get the most value from these numbers as it shows the time to fetch/parse public certificates, the other cases are just the time to use a cached certificate to validate the JWT.
- If using the IAM API - create a separate service account to sign on behalf of for your projects unless you NEED to use your default service account (e.g. the AppEngine service account). This way you can limit the scope of access for any leaked credentials. You'll have to grant the
roles/iam.serviceAccountTokenCreatorrole to any user/group/serviceaccount you want to be able to sign on behalf of the new service account (resource:projects/-/serviceAccounts/<serviceaccount>). For example, create an api-signer service account, do NOT furnish any keys for it, grant your AppEngine/GCE/etc. default service account the proper role for that serviceAccount, and use the api-signer@... service account address in your configuration. For example, to setup to use an AppEngine service account to sign on behalf of a service account api-signer (be sure toexport PROJECT_ID=your-project-idbefore executing the below):
# First, create the api-signer service account
gcloud beta iam service-accounts create api-signer --description="Tokens must be signed by this service account in order to authenticate to the API" --display-name="API Signer" --project=$PROJECT_ID
# Grant the AppEngine service account proper permissions to sign tokens on behalf of the service account we just created
gcloud beta iam service-accounts add-iam-policy-binding api-signer@$PROJECT_ID.iam.gserviceaccount.com --member=serviceAccount:$PROJECT_ID@appspot.gserviceaccount.com --role=roles/iam.serviceAccountTokenCreator --project=$PROJECT_IDUnderstand this process by reading this article.
- If using outside of GCP, be sure to put credentials for an account that can access the service account for signing tokens in a well known location:
- A JSON file whose path is specified by the GOOGLE_APPLICATION_CREDENTIALS environment variable.
- A JSON file in a location known to the gcloud command-line tool. On Windows, this is %APPDATA%/gcloud/application_default_credentials.json. On other systems, $HOME/.config/gcloud/application_default_credentials.json.