DEV Community: CKMo

Security is Usability — Examining Cybersecurity Erosion

CKMo — Thu, 03 Oct 2024 17:37:49 +0000

It's often said that humans are the weakest link in security and social engineering is easier than hacking. This is true — but there's another facet that isn’t discussed enough: when the security design causes friction, the system will deteriorate and lead to gaps over time due to user action (or inaction).

Great security solutions rarely fail on technical merits, but rather on human ones. However, it is possible to avoid this with security design which focuses on usability. The two — security and usability — do not need to be opposing forces.

We’ll cover several aspects of this topic:
Security is usability to avoid cybersecurity erosion
Why do we care about cybersecurity erosion?
What are some design choices to mitigate cybersecurity erosion?
Actionable takeaways

Security is usability

This is a key pillar of Pomerium’s security philosophy: you’re only as secure as your least compliant user.
The concept flows naturally into why some solutions suffer from what we call “Cybersecurity Erosion”: the solution’s architecture is technically sound but the design causes user friction and frustration, which in turn results in users looking for ways to overcome, go around, or even ignore the solution itself.

This is tangentially related to the concept of “Sustainable Security” covered by Sam Ainsworth. It’s a pervasive trend: even when correctly implemented, many security solutions degrade over time due to human factors. The designers simply didn’t take into account how the human element would erode the security solution over time in pursuit of “efficiency.”

As for why coin a new term, it’s because Sam Ainsworth’s coverage focuses specifically on a system’s technical aspects while this piece will focus on the system’s usability when it comes to user experience. In the end, security is usability.

If the security system gets in the way of productivity and workflow, even the most technically sound solution will erode as the human element seeks to navigate around the system or even take it down, piece by piece.

Here’s a few all-too-common examples:

Decision-fatigue: When users are bombarded with frequent alerts and notifications, they become desensitized. Many users tend to end up muting alerts and other notification screens, which directly weakens the system.
Password-fatigue: Without Single Sign-On (SSO), users juggling many passwords may resort to reusing them, compromising security. Password managers solve the interim problem but cause decision-fatigue when frequent prompts lower user acuity.
Inconsistent best-practices: A good example is network segmentation. When DevOps teams become too inundated with resource requirements and start cutting corners on network segmentation by not segmenting correctly or even adding new applications to existing network segments instead of creating isolated networks. The best practice isn’t followed, resulting in cybersecurity erosion.
Misapplied Access Control: In a rush, developers may incorrectly implement OpenID Connect (OIDC), creating vulnerabilities.
Client-based access: From usability to performance and reliability problems or even being considered unnecessarily invasive, client-based solutions add friction in the form of human design issues.

Why is cybersecurity erosion bad?

Let’s jump right to why it’s a concept worth discussing alongside “security is usability”. It’s impossible to ignore cybersecurity erosion as it has familiar costs and consequences:

Management overhead — Architecture requiring constant upkeep due to overhead will face de-prioritization or languish as resources are re-allotted or cost-cutting measures come into place.
Security friction — Security is often seen as a productivity inhibitor, but it doesn’t have to be designed that way. When users find security measures to be in the way of their workflow, they inevitably look for alternative pathways in search of a more efficient user experience. As a result, security teams begin viewing internal users as a problem to be managed, and the organization suffers internal conflict.

Neither symptom should be new. However, attributing these symptoms to a root cause of architectural design is new. When viewed in this manner, the following questions become relevant:

Why are we choosing between security and cost-reduction? If the security system is designed to minimize overhead and resource-drain, all discussions around efficiency in the future only need to ask if the organization is still maintaining the highest security posture with the minimal upkeep costs.
Is there security architecture that doesn’t inhibit workflow? Minimizing user frustration should be a new key objective when evaluating the existing security infrastructure. The architecture should keenly focus on smoothing out the user’s experience to avoid cybersecurity erosion. Otherwise, the safest security solution in the world will only be dismantled over time.

Tangibly, this means forward thinking organizations must evaluate solutions based on how well they’ll last, which often involves asking how it affects internal productivity and workflow. The fundamental architecture should actively avoid:

Frustrating the user. Any amount of workflow friction will lead to users trying to overcome the access control measures over time. The water of rivers will erode even the most durable stone, so the best answer is to design for the user’s workflow of least resistance.
Being difficult to implement. Access control isn’t implemented just once, but continuously over time as the organization grows and expands. When new environments or applications are created, the security should be easy and straightforward to implement to minimize mishaps. The system should not be overly prescriptive with implementation or you risk the practitioners being forced to architect around it.
Being difficult to maintain. No system can avoid needing maintenance, but it can be architected to either minimize the maintenance or enable a straightforward maintenance cycle. You never want your system to fail because the practitioners were overwhelmed by maintenance overload.

Tackling cybersecurity erosion with usability-first

Let’s share some of our successful learnings when designing for usability to mitigate cybersecurity erosion.

Clientless access
Speed and latency
Simple configuration

If you’re only as secure as your least compliant user, then we need to design accordingly. Thoughtful consideration for how users interface and interact with the system will pay long-term dividends for sustainable security.

Clientless access
Ask any user how they want to use the internet; does “logging into a client” make it into their preferred user flow? No — they usually say some form of “open the browser, type in a URL, hit enter.”

You need to minimize the amount of obstacles between users getting what they want, or they’ll look for ways around it. This is why we made clientless access a key Pomerium feature from the outset instead of as an after thought. For end users, this core feature translates to improved productivity and reduced costs for their business through:

Reduced user friction: No client, no additional hoops to jump through. Additionally, removing the need to memorize an additional set of credentials for logging into a client reduces user burden.
Minimal management burden: Removing the need to install and update a client across all user devices lightens a burden for IT management. If there’s nothing to misconfigure or forget, then there’s nothing that can be eroded.

