Application Settings

This guide explains how to configure an application from the ThunderID Console application details page.

Find Your Client ID

The Application ID and Client ID are shown on the application's General tab under Quick Copy. Use the copy button to grab them quickly.

• Application ID - the internal ThunderID identifier for this application.
• Client ID - the OAuth 2.0 identifier your SDK or client configuration needs.

Control Who Can Sign In

Under Access on the General tab, you can configure which users can register with this application and provide the application's URL and redirect URIs. The Allowed User Types and Authorized Redirect URIs settings apply to applications that let users sign in and are hidden for applications that use only the client_credentials grant.

Setting	Description
Allowed User Types	Restricts self-service registration to users of the selected types. If none are selected, self-service registration is unavailable for this application. This setting does not block existing users from signing in.
Application URL	The homepage URL of your application.
Authorized Redirect URIs	The URLs ThunderID sends users back to after authentication. Register every URI your application uses.

Use Wildcard Redirect URIs

ThunderID supports wildcard patterns in redirect URIs, so you can register a single pattern that covers a range of valid callback URLs instead of listing every exact URI.

note

Wildcard redirect URI support is disabled by default. A ThunderID administrator must set oauth.allow_wildcard_redirect_uri: true in deployment.yaml to enable it. See Configuration for details.

You can use * to match a single path segment or part of a hostname label, and ** to match zero or more path segments. For example:

• https://example.com/cb/*: matches https://example.com/cb/v1 but not https://example.com/cb/v1/extra
• https://app-*.example.com/cb: matches https://app-prod.example.com/cb and https://app-staging.example.com/cb

When the authorization request included a redirect_uri, the token endpoint validates it with exact matching per RFC 6749 §4.1.3: wildcard expansion does not apply at the token endpoint.

Configure Sign-In, Registration, and Recovery Flows

On the Flows tab, choose the flows that drive sign-in, sign-up, and password recovery for this application.

Authentication Flow - select the flow users follow to sign in. You can assign a custom flow built with the Flow Designer or use the deployment default. Use the open the flow builder link to edit the selected flow directly.

Registration Flow - toggle the switch to enable or disable self-registration. When enabled, select a flow that defines what information users must provide to create an account.

Recovery Flow - toggle the switch to enable or disable password recovery. When enabled, select a flow that guides users through the password reset process.

Customize the Appearance

On the Customization tab, control how your application looks and what legal links users see.

Setting	Description
Theme	The visual theme applied to authentication pages. Select Default Theme to use the shared deployment theme, or pick an application-specific theme.
Terms of Service URI	Displayed to users during consent, sign-in, sign-up, or recovery flows. When set, it must be a valid URI; otherwise the update is rejected with Invalid Terms of Service URI (APP-1040).
Privacy Policy URI	Displayed to users during consent, sign-in, sign-up, or recovery flows. When set, it must be a valid URI; otherwise the update is rejected with Invalid Privacy Policy URI (APP-1041).
Contacts	Administrator email addresses for this application. Separate multiple addresses with commas.

Configure What Goes Into Tokens

note

This section applies to OAuth 2.0 / OIDC applications (Browser App, Full-stack App, Mobile App, Backend Service, MCP Client, and Custom App). For applications that use the embedded sign-in approach, user attributes are configured in the assertion returned by the flow, not in tokens.

On the Token tab, configure what your application's tokens carry and how long they stay valid. The tab has two sub-tabs:

• User: the tokens issued when a user signs in. Available when the application supports a user sign-in grant, such as authorization_code.
• Application: the access token the application receives for itself through the client_credentials grant.

Each sub-tab stays read-only until its grant type is enabled on the Advanced Settings tab.

User Tokens

On the User sub-tab, choose which user attributes each token carries, how long tokens stay valid, and the response format for ID tokens and userinfo.

Access Token: select the user attributes to include in the access token payload. Default attributes (sub, iss, exp, and others) are always included and cannot be removed. Set Token Validity in seconds (for example, 3600 for one hour).

ID Token: select the user attributes to include. Only attributes covered by the requested scopes are returned. Set Token Validity in seconds.

You can also configure the ID token response format via the API. These settings are not available in the Console.

Setting	Description
Response Type	JWT (signed only, default), JWE (encrypted), or NESTED_JWT (signed then encrypted).
Encryption Algorithm	Key-management algorithm. Required for JWE and NESTED_JWT. Options: RSA-OAEP, RSA-OAEP-256. Requires an OAuth client certificate.
Encryption Encoding	Content-encryption algorithm. Required when Encryption Algorithm is set. Options: A128CBC-HS256, A256GCM.

User Info: configure what the /userinfo endpoint returns. User attributes are configurable from the Console. Response format settings are available via the API only.

Setting	Description
User Attributes	Attributes returned by the /userinfo endpoint. Enable Use same attributes as ID Token to mirror your ID token selection, or define a separate set.
Response Type	JSON (default), JWS (signed), JWE (encrypted), or NESTED_JWT (signed then encrypted).
Signing Algorithm	Required for JWS and NESTED_JWT. Options: RS256, RS512, PS256, ES256, ES384, ES512, EdDSA. Requires an OAuth client certificate.
Encryption Algorithm	Required for JWE and NESTED_JWT. Options: RSA-OAEP, RSA-OAEP-256. Requires an OAuth client certificate.
Encryption Encoding	Required when Encryption Algorithm is set. Options: A128CBC-HS256, A256GCM.

Application Token

On the Application sub-tab, configure the access token the application receives through the client_credentials grant. This token represents the application itself, so it carries no user attributes.

