HTTP/2’s multiplexing and binary framing make it significantly more efficient than HTTP/1.1, reducing latency and improving throughput. Connect RPC lets you harness these benefits while maintaining broad client compatibility for services that can’t yet support HTTP/2.

Connect RPC can be used to build both internal and external APIs, powering frontends, mobile apps, CLIs, agents and more. See the list of supported languages.

Core Features

Connect RPC provides a number of features out of the box, such as:

• Interceptors which make it easy to extend Connect RPC and are used to add authentication, logging, metrics, tracing and retries.
• Serialization & compression, with pluggable serializers, and support for asymmetric compression reducing the amount of data that needs to be transmitted, or received.
• Error handling, with a standard error format, with support for custom error codes to allow for more granular error handling.
• Observability, with in built support for OpenTelemetry enabling you to easily add tracing, or metrics to your APIs.
• Streaming, which provides a very efficient way to push or pull data without polling.
• Schemas, which enable you to define and validate your API schemas, and generate code from them.
• Code generation for Go, TypeScript, Kotlin, Swift and Java.

Ecosystem

In addition to these features, Connect RPC is built on top of the Buf ecosystem, which offers notable benefits:

• Connect RPC joins CNCF, entering the cloud-native ecosystem, which is great for the long term sustainability of the project.
• Buf Schema Registry, which is a great tool for managing, sharing and versioning your API schemas.
• Buf CLI, a handy all in one tool for managing your APIs, generating code and linting.

Recommended Interceptor Packages

Some handy Go packages that provide pre-built Connect RPC interceptors worth exploring or using as a starting point:

• authn-go, provides a rebuilt authentication middleware library for Go. It works with any authentication scheme (including HTTP basic authentication, cookies, bearer tokens, and mutual TLS).
• validate-go provides a Connect RPC interceptor that takes the tedium out of data validation. This package is powered by protovalidate and the Common Expression Language.
• rpclog provides a structured logging interceptor for Connect RPC with support for both unary and streaming RPCs.

Summary

1. Connect RPC provides a paved and well maintained path to building gRPC compatible APIs, while maintaining compatibility for HTTP/1.1 clients. This is invaluable for product teams that need to support multiple client types without building custom compatibility layers.

2. Using a mature library like Connect RPC, you get to benefit from all the prebuilt integrations, and the added capabilities of the Buf ecosystem. This makes publishing and consuming APIs a breeze.

3. Protobuf schemas, high performance serialisation and compression ensure you get robust and efficient APIs.

Conclusion

Connect RPC makes it easy to build high-performance, robust APIs with gRPC compatibility, while avoiding the complexity of building and maintaining custom compatibility layers.

In this model the CI provider acts as an identity provider, issuing tokens to the CI runner/agent which include a set of claims identifying the owner, pipeline, workflow and job that is being executed. This is then used to authenticate with the cloud service, and access the resources that the pipeline, workflow and job require.

In simple terms, this is a form of trust delegation, where the CI provider is trusted by the cloud service to issue tokens on behalf of the owner, pipeline, workflow and job.

How OIDC Works

The OIDC trust delegation flow is as follows:

sequenceDiagram
    participant CI as CI Provider<br/>(Identity Provider)
    participant Runner as CI Runner/Agent
    participant Cloud as Cloud Service<br/>(AWS/Azure/GCP)

    Note over CI,Cloud: OIDC Trust Delegation Flow

    CI->>Runner: Issue OIDC token with claims<br/>(pipeline, workflow, job)
    Runner->>Cloud: Request access with OIDC token
    Cloud->>Cloud: Verify token signature<br/>and validate claims
    Cloud->>Runner: Grant temporary credentials
    Runner->>Cloud: Access resources with credentials

    Note over CI,Cloud: Trust established via OIDC configuration

There are a few things to note:

• When using OIDC, the runner doesn’t need to be registered with the cloud service; it is granted access via the OIDC token.
• The OIDC token is cryptographically signed by the CI provider, and the cloud service verifies the signature to ensure the token is valid.
• In this model all three parties (CI provider, runner, and cloud service) are trusted to issue and verify tokens.

Limiting Cloud Access to the Agent/Runner

To ensure the CI provider can’t access the cloud service directly, you can add conditions which ensure only the runner/agent is allowed to access the cloud resources.

On top of this cloud providers such as AWS have conditions which can restrict access to a specific AWS network resource, such as a VPC. I recommend familiarizing yourself with the documentation for your cloud provider to understand how to lock down access to the runner/agent.

Benefits of OIDC

The reasons this is useful are:

• It provides a more secure and flexible approach to authentication and authorization
• It limits the scope of the token to the specific pipeline, workflow, and job
• It is tied to the lifecycle of the pipeline, workflow, and job, which means the token is limited to the duration of that execution
• It is more flexible than using machine identity for CI runners/agents as it allows for more granular control over the permissions granted to the runner/agent

Ephemeral Runners/Agents

Ephemeral runners/agents are short lived, single job, or single workflow runners/agents which are created before the workflow, or job is started. They provide a more secure and flexible approach to job execution as there is no need to worry about these environments being tainted by previous jobs or workflows.