Security is usability. There is no better way to design around cybersecurity erosion than to remove all semblances of the obstacle itself. With clientless access, most users don’t even know they’re going through Pomerium’s access control measures when accessing resources! As a nice bonus, this results in more productive employees when time is not lost dealing with clunky clients. This simple principle embodies the concept of security without friction, meaning the security team’s mandates are aligned with the company’s core desires for increasing productivity.

Speed and latency
This is specifically about your access control solution: Is the connection fast and does it minimize latency?

Let's face it, slow connections and lagging applications are productivity killers. Every second wasted waiting for a page to load or an action to register is a second stolen from your workday. Across a large organization, these delays can add up to significant lost hours.

That's why Pomerium prioritizes speed through a design enabling edge deployments. This minimizes latency and ensures a smooth, responsive experience. We've seen real-world results: helping Fortune 100 organizations slash latency from a sluggish 1.5 seconds down to a snappy 20 milliseconds.

Simple configuration
In today's fast-paced development environment with continuous integration and deployment (CI/CD), security solutions can become bottlenecks. Developers are constantly adding features and updating applications, and security needs to keep pace.

Gone are the days of one-time cybersecurity infrastructure deployments. As companies evolve, they find themselves constantly integrating their security solution with new acquisitions, expansions, and even mergers. This integration process can be a vulnerability minefield as traditional security implementations often require significant infrastructure changes, leading to misconfigurations and security gaps.

Traditional security solutions often require complex configurations that can introduce room for errors. This is especially true when deploying at scale in a CI/CD world. Even a seemingly small error rate, like 0.1%, can leave hundreds or even thousands of applications vulnerable. This cybersecurity erosion becomes a major liability over time, and we once again find the root cause to be: usability.

So what did Pomerium do differently to address this? We worked backwards from what we believe first principles are for what adding security should look like:

Error-Proof: Minimize the potential for human error during implementation, preventing disastrous security breaches.
Seamless Integration: Integrate seamlessly with existing infrastructure without forcing disruptive changes.
Effortless Testing: Simplify testing for potential misconfigurations and ensure a smooth security posture.

This was a difficult problem to solve. How can we offer a solution that allows companies to simply "add" security without disrupting their operations? We saw that many providers required extensive reconfiguration of existing infrastructure to fit their model. This created unnecessary complexity and discouraged adoption. Additionally, their implementation processes were often cumbersome and time-consuming.

In the end, our architectural model enables the following:

Deployed at edge: A key feature of Pomerium is being able to be deployed however you want it onto any existing infrastructure with minimal changes. The fewer parts that need to be moved, the better.
Programmatic deployments: We provide an API and SDK for developers so access control is being added the same way they would ship code. This achieves our goal of minimizing the potential for human error and misconfigurations.
Unified access controls: Because Pomerium is already greenlit by the security team, the only necessary tests are whether Pomerium was correctly added in front of each application. These application-centric deployments should have no security gap because they are shipped with the company’s pre-defined access controls.

This architectural decision ensures the solution serves the organization, not the other way around.

Actionable takeaways for any organization

Evaluate your cybersecurity system for sustainable usability or potential erosion.
Explore replacements which prioritize usability in its design to minimize erosion.

As your organization grows and evolves, it's crucial to ensure your cybersecurity doesn't become brittle and prone to gaps. Here's what you can do:

Conduct a Cybersecurity Sustainable Usability Audit: Take a close look at your current security system. Is it designed to adapt to changes and integrations, or does it require frequent updates and adjustments? Identify points where misconfigurations or gaps could occur during deployment or modification.
Explore Erosion-Resistant Solutions: Research options that prioritize a secure-by-design approach — for humans. The point of this write-up is to emphasize the importance of minimizing human deviation factors in your organization’s security system. This means looking for solutions designed to be secure without interfering with users or adding to the IT team’s burdens.

Liked what you read about Pomerium?
Pomerium’s design results in sustainable and usable security without cybersecurity erosion.

DevOps teams only need to configure Pomerium once through Zero then give API access to development teams. Developers can then add Pomerium’s access control and deploy to production with full confidence that the company’s security policies are being enforced. Finally, users can now access applications using the browser just like they would with any other website while Pomerium continuously verifies each action against identity and context.

Beautiful, isn’t it? We invite you to try out Pomerium today!

Skip the SSO tax with Pomerium

CKMo — Fri, 31 May 2024 23:04:16 +0000

Robust security is no longer optional in the modern threat landscape. Data breaches can damage business reputation and result in costly lawsuits. Yet, traditional Single Sign-On (SSO) solutions often come with a hefty price tag, forcing companies to choose between security and their bottom line.

The status quo shouldn't force companies to choose between security and their bottom line. Skip the SSO tax and add SSO to any self-hosted application with Pomerium.

What is SSO tax?

The SSO tax is when vendors charge users to access SSO as a service. This essentially means that customers pay extra money for a feature that companies should consider a basic security best practice. A common analogy is, “buying a car, paying for the brakes.”

Here’s the problem: those are some expensive brakes. The ssotax.org wall of shame shows significant pricing increases as a result of software vendors realizing they can force companies to pay for a basic security feature.

The Benefits of Single Sign-On (SSO)

SSO is a game-changer for user access management, especially for organizations juggling multiple cloud applications. Imagine logging into one central location (an identity provider like Google or Okta) and seamlessly accessing all your work apps without needing individual logins for each. This not only improves user experience but also enhances security, as it provides the following benefits:

