dpsctl login#

Overview#

Use dpsctl login to sign in and store credentials for later DPS API requests. In LDAP mode, use a username and password. In OIDC mode, use browser sign-in through the device authorization flow. Your administrator provides the configured mode and connection settings. Refer to Configure Server Authentication for server setup.

Usage#

Run the command with the global endpoint and TLS options for your deployment:

dpsctl login [flags]

Flags#

The command accepts global options and the following login options:

   --username string, -u string  The username to use to authenticate to DPS [$DPSCTL_USERNAME]
   --password-stdin              Read password from stdin (e.g. printf '%s\n' 'pass' | dpsctl login -u user --password-stdin) (default: false)
   --id-token                    Use the OIDC ID token for requests to DPS from this browser login session (default: false)
   --help, -h                    show help

LDAP#

Log In with a Password Prompt#

In LDAP mode, login prompts for the username and password when no credentials are supplied or saved:

$ dpsctl login
Please enter the value for username: alice
Please enter the value for password:
{
  "status": {
    "ok": true,
    "diag_msg": "Login successful"
  }
}

Log In with a Password from Standard Input#

You can supply a password file from your secret-management workflow through standard input with an explicit username:

$ dpsctl login --username alice --password-stdin < /path/to/password-file
{
  "status": {
    "ok": true,
    "diag_msg": "Login successful"
  }
}

Log In with Environment Variables#

Set DPSCTL_PASSWORD through your secret-management workflow, and provide the username through an environment variable:

$ export DPSCTL_USERNAME=alice
$ dpsctl login
{
  "status": {
    "ok": true,
    "diag_msg": "Login successful"
  }
}

OIDC#

Browser Login#

Provide the issuer and client ID configured by your administrator. The interactive dpsctl client must be registered as a public client without a client secret. It sends no secret during token exchange. The provider must support the device authorization flow.

Use the following command to start browser login:

dpsctl --oidc-issuer https://idp.example.com/realms/dps \
  --oidc-client-id dpsctl \
  --oidc-oauth-scope dps:api login

Open the URL displayed by dpsctl, enter the displayed code if requested, and complete sign-in in your browser. Browser login contacts the provider directly. Set the DPS endpoint and TLS options on later API commands. dpsctl stores the access token for those requests. dpsctl uses a refresh token supplied by the provider to renew the access token when needed. If the session expires without a usable refresh token, repeat browser login.

Use --oidc-oauth-scope for the scopes required by your provider and API configuration. Refer to OIDC Browser Login for discovery, endpoint overrides, and certificate options.

Authorization with an ID Token#

API requests use the access token by default. Use --id-token only when your deployment’s API authorization configuration accepts an ID token:

dpsctl --oidc-issuer https://idp.example.com/realms/dps \
  --oidc-client-id dpsctl \
  --oidc-oauth-scope dps:api login --id-token

This option requests the openid scope automatically and stores the ID token for API requests from that session. It requires OIDC browser login without username/password options. Follow your administrator’s token requirements in Configure OIDC Mode.

Mutual TLS#

Certificate authentication requires no dpsctl login step. Supply the client certificate and key on API commands as described in Mutual TLS.

Notes#

The following details apply when you configure login:

  • dpsctl stores credentials in ${HOME}/.dpsctl/credentials.yaml by default.

  • Set --credentials-path to use a different file.

  • In LDAP mode, dpsctl uses a valid stored refresh token to renew expiring access tokens before API requests. Repeat dpsctl login if the refresh token is missing, expired, or no longer accepted.

  • A password supplied through --password-stdin or DPSCTL_PASSWORD requires --username or DPSCTL_USERNAME.

  • Providing username/password options selects the DPS password login flow, even when OIDC options are also configured.

  • OIDC browser login cannot be combined with client credentials. For unattended services, refer to Obtain a Service Account Token.

  • Successful login confirms authentication. A later API request can still fail authorization. Follow Verify the Configuration to check access.