New Interested in participating in the HCP Waypoint Private Beta Program? Apply here
  • Infrastructure
    • terraform
    • packer
  • Networking
    • consul
  • Security
    • vault
    • boundary
  • Applications
    • nomad
    • waypoint
    • vagrant
  • HashiCorp Cloud Platform

    A fully managed platform to automate infrastructure on any cloud with HashiCorp products.

    • consul
    • terraform
    • vault
    • packerbeta
    Visit cloud.hashicorp.com
  • Overview
  • Tutorials
  • Docs
  • CLI
  • Plugins
  • Community
GitHub
Download
    • v0.8.x (latest)
    • v0.7.x
    • v0.6.x
    • v0.5.x
    • v0.4.x
    • v0.3.x
    • v0.2.x
    • v0.1.x
    • Overview
      • Overview
      • Helm
      • Heroku, Vercel, etc.
      • Kubernetes
  • Getting Started
    • Overview
    • Compatibility Promise
    • Protocol Version Table
    • Release Notifications
      • Overview
      • Upgrade to 0.2.0
      • Upgrade to 0.3.0
      • Upgrade to 0.4.0
      • Upgrade to 0.5.0
      • Upgrade to 0.6.0
      • Upgrade to 0.7.0
      • Upgrade to 0.8.0

    • Install
    • Externally Built Images
    • Building Container Images
    • Helm Deployment
    • YAML-Free Deployment
    • YAML Directory Deployment
    • Resource Status
    • ConfigMaps and Secrets

    • Overview
    • Git Integration
    • Remote Operations
    • Overview
    • Build
    • Deploy
    • Release
    • Hooks
    • Labels
    • Workspace and Label Scoping
    • Overview
      • Overview
      • Input Variables
      • External Data
      • artifact
      • deploy
      • entrypoint
      • labels
      • path
      • workspace
      • Overview
      • Full Reference
      • Templating
      • Overview
      • Expressions
      • JSON Syntax
    • app
    • build
    • config
    • deploy
    • hook
    • plugin
    • registry
    • release
    • runner
    • url
    • use
    • variable
  • URL Service
  • Logs
  • Exec
    • Overview
    • Dynamic Values
    • Files
    • Internal Values
    • Workspace and Label Scoping
    • Overview
      • Overview
      • OIDC
      • Overview
      • Maintenance
      • Production
      • Security
    • Express Server Install
    • Overview
    • Configuration
    • Profiles
    • On-Demand Runner
    • Additional Runners
  • Workspaces
  • Plugins
  • Triggers

    • Overview
      • Overview
      • Registering Plugin Components
      • Handling Configuration
      • Implementing the Builder Interface
      • Compiling the Plugin
      • Creating an Example Application
      • Testing the Plugin
    • Initializing the SDK
    • Passing Values Between Components
      • Overview
      • Authenticator
      • ConfigSourcer
      • Configurable
      • ConfigurableNotify
      • Builder
      • Registry
      • Platform
      • ReleaseManager
      • Destroy
      • Status
      • Default Parameters
      • Overview
    • Overview
    • Disable
    • Overview
    • GitHub Actions
    • GitLab CI/CD
    • CircleCI
    • Jenkins
  • Troubleshooting
  • Glossary

    • Overview
    • Architecture
    • Operation Execution
  • Roadmap

The Waypoint website is being redesigned to help you find what you are looking for more effectively.

Type '/' to Search

»OpenID Connect (OIDC)

Waypoint can be configured to use OpenID Connect (OIDC) for authentication. This enables you to use existing identity providers such as Google, Okta, GitLab, and more.

OIDC doesn't replace the built-in token system. The token system can and should still be used for machine-oriented access. Humans can use OIDC to authenticate and acquire a token.

»Configuring OIDC

You can configure OIDC using the waypoint auth-method set oidc CLI command. Please see the documentation for that command for all available options.

Before you setup OIDC, you'll need at least the client ID and client secret for your identity provider. Please see the documentation for your identity provider to determine what these values are. See Popular OIDC Providers for some help and guidance with specific popular providers. Please read the documentation on redirect URLs while configuring your OIDC provider.

Once you have the required information, use the CLI:

$ waypoint auth-method set oidc \
  -client-id=87a30dc693eb4db0a807c9faked4e0e643277f698aff83df5661021b6fc2d742 \
  -client-secret=11360b5e9d7a54435dstillfake0b2c0e49ca866676f00ab02ad0e8e2a6c \
  -issuer=https://accounts.google.com \
  google