Improved User Experience: Employees can access all their work applications with a single login, reducing frustration and wasted time.
Enhanced Security: SSO centralizes user authentication, making it easier to enforce access controls and manage user identities.
Reduced IT Burden: Onboarding and offboarding employees becomes much simpler with centralized user management.
Reduced Risk of Credential Theft: By reducing the number of logins needed, SSO minimizes the risk of compromised credentials.

Why is SSO Tax a problem?

The "SSO tax" creates a significant barrier for businesses, particularly smaller companies. Here's why it's a problem:

Unfair Pricing: Charging a premium for a core security feature like SSO is akin to selling a car and requiring an extra fee for brakes. It's a fundamental requirement, not a luxury add-on.
Reduced Security Adoption: High SSO costs can force companies to choose between user convenience and security, potentially leaving them vulnerable to cyberattacks.
Hinders Cloud Adoption: The "SSO tax" discourages businesses from adopting cloud-based solutions due to the additional cost of implementing SSO across multiple platforms.

Vendors might argue that SSO is a luxury feature and not necessary for small- and medium-sized businesses (SMBs), but that’s not true in practice. Not having SSO means:

Scaling difficulties: Onboarding and offboarding employees becomes difficult to manage at scale. The more applications you have, the bigger the scale.
Multiple access points: The purpose of single sign-on is to have one strong access point instead of multiple weak ones. This exposes multiple attack vectors for possible exploitation.
Credential fatigue: Forcing employees to keep track of multiple login credentials only results in increased chance of lost or stolen details. Moreover, password reset requests inundate IT management with unnecessary tickets.

While larger companies can afford to pay the extra SSO pricing tiers, SMBs can’t always afford to pay for enormous markups. Inevitably, when companies cannot afford SSO and hold sensitive customer data, they expose this data, leading to downstream security implications for customers.

Does the SSO tax actually cause software to be insecure?

Grip Security discussed the problem with over 100 CISOs and found that “80% of SaaS applications used by employees are not in their SSO portals,” listing the SSO licensing cost as the #1 reason for this predicament. So yes: the situation absolutely forces companies to choose between security and cost.

But vendors must be charging SSO for a reason, right?

There are some valid reasons why vendors might charge extra for SSO:

Development and Maintenance: Integrating SSO functionality requires additional development work and ongoing maintenance to ensure compatibility with various identity providers.
Supporting Multiple Identity Providers: Each identity provider has its own protocols and APIs, requiring tailored integrations. Supporting a wide range of providers increases development and maintenance complexity.
Customization Needs: Some companies might require custom configurations for their SSO implementation, adding to the vendor's workload.

While the above holds some merit, the following is also true:

Disproportionate Pricing: The upsell cost for SSO often goes far beyond what's reasonable to cover development and maintenance. It can be a significant multiplier of the base package, making it a luxury for smaller businesses that need it most.
Shifting Priorities: Charging a premium for SSO incentivizes profit over security. It creates a situation where companies have to choose between affordability and best practices.
Standardization Ignored: The sheer variety of identity providers can be a challenge, but industry standards exist to simplify integrations. Vendors who leverage these standards can reduce development costs and offer SSO at a more reasonable price.

The Ethical Dilemma

Ultimately, the "SSO tax" creates an ethical dilemma for vendors. While development costs exist, charging exorbitant fees makes it harder for businesses to prioritize security. Ideally, vendors should:

Offer SSO in Base Packages: Consider SSO a core feature, not an expensive add-on. In today's cloud-based world, secure access management is essential.
Develop Standardized Integrations: Leveraging industry standards can streamline development and reduce costs associated with supporting multiple identity providers.
Provide Transparent Pricing: Vendors should clearly outline the costs associated with SSO and avoid hidden fees or excessive markups. To those SMBs and even larger companies that would like to cut costs, Pomerium can alleviate some of that for you.

How does Pomerium workaround the SSO tax?

While many companies will write endless blogs shaming vendors for implementing an SSO tax, Pomerium believes in solution-oriented discussions. Pomerium Zero allows you to implement SSO for your self-hosted applications without the burden of the SSO tax. Here's what makes Pomerium stand out:

Free and Open Source: Pomerium Zero is a free, open-source solution. You don't have to pay any licensing fees or hidden charges to enjoy the benefits of SSO.
Easy to Implement: Pomerium Zero is designed for ease of use. It integrates seamlessly with your existing infrastructure and requires minimal configuration.
Secure and Scalable: Pomerium Zero prioritizes security without sacrificing performance. It offers robust access controls and scales to meet the needs of your growing business.
Empowering Businesses of All Sizes: Whether you're a small startup or a large enterprise, Pomerium Zero makes secure SSO accessible.

Even better, Pomerium can add SSO to legacy applications that do not have built-in SSO. Simply put Pomerium in front of your legacy application, implement SSO through Pomerium, and voila — you don't need to change the application at all.

Pomerium Zero offers this as a basic feature. The immediate ROI scales linearly with every single application your company uses where you self-host and pay to unlock SSO. If ten internal applications cost $20/user/month for SSO, Pomerium saves $200/user/month.

We use SAML. Do we have to keep paying the SSO tax?

While we highly suggest shifting to OIDC, companies that cannot shift away from SAML can find an OIDC compliant federating identity provider (such as Amazon Cognito) to implement SSO through Pomerium and save on the SSO tax.

Have other questions about a specific application or your custom identity provider? Feel free to reach out to us on our Discuss forums to ask how you can save on the SSO tax today.

Securing TiddlyWiki with Pomerium

CKMo — Mon, 11 Mar 2024 20:31:42 +0000

This guide will show you how to add authentication and authorization to an instance of TiddlyWiki on NodeJS with Pomerium. Note that Pomerium can secure any web application, so the steps within can be easily replicated for your web app of choice.

