A new platform for documentation and tutorials is launching soon.
We are migrating Waypoint documentation into HashiCorp Developer, our new developer experience.
»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.
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
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.
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 loginto 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.
To set the UI-based URL when setting up your auth method, add the
$ waypoint auth-method set oidc \ -client-id=87a30dc693eb4db0a807c9faked4e0e643277f698aff83df5661021b6fc2d742 \ -client-secret=11360b5e9d7a54435dstillfake0b2c0e49ca866676f00ab02ad0e8e2a6c \ -issuer=https://accounts.google.com \ -allowed-redirect-uri=https://<ui addr>/auth/oidc-callback google
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
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
-list-claim-mappings flag maps the "groups" claim to be exposed
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
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.
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:
Look for an existing user account that is linked to exactly the user
(issuer ID, sub ID)tuple.
Look for an existing user account with an email address matching the
Create and link a new user with a random username.
Users of OIDC-created accounts can modify their account details
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.
- Help: https://developers.google.com/identity/protocols/oauth2/openid-connect
- Issuer URL:
- 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.
- Help: https://developer.okta.com/docs/reference/api/oidc/
- Issuer URL: