The jwt auth method can be used to authenticate with Stronghold using OIDC or by providing a JWT.

The OIDC method allows authentication via a configured OIDC provider using the user’s web browser. This method may be initiated from the Stronghold UI or the command line. Alternatively, a JWT can be provided directly. The JWT is cryptographically verified using locally-provided keys, or, if configured, an OIDC Discovery service can be used to fetch the appropriate keys. The choice of method is configured per role.

Both methods allow additional processing of the claims data in the JWT. This page covers the concepts common to both methods and then the OIDC login flows.

OIDC authentication

This section covers the setup and use of OIDC roles. It assumes basic familiarity with OIDC concepts. The Authorization Code flow makes use of the Proof Key for Code Exchange (PKCE) extension.

Stronghold includes two built-in OIDC login flows: the Stronghold UI and the CLI (d8 stronghold login).

Redirect URIs

Unless you are using callbackmode=device, an important part of OIDC role configuration is properly setting redirect URIs. This must be done both in Stronghold and with the OIDC provider, and these configurations must align. The redirect URIs are specified for a role with the allowed_redirect_uris parameter. There are different redirect URIs to configure the Stronghold UI and CLI flows, so one or both will need to be set up depending on the installation.

CLI

If you plan to support authentication via d8 stronghold login -method=oidc and are not using callbackmode=device, a redirect URI with a path ending in oidc/callback must be set. With the default callbackmode=client, this is usually http://localhost:8250/oidc/callback. With callbackmode=direct, use a URI of the following form:

https://<HOST>:<PORT>/v1/auth/<MOUNT_PATH>/oidc/callback

Where:

  • <HOST>:<PORT> is the Stronghold server name and port;
  • <MOUNT_PATH> is the path the auth method is mounted at, for example, oidc or jwt.

Logins via the CLI may specify a different host and/or listening port if needed, and a URI with this host/port must match one of the configured redirect URIs. These same URIs must be added to the provider as well.

Stronghold UI

In Stronghold in DP, the redirect URIs for the Stronghold UI and the CLI are configured automatically when the stronghold module works in the Automatic management mode.

OIDC login (Stronghold UI)

To log in through the Stronghold UI, follow these steps:

  1. Select the “OIDC” login method.
  2. Enter a role name if necessary.
  3. Press “Sign In” and complete the authentication with the configured provider.

OIDC login (CLI)

By default, the CLI uses the oidc mount path. In Stronghold in DP, the method is mounted at oidc_deckhouse. If the auth method is mounted at a different path, specify it with the -path parameter.

  • Stronghold in DP
  • Stronghold in Linux
$ d8 stronghold login -method=oidc -path=oidc_deckhouse role=test

Complete the login via your OIDC provider. Launching browser to:

    https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&client_id=r3qXc2bix9eF...

$ stronghold login -method=oidc role=test

Complete the login via your OIDC provider. Launching browser to:

    https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&client_id=r3qXc2bix9eF...

The browser opens the generated URL to complete the provider’s login. The URL may be entered manually if the browser cannot be opened automatically. The skip_browser parameter (default: false) disables the automatic launch of the default browser.

The callback listener may be customized with the following optional parameters. These are typically not required to be set:

  • mount (default: oidc): the mount path of the auth method.
  • callbackmode (default: client): the callback mode:
    • client: a connection to a port on the CLI client;
    • direct: a direct connection to the Stronghold server;
    • device: the device flow, which has no callback.
  • listenaddress (default: localhost): only for the client callback mode.
  • port (default: 8250): only for the client callback mode.
  • callbackhost (default: the Stronghold server host in the direct callback mode, otherwise localhost).
  • callbackmethod (default: the scheme of the Stronghold server in the direct callback mode, otherwise http): the scheme to use in the OIDC redirect_uri.
  • callbackport (default: the port value in the client callback mode, otherwise the port of the Stronghold server followed by /v1/auth/<MOUNT_PATH>, where <MOUNT_PATH> is the value of the -path login option). This value is used in the redirect_uri, whereas port is the localhost port that the listener is using. These two may be different in advanced setups.

OIDC provider configuration

Register Stronghold as a client application with the OIDC provider and add the redirect URIs from the Redirect URIs section. Provider-specific guides: GitLab, Keycloak, Kubernetes.

OIDC configuration troubleshooting

Use the following tips to troubleshoot an OIDC setup:

  • If a role parameter (for example, bound_claims) requires a map value, it can’t be set individually using the Stronghold CLI. In these cases, write the entire configuration as a single JSON object:

    • Stronghold in DP
    • Stronghold in Linux
    d8 stronghold write auth/oidc/role/demo -<<EOF
{
  "user_claim": "sub",
  "bound_audiences": "abc123",
  "role_type": "oidc",
  "policies": "demo",
  "ttl": "1h",
  "bound_claims": { "groups": ["mygroup/mysubgroup"] }
}
EOF
    stronghold write auth/oidc/role/demo -<<EOF
{
  "user_claim": "sub",
  "bound_audiences": "abc123",
  "role_type": "oidc",
  "policies": "demo",
  "ttl": "1h",
  "bound_claims": { "groups": ["mygroup/mysubgroup"] }
}
EOF

  • Monitor the Stronghold log output. It contains information about OIDC validation failures.

  • Ensure that the redirect URIs in Stronghold and on the provider match exactly. Check: http/https, 127.0.0.1/localhost, port numbers, whether trailing slashes are present.

  • Start with a minimal configuration. The only claim configuration a role requires is user_claim. After authentication works, add claims bindings and metadata copying.

  • bound_audiences is optional for OIDC roles and typically not required. OIDC providers use the client_id as the audience, and OIDC validation expects this.

  • Check which scopes your provider requires to return all of the information you need. The profile and groups scopes often need to be requested. Add them by setting oidc_scopes="profile,groups" on the role.

  • If you see claim-related errors in the logs, check the provider’s documentation to see how it names and structures its claims. Depending on the provider, you may be able to construct a curl implicit grant request to obtain a JWT that you can inspect. To decode a JWT located in the access_token field of a JSON response, run:

    cat jwt.json | jq -r .access_token | cut -d. -f2 | base64 -d

  • The verbose_oidc_logging role option logs the received OIDC token to the server logs if debug-level logging is enabled. It helps to debug the provider setup and to verify the received claims. Claims data is logged verbatim and may contain sensitive information, so do not enable this option in production.

Additional resources

←
Auth methods / Overview
OIDC / Overview
→