What is TiddlyWiki on Node.js

TiddlyWiki is a personal wiki and a non-linear web notebook for organizing and sharing information.

It is available in two forms:

As a single HTML page
As a Node.js application

In this guide, you will run Pomerium and your TiddlyWiki Node.js application in Docker containers.

How you will secure TiddlyWiki

Securing access to TiddlyWiki involves two steps:

Configuring Pomerium to forward specific user session data in an unsigned header to TiddlyWiki
Configuring TiddlyWiki to accept a special request header for trusted authentication

In this way, you can implement single sign-on (SSO) for your TiddlyWiki instance, which means an authorized user only needs to authenticate once to access the application.

To configure TiddlyWiki, you'll set its ListenCommand to use the authenticated-user-header parameter. You'll configure Pomerium to forward the user's email claim in an unsigned header to TiddlyWiki.

Before you start

If you completed our Quickstart guide, you should have a working Pomerium project with the following YAML files:

config.yaml
docker-compose.yaml

If you haven't completed the Quickstart:

Install Docker and Docker Compose
Create a config.yaml file for your Pomerium configuration
Create a docker-compose.yaml file for your Docker configuration

Set up Pomerium

Add the following code in your config.yaml file:

authenticate_service_url: https://authenticate.pomerium.app

jwt_claims_headers:
  X-Pomerium-Claim-Email: email

routes:
  - from: https://wiki.localhost.pomerium.io
    to: http://tiddlywiki:8080
    pass_identity_headers: true
    policy:
      - allow:
          and:
            - email:
                # Replace with your email address
                is: user@example.com

Let's review the configuration file:

The jwt_claims_headers setting will forward the user's email address in an unsigned, HTTP request header. The header follows the custom format specified in the file (in this case, X-Pomerium-Claim-Email).
The pass_identity_headers setting tells Pomerium to forward all identity headers to the upstream application
The attached policy authorizes users with a matching email address to access TiddlyWiki. Pomerium will forward the address specified in the policy to TiddlyWiki as an unsigned identity header.

Set up Docker Compose services

Add the following code in your docker-compose.yaml file:

version: '3'
services:
  pomerium:
    image: cr.pomerium.com/pomerium/pomerium:latest
    volumes:
      - ./config.yaml:/pomerium/config.yaml:ro
    ports:
      - 443:443

  tiddlywiki_init:
    image: elasticdog/tiddlywiki:latest
    volumes:
      - ./wiki:/tiddlywiki
    command: ['mywiki', '--init', 'server']

  tiddlywiki:
    image: elasticdog/tiddlywiki:latest
    ports:
      - 8080:8080
    volumes:
      - ./wiki:/tiddlywiki
    command:
      - mywiki
      - --listen
      - host=0.0.0.0
      - authenticated-user-header=X-Pomerium-Claim-Email
    depends_on:
      - tiddlywiki_init

Before you test your services, make sure the value of authenticated-user-header matches the value of the custom header defined in config.yaml.

Run Docker Compose:

docker compose up

Test TiddlyWiki

In your browser, navigate to your TiddlyWiki instance. Pomerium will prompt you to authenticate against its hosted identity provider.

After successful authentication, Pomerium will redirect you to your TiddlyWiki instance:

Great job! You successfully secured TiddlyWiki behind Pomerium.

Want to secure something else instead? Check out our guides, or if it's not there, reach out on our forums!

Securing Grafana for Web Access

CKMo — Tue, 27 Feb 2024 16:39:36 +0000

This guide will demonstrate how to secure an instance of Grafana behind Pomerium proxy to provide users with a seamless login to Grafana using your identity provider.

What is Grafana?

Grafana is an open-source analytics visualization and monitoring tool. It provides many user-contributed Dashboards that make it popular for enthusiasts as well as professionals.

Getting Started

Note: This guide uses GitHub as the pre-configured Identity Provider (IdP), but you can use any supported IdP.

To complete this guide, you need:

Docker and Docker Compose
A pre-configured identity provider (IdP)

See the Pomerium Quick-start guide to run Pomerium in a containerized Docker environment.

Build a Grafana Route

In your config.yaml file, add the following Grafana route:

- from: https://grafana.localhost.pomerium.io
  to: http://grafana:3000
  host_rewrite_header: true
  pass_identity_headers: true
  policy:
    - allow:
        or:
          - email:
              is: user@example.com

In the code above:

host_rewrite_header rewrites the Host: header to match an incoming header value. Without this option enabled, Grafana will throw a 403: Origin not allowed error after login when you attempt to add users.

This behavior is due to a CSRF check added in Grafana v8.3.5 (this guide uses v9.2.4) that requires the Origin request header to match the server origin.

See this GitHub issue for more information.

Configure Grafana to use JWT Verification

Configuring Grafana to use JWT authentication makes it possible for Grafana to accept identity claims sent upstream by Pomerium.

Since you're not using a grafana.ini file to configure your Grafana instance, you can override Grafana's configuration using environment variables. See the Grafana docs for more information.

In your docker-compose.yaml file, add the Grafana Docker image as a service:

grafana:
  image: grafana/grafana:latest
  ports:
    - 3000:3000
  environment:
    - GF_AUTH_SIGNOUT_REDIRECT_URL=https://grafana.localhost.pomerium.io/.pomerium/sign_out
    - GF_AUTH_JWT_ENABLED=true
    - GF_AUTH_JWT_HEADER_NAME=X-Pomerium-Jwt-Assertion
    - GF_AUTH_JWT_EMAIL_CLAIM=email
    - GF_AUTH_JWT_JWK_SET_URL=https://grafana.localhost.pomerium.io/.well-known/pomerium/jwks.json
    - GF_AUTH_JWT_CACHE_TTL=60m
  volumes:
    - ./grafana-storage:/var/lib/grafana

