SWITCHAUTHMODE utility

You use the SWITCHAUTHMODE utility on the OpenEdge Command Center server host to store and activate authentication configurations, and to return to local authentication when required.

Syntax

switchauthmode --list
switchauthmode --add
switchauthmode --activate <configuration-name>
switchauthmode --remove <configuration-name>
switchauthmode --activate local

When you run SWITCHAUTHMODE --ADD, the utility prompts you to enter the following configuration values interactively, one at a time:

  • configuration name
  • provider (entra, okta, or keycloak)
  • issuer URL
  • client ID
  • client secret
  • redirect URI
  • scope, including the custom API scope value
  • roles claim path (optional)
CAUTION: Use SWITCHAUTHMODE --REMOVE only to delete a stored but inactive configuration.

List and remove configurations

To review the stored configurations, including the active one, run:

switchauthmode --list

To delete a stored configuration that is not active, run:

switchauthmode --remove "Dev Okta"
Note: To delete the active configuration, first activate another configuration.

Parameters

Parameter Required Description
--list No Lists the stored authentication configurations and identifies the active one.
--add No Stores a configuration. The configuration is inactive until you activate it.
--activate No Activates a named configuration. Restart the server to apply the change.
--remove No Deletes the named configuration. You cannot delete the active configuration.
--name Yes, with --add Name of the configuration, for example, Company Entra ID. Name is the key that you use to activate or remove the configuration.
--provider Prompted if omitted Identity provider type. The supported values are entra and okta.
--issuerUrl Yes, with --add OIDC issuer URL. OpenEdge Command Center reads the endpoints of the identity provider from the OpenID Connect discovery document that is published at this URL, so you do not configure those endpoints individually.
--clientId Yes, with --add Application or client ID from the identity provider. The value is stored unencrypted.
--rolesClaimPath No (optional) Specifies the claim path in the IdP access token that contains the user’s assigned roles.
--clientSecret Yes, with --add Client secret from the identity provider. The value is stored in encrypted form.
--redirectUri Yes, with --add Callback URL of the OpenEdge Command Center server. The value must match the redirect URI that is registered in the identity provider exactly. The path is /api/auth/callback.
--apiScope No Custom API scope that makes the identity provider issue a JWT access token that contains a roles claim. Required for both Microsoft Entra ID and Okta.
--scope No Space-separated OpenID Connect scopes requested from the identity provider. The default is openid profile email offline_access.

Notes

  • The utility must run with root privileges on Linux, or with Administrator privileges on Windows, otherwise it exits with an error and makes no change.
  • The utility is available only on the OpenEdge Command Center server host. The authentication mode cannot be changed from the interface or from the REST API.
  • Activating a configuration does not take effect until you restart the OpenEdge Command Center server.
  • Activating an identity provider configuration sets all users to inactive, and activating the local configuration restores them and requires each user including admin to set a new password.

Roles claim path: Nested-scenario examples

The rolesClaimPath is an optional field. It specifies the path to the claim that contains the user’s roles in the access token. It uses the dot-notation syntax, so it can reference nested objects and array elements. This value is useful when the roles are not stored in a default claim such as roles, resource_access.<clientId>.roles, or realm_access.roles.

Example 1: One level of nesting

Token:

{
  "custom_claims": {
    "app_permissions": ["role:oecc/oecc_admin"]
  }
}

Path:

custom_claims.app_permissions

Example 2: Per-client nesting with the {clientId} placeholder

Token:

{
  "app_access": {
    "oecc-server": {
      "roles": ["role:oecc/oecc_admin"]
    }
  }
}

Path:

app_access.{clientId}.roles

At run time, this path resolves to app_access.oecc-server.roles by using the client ID from the same configuration.

Example 3: Nested object with an array index

Token:

{
  "groups": [
    {
      "name": "primary",
      "roles": ["role:oecc/oecc_admin"]
    }
  ]
}

Path:

groups[0].roles

If none of these paths resolves, for example because of a typo or because the claim is not present in a given token, OpenEdge Command Center falls back to the built-in claim shapes (roles, resource_access.<clientId>.roles, and realm_access.roles) automatically. It does not fail or error out.

Examples

Add and activate a Microsoft Entra ID configuration

The --add command creates an OIDC configuration and prompts for its values interactively.
switchauthmode --add

Then provide the following values when prompted:

Configuration name: Company Entra ID
Provider: entra
Issuer URL: https://login.microsoftonline.com/<tenant-id>/v2.0
Client ID: <Application (client) ID>
Client secret: <Client secret value>
Redirect URI: https://<oecc-server>:<port>/api/auth/callback
Scope: api://<client-id>/<exposed-custom-scope>
Roles claim path: optional, for example app_access.{clientId}.roles

Then run:

switchauthmode --activate "Company Entra ID"

Add and activate an Okta configuration

  1. Add and activate an Okta configuration that uses a custom authorization server:
    switchauthmode --add
  2. Provide the following values when prompted:
    Configuration name: Dev Okta
Provider label: okta
Issuer URL: https://<your-okta-domain>.okta.com/oauth2/<authServerId>
Client ID: <Okta client ID>
Client secret: <input hidden — not echoed>
Redirect URI: https://<oecc-server>:<port>/api/auth/callback
Scope: <custom-scope-name> and optional OIDC scopes, such as openid profile email offline_access
Roles claim path: optional
  3. Run the following:
    switchauthmode --activate "Dev Okta"