This document relates to Chainguard Enforce, which you will need access to in order to follow along. You can request access through selecting Chainguard Enforce on our inquiry form.
Chainguard Enforce currently offers login and authentication through three different OpenID Connect identity providers: Google, GitHub, and GitLab. OpenID Connect (OIDC) provides an identity layer on top of the OAuth 2.0 protocol, and it is integrated with both the Chainguard Enforce Console web browser interface and chainctl on the command line. This document will walk through both of these workflows.
Once you have access to Chainguard Enforce, you can navigate a web browser to console.enforce.dev. A sign in page will be displayed, similar to the one below.
From here, you have three options to authenticate in to the Console via one of the following OIDC providers:
To authenticate with Google (including through a Google-based email), click the Google button, and then select the specific Google account you would like to use to log in to chainguard.dev. Note that you may need to log in to your Google account.
From here, you’ll sign in to Chainguard Enforce through Google, and will then be brought to the Enforce Console homepage.
To authenticate with your GitHub username, click the GitHub button. You may need to log in to your GitHub account at this point. When you are logged in, review the permissions page and confirm that you would like to authorize Chainguard Enforce.
If you are satisfied with allowing Chainguard Enforce to have the stated permissions, you’ll authorize it by clicking on the Authorize Chainguard Enforce button, and then sign in through GitHub. You’ll then be brought to the Chainguard Enforce Console homepage.
To authenticate via GitLab, you’ll be prompted to sign in to GitLab if applicable, and then be asked to authorize Chainguard Enforce to use your GitLab account.
As long as you are satisfied with granting Chainguard Enforce the permissions to your GitLab account, you can click on the Authorize button. Next, you’ll be brought to the Chainguard Enforce Console homepage.
At this point, you are logged in to Chainguard Enforce and will have access to your Chainguard Enforce account through the Console.
When using chainctl, you can initiate the login flow through the chainctl auth login command.
chainctl auth login
When you run this command, you’ll receive output similar to the following on your command prompt.
Your browser will now be opened to:
https://auth.chainguard.dev/authorize?access_type=online&client_id=<RELEVANT ID HERE>
This will trigger a page to open on your default web browser. If this does not occur, you can copy the full URL on your terminal output and paste it in to a browser address bar.
At this point, your browser will display a login page similar to the following.
With chainctl, you’ll have the option to log in with one of the following OIDC providers:
If you will be authenticating with Google, click the Google button, and then select the specific Google account you would like to use to log in to chainguard.dev. Note that you may need to log in to your Google account.
From here, you’ll sign in to Chainguard Enforce through Google and then receive a confirmation page that reads Chainguard Auth Successful. At this point, you can close the browser window and return to the command line to continue working with chainctl.
Chainguard Auth Successful
To authenticate with your GitHub username, click the GitHub button. You may need to log in to your GitHub account at this point. When you are logged in to GitHub, review the permissions page and confirm that you would like to authorize Chainguard Enforce.
If you are satisfied with allowing Chainguard Enforce to have the stated permissions, you’ll authorize it by clicking on the Authorize Chainguard Enforce button, and then sign in through GitHub. Next, you’ll receive a confirmation page in your browser that reads Chainguard Auth Successful, and you may now close the browser window and return to the command line.
As long as you are satisfied with granting Chainguard Enforce the permissions to your GitLab account, you can click on the Authorize button. Next, you’ll be brought to a confirmation page that reads Chainguard Auth Successful. You may now close the browser window and can return to the command line to continue using chainctl.
Once you return to the terminal window, you’ll also be able to review the output that indicates that you have successfully logged in to Chainguard Enforce via chainctl:
Successfully exchanged token.
Valid! Id: <Relevant ID here>
You are now logged in to Chainguard Enforce and can use chainctl for your account.
You can use another device (typically a smartphone) to authenticate and log in to Chainguard Enforce when you cannot access your present working device’s browser. For instance, perhaps your present device is a container or a cloud virtual machine that doesn’t have browser access.
To authenticate, you will browse to the provided URL on an alternate device.
First, authenticate with chainctl. In this workflow, we are assuming you are not able to access a browser, so you may be authenticating from a virtual machine or container.
chainctl auth login
You’ll receive output that the device’s browser could not open, and be provided with a URL to authenticate.
Error opening browser. Switching to device flow...
Enter the verification code FTFD-ZVTV in your browser at: https://auth.chainguard.dev/activate
Code will be valid for 900 seconds
When you navigate to https://auth.chainguard.dev/ with your smartphone or other device, you’ll receive a screen with a field to enter the verification you were given in the terminal output.
Once you enter the verification code and complete the workflow by pressing the Continue button, you’ll receive terminal output that indicates that the token was successfully exchanged.
Successfully exchanged token.
Valid! Id: af641...
You are now authenticated to Chainguard Enforce.
If you find yourself frequently logging into Chainguard Enforce with chainctl, you may find it helpful to set a default authentication provider. This means that instead of having to select your OIDC provider (Google, GitHub, or GitLab) every time after logging in, you can be taken directly to the default authentication provider’s login flow.
To set a default authentication provider, you can edit the chainctl configuration file with the following command.
chainctl config edit
This will open a text editor (nano, by default) where you can edit the local chainctl config. Add the following lines to this file.
default: social-login: google # (or github or gitlab)
Then save and close the file. If you used the default editor, nano, you can do so by pressing CTRL + X, Y, and then ENTER.
CTRL + X
You can also set this with a single command using the chainctl config set subcommand. The following example sets GitLab as the default provider.
chainctl config set
chainctl config set default.social-login gitlab
Once set, the configured authentication provider will be used automatically any time you run chainctl auth login.
If you ever need, you can remove the default setting with the chainctl config unset subcommand.
chainctl config unset
chainctl config unset default.social-login
Property "default.social-login" unset.
Check out the chainctl config documentation for more details on how you can manage the chainctl configuration.
To learn more about how to work with Chainguard Enforce, you can review our User Onboarding tutorial. If you would like to learn more about the Chainguard Enforce Console, you can read How to create policies in the Chainguard Enforce Console. You can also review the full chainctl reference documentation to learn more about our command line tool.