Here's what the environment variables do:

GF_AUTH_SIGNOUT_REDIRECT_URL: signs users out of Pomerium when they sign out of Grafana
GF_AUTH_JWT_ENABLED: enables JWT authentication (Grafana disables it by default)
GF_AUTH_JWT_HEADER_NAME: tells Grafana which HTTP header to look at for the JWT (see Identity Verification for more information)
GF_AUTH_JWT_EMAIL_CLAIM: associates the email_claim in the JWT with the email of the Grafana user
GF_AUTH_JWT_JWK_SET_URL: defines the URL with the signing key to validate the JWT
GF_AUTH_JWT_CACHE_TTL: sets a 60-minute cache time for the token

Congratulations, your Grafana now has a secured route. Let's add users.

Add users to Grafana

At this stage, Grafana is configured to use the email claim in the JWT to associate an incoming connection with a user (you will configure Pomerium to include identity information via the JWT in the next section).

But, the user first must exist in Grafana to be associated. Otherwise, you will see the following error in the browser after authenticating:

{"message": "User not found"}

To avoid this error, create a user with administrator privileges. (If you plan on administering Grafana through a direct connection to the service, skip this section.)

To add users without requiring them to accept an invitation:

Log in to Grafana directly as an admin user at https://grafana.localhost.pomerium.io (if this is your first time signing up for Grafana, admin is the default username and password)
Select Server Admin, Users

Caution: This is distinct from the Users option under the Configuration cog wheel, which will only finalize a new user when they accept an invite via email or link.
Select New user to create a new user. Make sure that the email address matches the one provided by Pomerium via your IdP. If you want to check the data provided by Pomerium in the JWT, you can access the special endpoint /.pomerium from any Pomerium route to view it.

After creating a new user in Grafana, that user should be logged in automatically when they access Grafana from the Pomerium route (after first authenticating with your IdP, of course).

Manage access at scale

First, ensure Grafana is up to date to take advantage of auto_sign_up, as it is only available for JWT as of version 8.4.0.

The steps outlined above work to confirm the configuration for small teams, but adding users individually and manually does not scale for larger organizations. To add users to Grafana at scale, you can use the Grafana's auto_sign_up configuration to auto sign up users as they log in:

[auth]
signout_redirect_url = https://grafana.localhost.pomerium.io/.pomerium/sign_out
[auth.jwt]
enabled = true
header_name = X-Pomerium-Jwt-Assertion
email_claim = email
jwk_set_url = https://grafana.localhost.pomerium.io/.well-known/pomerium/jwks.json
cache_ttl = 60m
username_claim = sub ;sets the username to the value of the "sub" claim
auto_sign_up = true ;sets the login to automatically create a new user if one doesn't exist
[users]
auto_assign_org = true ;auto assigns the user to the existing default organization
auto_assign_org_role = Editor ;auto assigns the user the "Editor" role

Note that the value of auto_assign_org_role could also be "Admin" or "Viewer".

This will automatically create a user with their email and username populated.

Pomerium autopopulates the JWT name claim by default with the value provided by the identity provider to save you time. This configuration will allow seamless authentication and authorization without any additional toil for your team.

For teams using Google as an IdP, the user field is populated by a numeric value that you cannot configure. Note that Grafana can accept the name field as a username, including spaces:

username_claim = name

Troubleshooting

Local Signing Key

In instances where Grafana cannot get the signing key for the JWTs from the Pomerium authenticate service, you can place a copy of the key locally.

For example, wildcard certificates signed by LetsEncrypt may still be cross-signed by the [expired DST R3 root]. While many browsers still trust these certificates (as long as they are also signed by a valid root), some applications reject them, including Grafana:

logger=context error=Get "https://grafana.localhost.pomerium.io/.well-known/pomerium/jwks.json": x509: certificate signed by unknown authority

To circumvent this issue, you can use curl or wget to download the signing key locally:

curl

From the Grafana host:

curl https://grafana.localhost.pomerium.io/.well-known/pomerium/jwks.json > /etc/grafana/jwks.json

wget

From the Grafana host:

wget -O /etc/grafana/jwks.json https://grafana.localhost.pomerium.io/.well-known/pomerium/jwks.json

Edit grafana.ini and add the jwk_set_file key to provide it to Grafana:

[auth.jwt]
enabled = true
header_name = X-Pomerium-Jwt-Assertion
email_claim = email
jwk_set_file = /etc/grafana/jwks.json
cache_ttl = 60m

If you have other issues with this guide, please reach out to Pomerium on our forums!

Children’s Introduction Guide to Zero Trust

CKMo — Sat, 24 Feb 2024 00:42:46 +0000

This guide gives a children’s-level overview for zero trust principles based on NIST SP 800-207 Zero Trust Architecture. It is part of Pomerium's Children's Guide series.

(All images are generated with AI.)

Once upon a time there was an app named Alice. She grew up under the watchful eye of DevDad, but no app could help people while stuck in the Sand Castle. The day came for Alice to leave the safety of the Sand Castle, and DevDad needed to prepare her for the world.

To do so, DevDad made a container ship just for her, which would contain everything Alice needs when she goes outside. But DevDad worried she would encounter Blackhats while sailing the Wild Wild Web — bad people that would trick Alice or worse, get into her ship and steal from her.

And so DevDad asks her if she remembered her lessons on zero trust.

“Why do I need this again?” Alice asked.

