Application Management

Creating, configuring, and managing applications in Orion

Back to Documentation

What is an Application?

An Application in Orion represents any service, website, or API that needs to authenticate users or make authenticated requests. Applications belong to an Organisation and serve as the primary unit of configuration for authentication, authorization, and OAuth.

Key properties of an application:

  • Name — Human-readable display name
  • PublicId — A GUID that uniquely identifies the application. Also serves as the OAuth client_id.
  • Description — Shown to users during permission/consent screens
  • IsAutoRegister — Whether users are automatically granted access without explicit permission
  • IsRoamingEnabled — Legacy federation only: whether users from other organisations can sign in through the legacy (HMAC) federation login. It has no effect on OAuth sign-in.
  • SignInAudience — Who can sign in over OAuth: members of the application's organisation only (the default), or members of any organisation on this server once their organisation allows it. See Who can sign in.
  • IsDiscoverable — Whether the app appears in the Application Directory
  • IsOAuthEnabled — Whether OAuth 2.0/OIDC is active for this application

Creating Applications

Applications are created via the Management UI by organisation administrators.

1

Navigate to Applications

Go to Account Manager → Manage Applications

2

Fill in the application details

Provide a name, description, and select the required permission policy (what data the app needs access to).

3

Configure options

  • Enable Auto Register if you want all org users to have automatic access
  • Enable Roaming if users from other organisations should be able to sign in through the legacy federation login (for OAuth, use Who can sign in)
  • Enable Discoverable to list the app in the organisation directory
4

Save the application

After creation, note the PublicId shown in the Application Manager. This is your client_id for OAuth and the ApplicationId for the SDK.


Enabling OAuth

OAuth is configured per application. To enable it:

1

Open the Application Manager

Go to Applications → click on your app.

2

Toggle OAuth Enabled

Check the "Enable OAuth" checkbox in the OAuth section.

3

Configure OAuth settings

  • Redirect URIs: Space-separated list of allowed redirect URIs for the authorization code flow
  • Post-Logout Redirect URIs: Where to redirect after end_session
  • Allowed Grant Types: Which grant types this client can use (space-separated)
  • Allowed Scopes: Which scopes this client can request
  • Require PKCE: Whether PKCE is mandatory (recommended: yes)
  • Require Consent: Whether users see a consent screen
  • Access Token Lifetime: Seconds until the access token expires
  • Refresh Token Lifetime: Seconds until the refresh token expires
4

Generate a client secret (confidential clients)

For server-side applications, generate a client secret. The secret is shown only once — store it securely.


Who Can Sign In

The Application Manager's Who can sign in panel decides who may sign in to the application over OAuth:

  • Members of this organisation only (the default, and every existing application).
  • Members of any organisation on this server, once their organisation allows it. Each organisation decides for its own members: an administrator approves the application, or the organisation lets its members consent for themselves, or blocks applications of other organisations (see OAuth → Consent Model).

Before choosing "any organisation", know what it means for the application:

  • Tokens for members of other organisations are issued by your organisation's issuer and signed with its key, but org_id, roles and the other claims describe the member's own organisation. The application must check org_id in every token, key accounts on sub, and never find or merge an account by email (see Security).
  • The application's sign-in page no longer creates accounts or offers "Create account".
  • The client ID must be unique on the server, ignoring case: other organisations' administrators approve the application by it. An application whose client ID another application also uses cannot be switched; create a new application instead.
  • Redirect URIs, client secrets, PKCE and allowed scopes stay under your organisation's control. Access roles apply to your own members only.
  • Widening a scope the application requests, or asking for a new one, needs every approving organisation to approve again. Allowing a scope on the application before requesting it lets approvals given from then on cover it.

Saving asks for a confirmation either way. Switching back to "this organisation only" signs members of other organisations out at once (refresh tokens, Verified references and pending sign-ins are revoked); their organisations' approvals are kept and apply again if you switch back. The management portal always serves members of every organisation and is not set here. A platform operator can turn the feature off for the whole server with ORION_MULTI_ORG_APPLICATIONS=false (see Configuration).


System Accounts

System accounts provide machine-to-machine authentication for your application. Each system account has a Public Key and a Secret Key used for HMAC authentication.

Creating a System Account

In the Application Manager, click Generate New System Account. Both keys are shown immediately — the secret key is only displayed once.

// Example keys (for illustration only)
Public Key:  a1b2c3d4-e5f6-7890-abcd-ef1234567890
Secret Key:  LXg0YTFiMmMzZ...base64...encoded

Cross-Application Permissions

By default, a system account can only access data within its own application. To grant access to other applications, use Manage Permissions on the system account and grant access to the target application.


Redirect URI Configuration

Redirect URIs are validated during the OAuth authorization flow to prevent open redirect attacks.

  • Exact match: By default, redirect URIs must match exactly (including path, no query string).
  • Multiple URIs: Space-separate multiple URIs in the configuration field.
  • Wildcard domains: If ORION_ALLOWED_REDIRECT_DOMAINS is set, redirect URIs matching those patterns are allowed server-wide.
  • Localhost: http://localhost URIs are accepted during development (any port).
  • Orion's own host: only the management portal may redirect to Orion's own host without registering the URI. Any other application must register it, and when ORION_ALLOWED_REDIRECT_DOMAINS is set, Orion's host must be in that list.

Permission Policies

Each application has a permission policy that defines what data access the application requires. Users must accept this policy before they can access the application.

  • Policies are versioned — changing requirements creates a new policy version
  • When a policy is updated, all existing permission grants are revoked and users must re-consent
  • Policies are shown to users during the permission grant screen

Application Directory

The Application Directory (Account Manager → App Directory) shows all discoverable applications across all organisations. Organisation administrators can use this to:

  • Browse available applications
  • Grant system account permissions to third-party applications
  • View application details and permission requirements

To make your application appear in the directory, enable Discoverable in the application settings.

← OAuth 2.0 Next: Setup →