Claims: add the application's own claims to the token. The available claims are groups, roles, and the organization unit claims ouHandle, ouId, and ouName. Default claims (sub, iss, exp, and others) are always included and cannot be removed.

Token Validity: set how long this token stays valid, in seconds, independently of the user access token.

Rotate the Client Secret

note

Client secrets are only present on confidential clients: Full-stack App and Backend Service application types, and MCP Client or Custom App applications configured as confidential. This section does not apply to public clients such as Browser App, Mobile App, or an MCP Client or Custom App configured as public.

If you need to invalidate the current client secret, open the General tab and click Regenerate Client Secret in the Danger Zone.

warning

The current client secret is immediately invalidated. Any running clients using the old secret will lose access. Update your application configuration right away.

Review OAuth 2.0 Configuration

note

This section applies to OAuth 2.0 / OIDC applications only.

The Advanced Settings tab shows the OAuth 2.0 settings configured at creation.

Setting	Description
Grant Types	The OAuth 2.0 flows this application can use. Supported values: authorization_code, refresh_token, client_credentials, urn:ietf:params:oauth:grant-type:token-exchange, urn:ietf:params:oauth:grant-type:jwt-bearer. Whether this application can initiate flows directly via POST /flow/execute depends on its application type and, for Full-stack, Custom, and MCP Client applications, its grant configuration. See Direct Initiation Restriction for the full rule.
Response Types	The response types the application can request (for example, code).
Client Authentication Method	How the application authenticates at ThunderID's client-authenticated endpoints (token, introspection, revocation, PAR, and CIBA): client_secret_basic (default), client_secret_post, private_key_jwt, or none (public clients). See Client Authentication Methods.
Public Client	Whether this is a public client that cannot securely store a client secret.
PKCE Required	Whether the application must send a code_challenge in every authorization request. Always Yes for public clients.

You can also attach a Certificate for client authentication (private_key_jwt) or token/userinfo encryption.

Certificate Type	Description
None	No certificate configured.
JWKS	Provide the JSON Web Key Set (JWKS) inline.
JWKS_URI	Provide the URL of the application's JWKS endpoint. ThunderID fetches the public keys to verify signed requests. Must use HTTPS.

For full protocol-level details, including ACR values, scope-to-claims mapping, PAR enforcement, and token signing and encryption algorithms, see the OAuth & OIDC catalogue.

Configure Platform Attestation

Mobile applications cannot safely hold a Flow Secret, so they prove their identity a different way: by presenting a platform attestation token. ThunderID supports Google Play Integrity for Android clients and Apple App Attest for iOS clients. See Attestation for how this fits into the App-Native integration model. Attestation is optional; when enabled, an application configures exactly one platform, from its Advanced tab or via the top-level attestation block in a declarative resource.

Android (Google Play Integrity)

Configure the Android platform under the attestation.android block:

Setting	Description
Package Name	The Android application package name (for example, com.example.myapp) that must match the attested app.
Signing Certificate SHA-256 Digests	One or more allowed signing certificate digests, in the URL-safe base64 form reported by Play Integrity. The attested app must match one of these.
Service Account Credentials	The Google Cloud service account JSON used to call the Play Integrity API. It is write-only: ThunderID never returns it in responses, and leaving it blank when editing keeps the stored value.

note

The service account credentials are stored encrypted and never returned. For an app managed declaratively, set the serviceAccountCredentials field in the attestation.android block. On update, omit it to preserve the previously stored value.

iOS (Apple App Attest)

Configure the iOS platform under the attestation.apple block. Verification runs entirely on the server: ThunderID validates the attestation certificate chain against Apple's App Attest root certificate authority, then checks the attested app against the registered identity. This platform uses only non-secret identifiers, so nothing is stored write-only.

Setting	Description
Team ID	The Apple Developer Team ID (for example, ABCDE12345).
Bundle ID	The iOS application bundle identifier (for example, com.example.myapp) that must match the attested app.

The trust anchor used to validate the attestation certificate chain is a server-level setting, shared by every application, rather than a per-application one. It is configured under the attestation.apple.root_certificate key in deployment.yaml and holds the PEM-encoded Apple App Attestation Root CA certificate. ThunderID ships the public Apple root as the default in config/default.json, valid until 2045, so no configuration is required to verify iOS attestations out of the box.

note

Override this only if Apple publishes a new App Attestation Root CA. To do so, add the replacement certificate to deployment.yaml, which takes precedence over the shipped default:

attestation:
  apple:
    root_certificate: |
      -----BEGIN CERTIFICATE-----
      <your PEM-encoded certificate>
      -----END CERTIFICATE-----

Dev Mode

Configuring attestation.android or attestation.apple requires a signed build with the exact package name, signing certificate, or bundle identifier registered above. A sample application or a local development build usually cannot produce a valid attestation. Dev Mode lets a Mobile application initiate a flow directly without presenting an attestation token, regardless of whether an Android or iOS platform is configured. Enable it from the toggle in the Platform Attestation card header, or set attestation.devMode to true in a declarative resource. Dev Mode is disabled by default.

warning

Dev Mode skips the platform-attestation check only when this application initiates a flow directly. It does not affect any other application operation. Use it only for testing, or to try out a sample or development client. Disable it before the application goes to production.

Related Guides

• Manage Applications - Create, update, and delete applications
• OAuth & OIDC - Protocol-by-protocol reference for OAuth 2.1 and OpenID Connect features
• Flows - Build and assign custom authentication and registration flows