“It’s for keeping yourself safe. Sometimes we do things because it’s simple or fast, but simple and fast is rarely safe. Remember when I always told you to look before you jump? Why did you trust that where you jumped would be an easy or safe landing?”

Alice thought about that. “But what if I’ve safely made that jump many times and know there’s pillows at the bottom? Really soft pillows?”

DevDad nodded. “I understand. But then, what if the next time you jump without looking, someone else had come and taken all the really soft pillows? Then you’d be hurt, because you trusted what you knew to be true, but is no longer true. That’s why you should check each time you jump even if you’ve made that jump a hundred times before. Someone only needs to take the pillows away once for it to hurt a lot. Does that make sense?”

“I think so.”

“So let me ask you this: if you meet someone out there on the Wild Wild Web, what do you think you should be checking before you let them in your ship?”

“Um, the person. What they’re using. And…” Alice’s face scrunched up in thought, “…what they’re trying to do?”

“Yes, those three things.” DevDad held up three fingers. “Always check if the person is who they say they are. Look to see if they’re using the things you expect them to be using. And of course, think about if what they’re trying to do makes sense.”

“That’s a lot to do before I let someone in,” Alice complained. “What if I end up making lots of friends?”

“That’s not much of a worry, I designed your ship to do that for you.” DevDad pointed to a tool at the door called a reverse proxy, then reminded Alice, “Remember: this is your ship, and it has many things others might want.” DevDad held up a box of Alice’s things, then pulled a toy out. “Like your favorite rubber duck. If you let in a Blackhat, they might steal it. And once someone gets inside, it becomes very hard to get them out again.”

“But how does that check for me?” Alice pointed at the reverse proxy. “What if you wanted to visit me?”

“That’s a good question. So for example, you trust me right, Alice?” DevDad asked.

“I do!” Alice burbled. “You helped make me.”

“And sometimes I might want to come see you again once you leave Sand Castle.” DevDad hoisted Alice into her ship. “But no matter how excited you are to see a familiar face, how do you know it’s me?”

Alice peeked outside of her ship. “I can’t just look at you?”

“No, because while that is checking, it can be easily fake.” DevDad clapped his hands and summoned up an exact replica of himself, then the two walked around Alice’s ship. “Sometimes, Blackhats like to pretend they’re someone you know in order to get you to open your container for them. They might look and sound like me, but you must make sure to have multiple methods of checking sure if it is me.”

“Like the phrase we use?”

“Exactly! But what if Blackhats heard us use the phrase or steal it from me? Another thing you can check is whether I’m carrying something you know only I have, such as these.” DevDad pulled out a set of keys from his pocket. Nearby, the clone reached into his pocket and pulled out nothing, for it did not have the same set of keys. “When you check for two or more things that should prove someone is who they say they are, then it is more likely to be true. This is important or you might end up letting the wrong person in.”

“Won’t people hate me for asking them to prove they are who they are?” Alice frowned. “I would hate to be asked to prove who I am.”

“Oh of course,” DevDad agreed. “People hate it. But that’s why I set up your reverse proxy to do all that checking for you as quickly as possible…as long as you remember to check! Now, do you remember the second thing to verify?”

“Um, what they’re using!”

DevDad created another ship and stepped into it. “Correct. Do you know why?”

Alice thought hard. “Because sometimes what they’re using to connect to my ship might be icky?”

DevDad’s ship rolled up to bump against Alice’s ship. “Sometimes, the person is real. But how do you know their ship isn’t carrying anything dangerous?” DevDad’s ship opened to try and connect with Alice’s ship. “For example, you’re allergic to all types of bugs — how do you know my ship is bug-free? Just because I said I cleaned it?”

“But I can’t go onto your ship to check,” Alice pointed out.

“No, you can’t. But your reverse proxy can check for you whether my ship is as clean as it should be. Only after you have checked if my ship is safe to connect with should you open up.”

DevDad looked at Alice and held up three fingers. “Finally, checking what they’re trying to do. If you open your ship for someone to come fix a leak in the front, but they want to go straight to the back, does that make sense? No! So whenever someone, anyone, wants to do something on your ship, you need to check that it makes sense.”

DevDad stepped off his ship and it disappeared, but Alice seemed deep in thought.

“This is a lot to check before anything happens,” Alice observed from inside her ship. “That’s a lot to remember.”

“Indeed it is.” DevDad agreed. “To make it simple for you and your friends, I gave your ship a reverse proxy to do all of it for you. Now come on out: there’s one thing we should do together.”

“Nuh uh. Can you prove who you are?”

DevDad smiled, seeing that Alice was learning. He allowed her ship to check who he was before Alice climbed out. “Let’s get your ship to the Wild Wild Web.”

Alice ran over to hug DevDad. “Does this mean I’ll be sailing alone?”

“You’re a grown app now, you’re free to go where you’re needed — whether it’s the Castle in the Clouds or the Edge of the World.” DevDad returned the hug. “I’ll come find you every once in a while to make sure you are being good and have everything you need, but remember —”

“Zero trust, and to always check if I’m doing it.”

Together, DevDad and Alice pushed her ship out to the Wild Wild Web. Alice had many fun adventures and met many friends while keeping her ship safe from Blackhats.

If you enjoyed this, feel free to check out other parts of this Children’s Guide series:

Children’s Guide to Context-Aware Access
Children’s Guide to the Perimeter Problem
Children’s Guide to Deperimeterization

Secure Browser Access to code-server VSCode

CKMo — Fri, 16 Feb 2024 20:18:44 +0000

Secure Browser Access to code-server VSCode Behind Pomerium

In this guide, you'll run code-server's Visual Studio Code (VSCode) in a Docker container and secure browser access to your project with Pomerium, an open source reverse proxy.

What is code-server?

