OpenID Connect (OIDC)
Warning
This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.
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:
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 forwaypoint 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.
To set the UI-based URL when setting up your auth method, add the allowed-redirect-uri
flag:
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:
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:
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
email
claim. This is only done if the identity provider specifiesemail_verified
as true.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.
- 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}/