oidc

Overview ¶

Package oidc provides an implementation of the snowplow.TokenSource interface, allowing snowplow.Emitter to authenticate with the collector endpoint using the OIDC flow.

When executed within the supported cloud provider (AWS or Google Cloud), it will use cloud provider's API to generate an ID Token that the collector endpoint can use to authenticate the request, following the OIDC standard.

For that to work, the instance where this code will be executed needs to be properly prepared.

AWS setup ¶

1. Outbound Identity Federation must be explicitly enabled in the AWS Account's IAM settings.

2. We need to create a specific permissions policy that allows talking to STS GetWebIdentityToken endpoint.

3. The role that is assigned to the instance where the code will be running must include the above permission policy.

Policy definition:

 {
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": "sts:GetWebIdentityToken",
			"Resource": "*"
		}
	]
}

AWS ID Token validation ¶

When properly executed in AWS, request to Snowplow Collector will be enhanced with a JWT used as the Authorization Bearer token.

First step of validation should be checking if it matches the Issued At (`iat`) and Expires At (`exp`) claims. Next, we should extract:

• Key ID (`kid`) from the JWT header,
• Issuer address (`iss`) from the JWT payload.

`iss` in AWS will point to a service that's unique for every AWS account where the request originated from. The URL should look like `https://some-uuid-here.tokens.sts.global.api.aws`. Therefore it's important that the authentication service on the collector side does extract the Issuer information and uses that to discover JWKS (JSON Web Key Set). There is no way to hardcode that information.

Once the Issuer is extracted, authentication service on the collector side can use the OIDC discovery URL to find the JWKS: `https://some-uuid-here.tokens.sts.global.api.aws/.well-known/openid-configuration`. This URL will return a JSON object with JWKS URL at the `jwks_uri` key.

From the JWKS we can next receive the public key by matching with `kid` retrieved from JWT header. Having the public key we can then validate signature of the JWT.

After validating JWT integrity, we can extract other claims to check if the token is authorized to talk with snowplow collector:

• Audience (`aud`) - which snowplow.Emitter will set to the FQDN of the collector itself.
• Subject (`sub`) - which should be the ARN of the role attached to the instance, scoped to the AWS account. This may be useful if we know that a single role from a single AWS account is expected to talk with snowplow collector.
• Organization ID (`"https://sts.amazonaws.com/".org_id`) - which should be the ID of the AWS Organization the AWS account belongs to. This is useful if many roles from, potentially, many AWS Accounts but within the same AWS Organization are going to be talking with snowplow collector.

Google Cloud setup ¶

1. Service Account that is attached to the instance where the code will be executed, must have the `iam.serviceAccount.getOpenIdToken` permission enabled.

2. When attaching the Service Account to the instance, you must enable the https://www.googleapis.com/auth/cloud-platform token scope.

Google Cloud ID Token validation ¶

When properly executed in Google Cloud, request to Snowplow Collector will be enhanced with a JWT used as the Authorization Bearer token.

First step of validation should be checking if it matches the Issued At (`iat`) and Expires At (`exp`) claims. Next, we should extract:

• Key ID (`kid`) from the JWT header,
• Issuer address (`iss`) from the JWT payload.

`iss` in Google Cloud should always be set to https://accounts.google.com. Authentication service on the collector side can next use the OIDC discovery URL to find the JWKS (JSON Web Key Set): `https://accounts.google.com/.well-known/openid-configuration`. This URL will return a JSON object with JWKS URL at the `jwks_uri` key.

From the JWKS we can next receive the public key by matching with `kid` retrieved from JWT header. Having the public key we can then validate signature of the JWT.

After validating JWT integrity, we can extract other claims to check if the token is authorized to talk with snowplow collector:

• Audience (`aud`) - which snowplow.Emitter will set to the FQDN of the collector itself.
• Subject (`sub`) - which should be the numerical ID of the Service Account for which the token was generated. This may be useful if we know that a single service account is expected to talk with snowplow collector.
• Organization Number (`google.organization_number`) - which should be the numerical ID of the Google Cloud Organization to which the service account belongs. This is useful if many service accounts from, potentially, many Google Cloud Projects but within the same Google Cloud Organization are going to be talking with snowplow collector.

Usage ¶

To use Source, create the object and attach it to snowplow.Emitter using the snowplow.WithTokenSource() function:

ts := oidc.NewSource()

emitter, err := snowplow.NewEmitter(
	collectorURL,
	snowplow.WithTokenSource(ts),
)

If you want to configure Source, use the available Option functions when creating the Source object:

  ts := oidc.NewSource(
    oidc.WithSkipIfUnsupportedCloud(true) // to quietly ignore header enhancing if not running in supported cloud
  )

	emitter, err := snowplow.NewEmitter(
		collectorURL,
		snowplow.WithTokenSource(ts),
	)