Code-server is an open-source tool that allows you to run VSCode, a popular integrated development environment (IDE), on a remote server through the browser. This setup essentially turns VSCode into a cloud-based IDE, providing flexibility and accessibility advantages.

Code-server is particularly popular among developers who want the full power of VSCode, but need to work in a cloud-based environment. This is ideal if you work on multiple machines, need to access your development environment remotely, or you have limited local resources.

How to secure code-server with Pomerium

Code-server requires password authentication by default. By securing code-server behind Pomerium, you can remove code-server’s password requirement and configure Pomerium to add authentication and authorization to an online instance of VSCode.

This guide shows you how to secure code-server with Pomerium. Here are the steps you’ll follow:

Install code-server and run it in a Docker container
Access your code-server project in the browser listening on localhost
Configure Pomerium to safely expose your code-server instance

By the end, you will have a minimal, real-world code-server instance that allows developer teams to write code using VSCode in the browser.

Before you start

If you completed Pomerium's Quickstart guide, you should have a working Pomerium project with the following YAML files:

config.yaml
docker-compose.yaml

If you haven't completed the Quickstart:

Install Docker and Docker Compose
Create a config.yaml file for your Pomerium configuration
Create a docker-compose.yaml file for your Docker configuration

Set up Pomerium

In your config.yaml file, add the hosted authenticate service URL:

authenticate_service_url: https://authenticate.pomerium.app

Add the following route:

- from: https://code.localhost.pomerium.io
  to: http://codeserver:8080
  policy:
    - allow:
        or:
          - email:
              is: user@example.com
  allow_any_authenticated_user: true
  allow_websockets: true

Note: In this example route, code.localhost.pomerium.io is the publicly accessible route. codeserver is the local hostname for the server or container running code-server.

Set up Docker Compose

In your docker-compose.yaml file, add the code-server and Pomerium services:

version: '3'
services:
  pomerium:
    image: pomerium/pomerium:latest
    volumes:
      - ./config.yaml:/pomerium/config.yaml:ro
    ports:
      - 443:443
  codeserver:
    image: codercom/code-server:latest
    ports:
      - 8080:8080
    volumes:
      - ./code-server:/home/coder/project
      - ./code-server-config/.config:/home/coder/.config

Access code-server on localhost

Run docker compose up. In your browser, go to localhost:8080.

Code-server will prompt you to enter a password. You can find a pre-generated password in code-server-config/.config/code-server/config.yaml. If you enter it, you gain access to your code-server project.

However, remembering passwords is tedious. Let's disable the password requirement and use Pomerium to enforce authentication and authorization instead.

Access code-server behind Pomerium

In docker-compose.yaml, add the following command to your code-server container:

codeserver:
  image: codercom/code-server:latest
  ports:
    - 8080:8080
  volumes:
    - ./code-server:/home/coder/project
    - ./code-server-config/.config:/home/coder/.config
  command: --auth none --disable-telemetry /home/coder/project

This will disable the password prompt (and prevent code-server from collecting telemetry data from your project). Now, restart Docker Compose and access code-server using the route defined in config.yaml:

https://code.localhost.pomerium.io

After authenticating against the Cognito identity provider, you will be redirected to the code-server route.

Build a project in code-server

Now that you can access VSCode in your browser, test out code-server by building a quick HTML project.

Create an index.html file and add the following code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Code-Server Sample</title>
  </head>
  <body>
    <h1 style="color:blueviolet">Check out more from Pomerium:</h1>
    <ul style="font-size: 20px;">
      <li><a href="https://www.pomerium.com/docs/guides">Guides</a></li>
      <li><a href="https://www.pomerium.com/blog/">Blog</a></li>
      <li><a href="https://www.pomerium.com/docs">Documentation</a></li>
    </ul>
    <h2 style="color:blueviolet">Happy coding!</h2>
  </body>
</html>

Go to Extensions and install Live Server
Right-click index.html and select Open with Live Server
Select any of the links to learn more about Pomerium

Great job! You successfully deployed code-server.

Note: When the code-server container is rebuilt, any files outside of /home/coder/project are reset, removing any dependencies (such as go and make). In a real remote development workflow, you could mount additional volumes, or use a custom code-server container with these dependencies installed.

5 Lessons Learned Connecting Every IdP to OIDC

CKMo — Thu, 15 Jun 2023 20:29:21 +0000

Developers may be familiar with the need to add authentication and authorization to applications. Today, this usually involves integrating some form of identity provider (IdP) for single sign-on (SSO) purposes via Open ID Connect (OIDC).

But OAuth is already very hard and eats up a lot of dev time. Consider how difficult it is to configure OIDC, which is built on top of OAuth? We thought that since this process is a big headache for developers, “Wouldn’t it be nice if OIDC's manually complicated and easily broken process was just done for you for any IdP?”

While it’s certainly nice for developers, getting there was a nightmare. Below we included 5 lessons we learned simplifying OIDC for all developers.

Take a deep breath with us and let’s go.

Lesson 1: Too Many Standards Means No Standard

Let’s work a bit backwards first: why do we want to integrate with IdPs? Well, in the OIDC setup, the Relying Party (RP, or service provider) wants authentication (and authorization, but we can’t cover everything), and IdPs are a great way to authenticate the user trying to access the service.

To accomplish this, the RP usually wants three things per OIDC standards (bear with us, we know we’re simplifying this):

Access Token — allows RP application to access API/User Info endpoint
Refresh Token — for getting a new Access token
Identity Token — caches User profile information and provides it to client app

While all the IdPs end up giving you these three tokens, what we did not expect was that they would give you these three tokens in wildly different forms. And by that, we don’t mean that they don’t always give it to you as a JSON Web Token (JWT) — which, incidentally, is true in some cases — but that each token would have a nonstandard form of giving you the information you wanted.