When paired with OIDC these environments provide an extra layer of security as they are destroyed after the job or workflow is complete, further reducing the risk of cross job or workflow access.

Summary

So in summary, OIDC provides a more secure and flexible approach to access management for CI projects, and it is particularly useful when paired with ephemeral runners/agents.

The biggest advantage of this approach is that it allows engineers to focus on the access required by the pipeline, workflow, and job, rather than having to manage machine identities and permissions for each runner/agent.

One of the interesting things about this approach is that you’re not limited to using OIDC just with cloud providers; you can use it with your own services as well. By using OIDC libraries such as github.com/coreos/go-oidc, you can implement APIs which can use the identity of CI pipelines, workflows, and jobs. An example of this is Using OIDC With HashiCorp Vault and GitHub Actions.

Links

• OIDC for Buildkite
• OIDC for GitHub Actions
• OIDC for GitLab

When setting up an applications authentication I try to keep in mind a few goals:

1. Keep my users data as safe as possible.
2. Try and find something which is standards based, or supports integrating with standard protocols such as openid, oauth2 and SAML.
3. Evaluate the authentication flows I need and avoid increasing scope and risk.
4. Try to use a service to start with, or secondarily, an opensource project with a good security process and a healthy community.
5. Limit any custom development to extensions, rather than throwing out the baby with the bath water.

As you can probably tell, my primary goal is to keep authentication out of my applications, I really don’t have the time or inclination to manage a handcrafted authentication solution.

What does AWS Cognito provide out of the box?

Lets look at what we get out of the box:

• Storing and protecting your users data with features such as Secure Remote Password Protocol (SRP).
• Signing up for an account with email / sms verification
• Signing in, optionally with Multi Factor Authentication (MFA)
• Password change and recovery
• A number of triggers which can be used to extend the product

What is great about Cognito?

Where AWS Cognito really shines is:

• Out of the box compliance to standards such as SOC and PCI
• Integration with a range of platform identity providers, such as Google, Apple and Amazon
• Support for integration with identity providers (IdPs) using OpenID and SAML.
• Really easy to integrate into your application using libraries such as AmplifyJS.
• AWS is managing it for a minimal cost

What is not so great about Cognito?

Where AWS Cognito can be a challenge for developers:

• Can be difficult to setup, and understand some of the settings which can only be updated during creation, changing these requires you to delete and recreate your pool.
• Per account quotas on API calls
• A lack of search
• No inbuilt to backup and restore the user data in your pool

So how do we address some of these challenges, while still getting the value provided and being able to capitalise on it’s security and compliance features.

What is the best way to setup Cognito?

To setup Cognito I typically use one of the many open source cloudformation templates on GitHub. I crafted this template some time ago cognito.yml, it supports login using email address, and domain white listing for sign ups.

As a follow on from this I built a serverless application serverless-cognito-auth which encapsulates a lot of the standard functionality I use in applications.

You can also use AWS Mobile Hub or AWS Amplify to bootstrap a Cognito pool for you.

Overall recommendations are:

1. If your new to Cognito and want things to just work then I recommend trying AWS Amplify.
2. If you are an old hand and just want Cognito the way you like it, then use one of the many prebuilt templates.

How do I avoid quota related issues?

Firstly I recommend familiarising yourself with the AWS Cognito Limits Page.

I haven’t seen an application hit request rate this more than a couple of times, and both those were related to UI bugs which continuously polled the Cognito API.

The one limit I have seen hit is the sign up emails per day limit, this can be a pain on launch days for apps, or when there is a spike in sign ups. If your planning to use Cognito in a startup you will need to integrate with SES.

How do I work around searching my user database?

Out of the box cognito will only allow you to list and filter users by a list of common attributes, this doesn’t include custom attributes, so if you add an attribute like customerId you won’t be able to find all users with a given value.

This limitation makes it difficult to replace an internal database driven authentication library just using the cognito service, so for this reason I recommend adding a DynamoDB table to your application and integrating this with cognito using lambda triggers to build your own global user store.

To simplify interacting with Cognito I wrote a CLI which provides some helpful commands to scan, filter, export and perform some common admin functions, you can find it at https://github.com/wolfeidau/cognito-cli.

How do I back up my user pool?

Backing up user accounts in any system is something you need to consider carefully as this information typically includes credentials as well as other sensitive data such as mobile number which is often used as a second factor for other services.

Currently Cognito doesn’t provide a simple way of exporting user data, the service does however have an import function which will import users in from a CSV file.

Note: AWS cognito doesn’t support export user passwords, these will need to be reset after restore.

For some examples of tooling see cognito-backup-restore.

Conclusion

If you really care about security and compliance then cognito is a great solution, it has some limitations, and gaps but these can be worked around if you want to focus your effort somewhere else.

Personally I think it is really important that as a developer I pick solutions which ensure my customers data is locked away as securely as possible, and ideally using a managed service.

You could totally roll your own authentication solution, and manage all the patching and challenges which go with that but that makes very little sense when you should probably be solving the original problem you had.

Authentication is a yak I am willing to let someone else shave manage, and so should you, if not for your own sanity, then that of your users.

Lastly if your building out a web application use amplify-js, this library makes it so easy to add Cognito authentication to your web application. I used it on cognito-vue-bootstrap which you can also check out.