Use Registry Mint with QGIS and standard OAuth clients

Register a managed QGIS installation or another standard OAuth client with Registry Mint, then let the client obtain a new short-lived access token without an operator copying bearer tokens.

When to use this

Use this compatibility profile for a managed client that supports the OAuth 2.0 Client Credentials grant but cannot sign a private_key_jwt assertion. Register each installation separately so one credential can be revoked without interrupting every client.

This profile identifies the client installation, not the person using it. Use an institution identity provider when Relay authorization must follow a person’s login, role, or employment status.

Registry Mint keeps private_key_jwt as the default authentication method. A registration enables client-secret authentication only when its clientAuthentication.method is client-secret.

Before you start

You need:

• A Registry Mint deployment with one exact Relay audience and an access-token lifetime of 900 seconds or less.
• A protected Relay access profile whose required scope is known.
• An owner-only location for the generated client secret.
• Transport Layer Security (TLS) endpoints for Registry Mint and Registry Relay.

Generate one installation secret

Generate 32 random bytes, write the printable secret to an owner-only file, and print only its SHA-256 fingerprint:

mint client-secret generate --out "<owner-only-client-secret-file>"

sha256:<64-lowercase-hex-characters>

The command refuses to replace an existing file. The fingerprint is not a credential and belongs in the client registration. Keep the generated file outside Git, deployment configuration, logs, and shell history.

Register the client installation

Create one file under clients.directory:

clientId: qgis-jeremi-laptop
principal: urn:example:managed-client:qgis-jeremi-laptop
authorization:
  scopes:
    - registry:qgis:premises:read
clientAuthentication:
  method: client-secret
  secretFingerprints:
    - sha256:<fingerprint-from-generation>

Do not add keys to this registration. Client-secret and private_key_jwt authentication cannot be combined in one client entry. Registry Mint reads the scope and principal from the registration; the token request cannot add, replace, or widen either value.

Check the deployment and reload the client registry:

mint check --config /etc/mint/mint.yaml
kill -HUP "$(pgrep -x mint)"

The existing registry remains active when the edited registration fails to load.

Test the token exchange

Ask curl to prompt for the secret so the value does not enter shell history:

curl -sS --user qgis-jeremi-laptop \
  -d grant_type=client_credentials \
  https://mint.example.org/token

Enter host password for user 'qgis-jeremi-laptop':

After you enter the generated value, Registry Mint returns a standard token response:

{
  "access_token": "<short-lived-token>",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "registry:qgis:premises:read"
}

Registry Mint does not issue a refresh token for Client Credentials. The client obtains another short-lived access token with the same installation credential when the current token expires. QGIS implements the Client Credentials exchange as a form-body request. Its OAuth2 network request hook detects the expiring token, unlinks a session that has no refresh token, and links again before applying authentication to the next layer request. For this grant, linking again performs another Client Credentials exchange.

Configure QGIS

1. Open Settings > Options > Authentication.
2. Set a QGIS master password if the authentication database is not initialized.
3. Add an authentication configuration named Relay QGIS reader.
4. Select OAuth2 as the authentication method.
5. Select Client Credentials as the grant flow.
6. Set the token URL to https://mint.example.org/token.
7. Set the client ID to qgis-jeremi-laptop.
8. Enter the value from the owner-only client-secret file.
9. Leave scope empty. Registry Mint assigns the registered scope.
10. Select Header as the access method and save the configuration.
11. Create the OGC API Features connection with the Relay base URL and select Relay QGIS reader as its authentication configuration.

The QGIS project stores an authentication-configuration identifier. It does not need the client secret or an access token in the project file. Protect the QGIS authentication database and its master-password or operating-system keychain configuration as credentials for this installation. See the official QGIS authentication system overview for its authentication-database and OAuth2 boundaries.

Rotate or revoke the installation

Generate a second secret and add its fingerprint to secretFingerprints. At most two fingerprints are accepted so an overlap cannot become an unbounded collection of old credentials. Reload Registry Mint, update QGIS, remove the old fingerprint, and reload again.

To revoke the installation, remove its registration and reload Registry Mint. New token requests fail immediately. A token already issued remains valid until its bounded expiry, which is why the standard authorization profile cannot exceed 900 seconds.

Verify renewal and revocation

Leave the QGIS connection open through two access-token expiry boundaries and reload the layer after each one. Both reloads must succeed without pasting a bearer token.

Remove the client registration, reload Registry Mint, and reconnect after the last issued token expires. QGIS can no longer discover or load the protected collection. Restore the registration only if the installation remains authorized.

Troubleshooting

Symptom	Cause	Fix
Registry Mint returns invalid_client	The client ID, secret, authentication method, or registration does not match.	Confirm the per-installation registration and enter the generated secret again. The response does not distinguish which credential fact failed.
Registry Mint refuses the registration	The fingerprint is malformed, keys is also present, or the authority profile is not standard authorization.	Use the exact generated sha256: value, omit keys, and configure authorization.
QGIS receives a token but Relay returns 404	The registered scope does not authorize that concealed Relay resource.	Register the exact scope from the Relay access profile and reload Registry Mint.
QGIS works, then prompts after expiry	The OAuth configuration is not retaining the installation credential or cannot repeat Client Credentials.	Reopen the QGIS authentication configuration, confirm Client Credentials and Header access, then save it in the authentication database.
Every installation stops during rotation	Multiple installations shared one registration or the old fingerprint was removed before clients moved.	Give each installation a unique registration and keep no more than two fingerprints during a planned overlap.

Next

• Configure Registry Mint for service signing, token policy, audit retention, and client registry reloads.
• Request an access token from your own code when the client can use the preferred private_key_jwt method.
• Registry Mint reference for the complete registration and HTTP contract.