Some IdPs put everything in the ID Token. Other IdPs put everything in the User Info endpoint and make you query the API. Then some IdPs want to do a combination of these things, giving you some information in the ID Token and then make you query the rest from their API. This results in a lot of different sources of truth to standardize!

And we wanted to provide one gateway that allows for all these IdPs to plug and play for developers trying to configure OIDC.

Standardizing All ID Tokens for One Gateway

There were so many ways these three tokens alone looked differently across IdPs, but ID Tokens were definitely the biggest wildcard. Almost all of them were providing user identities in different ways. That’s a problem seeing as obtaining this information from IdPs is more or less the entire point.

So, earlier we mentioned that ID Tokens cache the user’s profile information and provides it to the client app. It’s a major part of the OIDC specification because well, part of authenticating someone is getting information about them. The ID tokens are supposed to provide a bunch of basic information about the user which the service can use to authenticate the user.

We were naïve enough to think the ID Tokens would look like passports: standardized across the IdPs. Instead, each IdP acted like a state, issuing their ID Tokens like driver’s licenses: while the data was all there, no two tokens were presented in the same format.

Here’s some examples of this madness:

AWS Cognito returns email verified as a string, not a boolean
PingIdentity chooses to return “mail” instead of “email”
Google does not support the offline_access scope (there’s a joke about always online here). Also prompt must be set to consent to ensure that our application always receives a refresh token
Onelogin also stopped supporting the offline_access scope when they launched v2
Microsoft Azure returns a non-standard issuer violating the OIDC spec (a running theme among IdPs)
Still Microsoft — a fun issue thread to read on their Azure Docs

In many cases, simply using a library to attempt OIDC would fail since obviously none of the IdPs provide things in an actual OIDC format. The result was spending devtime to write code for an extra layer to transform each individual ID token into an actual standard form before parsing it for the OIDC library.

Deep Breath.

Lesson 2: Most IdPs Don’t Even Try OIDC

It turns out not every single IdP supports OIDC. GitHub is an example — they don’t even OIDC, so we had to integrate with GitHub using OAuth.

There are many IdPs that simply don’t support OIDC, or gave us an API that is close to OIDC but different enough that the implementation does not result in OIDC. There were various challenges associated with trying to understand how that would work, and imagine our surprise when it turns out the answer is: “Oh, we don’t actually support OIDC.”

On the flip side, one IdP stands out as the easiest to integrate with and most closely aligns with OIDC standards. Drum roll…

(It’s Okta.)

Lesson 3: Directory Sync at Scale

The problem with scale is that you don’t think about it until boom, use case. Well, turns out our larger users (organizations with over 10k users) had a lot more groups in their directories than we initially thought to test for.

What did we think? Well, maybe around 100-300 groups? That seems reasonable, right? It stands to reason that groups being a way to categorize users would result in the group count < user count… right?

What do our users with over 10k users actually have? 10k groups. (Yeah. That was our reaction too!)

Some directories can have groups within groups (introducing group recursion, a different headache), and the OIDC authentication process would need to add or update all of the groups at once during directory sync. That’s a lot of data.

Somehow.

Together, all at once.

Deep Breath.

Directory Sync.

Look, IdPs, please understand that you need to support groups without doing a full directory sync! When each user’s info reaches 1MB and there’s >10k users, that’s an enormous data problem when you’re trying to do a full sync each time.

Groups info shouldn’t be in constant flux; there can’t be that many rockstar employees fulfilling so many different functions their groups info changes all the time (and if there is, just create a rockstar user group).

Azure AD actually figured this out with a delta changes feature. This feature means directory sync only calls the information that changed (so less than 1KB per user). Yes, it was hard to integrate, but it scales! The easy solutions don’t! The easy solutions are not lightweight at all!

Lesson 4: Where Should Data Be Placed?

Lesson 5: Keeping It Manageable

After our newfound epiphany that none of the IdPs will stick to the OIDC standard and all of them were doing their own thing, our devs were side-eyeing the “maintenance and upkeep” bucket with fear.

To save our sanity, we created a directory provider interface.

This allows developers implementing OIDC to adapt the quirks and weirdness of each IdP to their Pomerium instance. We then moved our existing directory providers to a separate repository so that implementation of directory providers is not tied to open-source Pomerium Core.

The result is achieving the original goal (helping developers simplify OIDC with any IdP) while keeping it manageable.

Deep Breath.

Closing Thoughts — Saving Devtime and Sanity

For those who want to take a crack at it yourselves, good luck! We do have some words for IdPs though:

Hey IdPs, it would be really nice if you stick to the OIDC standard. But here’s a few additional asks from our engineering team:

Please test your OIDC implementation against common SDKs so it works out of the box. Based on our understanding, everyone will need the Cognito hack to implement Cognito in OIDC. (Maybe it works fine in java, but we’re using the off-the-shelf Go library to do this.)
Please realize you all need to support group sync without doing a full directory sync. It’s a data intensive process and very annoying to maintain.
Please give people a way to add arbitrary directory data to claims, and everyone would be a lot happier. This would also make your product a lot more lightweight and easier to integrate with other products

A rising tide lifts all boats, and OIDC is very important in how things are done today. Developers shouldn’t be stuck configuring it for hours on end! Making sure that it’s as simple as possible for users to implement is key.

After all that work, we’re proud to say that developers can easily add OIDC to any resource via Pomerium. Whether you’re spinning up a new application or trying to add access control to a legacy service, OIDC authentication and authorization is just an SDK away. You can check out our open-source Github Repository or give Pomerium a try today!