$ waypoint auth-method set oidc \
  -client-id=87a30dc693eb4db0a807c9faked4e0e643277f698aff83df5661021b6fc2d742 \
  -client-secret=11360b5e9d7a54435dstillfake0b2c0e49ca866676f00ab02ad0e8e2a6c \
  -issuer=https://accounts.google.com \
  google

This will configure an OIDC auth method that is available to users immediately. You can use the other commands in the waypoint auth-method subcommand group to list, inspect, and delete auth methods.

»Redirect URLs

When configuring your OIDC provider, the provider should ask you to configure a set of allowed redirect URLs. This configurations happens on the provider's side, i.e. within Google, Okta, etc.

You should set the following redirect URLs:

  • http://127.0.0.1/oidc/callback - This must be set for waypoint login to work in the CLI. If you do not set this, the CLI login will not work. Note that non-TLS is expected here since it is a loopback call.

  • https://<ui addr>/auth/oidc-callback - This must be set for UI-based OIDC authentication to work. In this case, "ui addr" should be the routable UI address you visit. And note you SHOULD set TLS (https) for this.

»Restricting Access

You can restrict access to only certain users in your identity provider. Identity providers advertise a set of "claims" about a user. These claims can be used in rule expressions to restrict access.

To determine what claims are available, please see the documentation for your identity provider. An alternate approach is to configure the OIDC provider with no restrictions, then log in with the -v flag, i.e. waypoint login -v 127.0.0.1:9701. The -v flag will log a WARN-level entry with all the claims for your account.

Once you know what claims you want access to, you must specify them in the waypoint auth-method set oidc command, and create a rule. For example, for GitLab:

$ waypoint auth-method set oidc \
  -client-id=myid \
  -client-secret=mysecret \
  -issuer=https://gitlab.com \
  -list-claim-mapping="groups=groups" \
  -access-selector="mycompany in list.groups" \
  gitlab
$ waypoint auth-method set oidc \
  -client-id=myid \
  -client-secret=mysecret \
  -issuer=https://gitlab.com \
  -list-claim-mapping="groups=groups" \
  -access-selector="mycompany in list.groups" \
  gitlab

The -list-claim-mappings flag maps the "groups" claim to be exposed as list.groups in the access selector. The -list- prefixed flag should be used for all list claims (arrays). The -claim-mapping flag should be used for all direct values and will be exposed as value.<name>.

The selector mycompany in list.groups configures the provider to require the user to be in the group "mycompany" to authenticate. This can be used to restrict users to your Waypoint server. For full documentation on the available syntax, see the Consul documentation which uses the same syntax.

»Account Mapping

When logging in with OIDC, Waypoint will automatically create a new user account within Waypoint if one does not exist. Waypoint uses the following rules to find an existing user:

  1. Look for an existing user account that is linked to exactly the user (issuer ID, sub ID) tuple.

  2. Look for an existing user account with an email address matching the email claim. This is only done if the identity provider specifies email_verified as true.

  3. Create and link a new user with a random username.

Users of OIDC-created accounts can modify their account details using waypoint user modify.

»Popular OIDC Providers

This is a list of popular OIDC providers with a link to their help and any other information that might be useful for configuring OIDC.

»Google

  • Help: https://developers.google.com/identity/protocols/oauth2/openid-connect
  • Issuer URL: https://accounts.google.com

»GitLab

  • Help: https://docs.gitlab.com/ee/integration/openid_connect_provider.html
  • Issuer URL: https://gitlab.com (or the URL to your own installation)

Important: use the groups claim to restrict access to GitLab users that are members of specific groups. Otherwise, every GitLab user in the installation can access your Waypoint server.

»Okta

  • Help: https://developer.okta.com/docs/reference/api/oidc/
  • Issuer URL: https://${yourOktaDomain}/
github logoEdit this page

Using Waypoint

The best way to understand what Waypoint can enable for your projects is to give it a try.

Waypoint tutorials
Waypoint documentation
Tutorial

Get Started - Kubernetes

Build, deploy, and release applications to a Kubernetes cluster.

View
Tutorial

Introduction to Waypoint

Waypoint enables you to publish any application to any platform with a single file and a single command.

View

Waypoint is maintained by HashiCorp, Inc.

View Code of Conduct
DocumentationCLI ReferenceTutorialsIntegrations
All systems normal