Internal Applications

Beak IAM can be the one place staff sign in to reach every internal tool, not only the Beak products customers use. An internal application is registered under Platform → Internal Apps, gets its own sign-in client, and appears in an Internal section of the product selection screen for the people granted it.

Internal applications are deliberately not products. They live in a separate registry, belong only to a tenant marked Internal, and are invisible to every customer tenant: a customer administrator has no page for them, a customer user's selection screen never shows the section, and a customer's sign-in can never be accepted by one.

Products and internal applications are different things

	Beak products	Internal applications
Who they are for	Customers and Beak staff	Beak staff only
Where they are managed	Platform → Products	Platform → Internal Apps
Who may own them	Every tenant sees the same catalogue	Only a tenant of kind Internal
How access is granted	Through roles and their product codes	Person by person, or opened to every member of the internal tenant
Sign-in client	One shared client per tenant	One client per application
On the selection screen	Product tiles, with products you cannot open shown disabled	A separate Internal section, shown only when you have at least one

Nothing about products changes when internal applications are introduced. The Products and Product Groups pages, role product codes and the product tiles behave exactly as before.

Mark a tenant as internal

Internal applications can only belong to a tenant of kind Internal. Every tenant is a Customer tenant until a platform super administrator changes it.

Open Platform → Tenants and select the tenant Beak staff sign in to.
Next to the tenant's status badge, choose Change kind… — only a super administrator sees this action.
Confirm. The change is recorded in the audit log.

The tenant's products and users are unaffected. Its members keep signing in to Beak products exactly as before; the kind only decides whether the tenant may own internal applications.
Changing back is refused while the tenant still owns internal applications. Delete them first.
The tenant creation wizard never sets the kind. A new tenant is always a customer tenant.

Note: The internal tenant should sign in through the company identity provider rather than local passwords. Internal applications send every sign-in straight to the identity provider — see Only granted members can sign in.

Register an internal application

Open Platform → Internal Apps and choose Register App.
On General, pick the internal tenant and give the application a Name, a Code and its Launch URL. The code is a permanent lowercase identifier (letters, digits, hyphens); it becomes the sign-in client's identity, beak-int-<code>. Optional fields: description, category, icon, owner team and sort order.
On Sign-in & access, choose the Authentication mode:
- Beak service — for a service built by Beak that validates sign-ins with beakiamauthlib. A public client using PKCE; there is no secret.
- Third-party OIDC — for a tool such as Grafana, Argo CD, Backstage or Kibana that speaks standard OpenID Connect. A confidential client with a secret.
Add the Redirect URIs the application will use for its sign-in callback, one per line. A wildcard entry is refused; a trailing /* on a path is accepted.
Choose Register.

For a Third-party OIDC application the client secret is shown once, immediately after registration. Copy it into the tool's configuration straight away; Beak IAM does not store it and cannot show it again. If it is lost, use Rotate secret on the application's OIDC configuration panel to issue a new one.

Name, launch URL, redirect URIs, owner team and sort order can be edited later. The code, the owning tenant and the authentication mode are fixed once registered.
Deactivating an application disables its sign-in client, so nobody can sign in until it is activated again. Deleting it removes the client, its login flow and every grant.
Registration is all-or-nothing. If the identity platform cannot be reached part-way through, whatever was created is removed and the application is not registered.

Grant and revoke access

Open the application's Grants action (the people icon on its row).

Grant — search the internal tenant's users by email or name and select one. Only users of the internal tenant can be found; a customer tenant's user can never be granted an internal application.
Revoke — choose the revoke action beside a granted user. Their next sign-in to the application is refused; an existing session ends when it next has to renew.
Open to all members of the tenant — a switch on the application's Sign-in & access tab. When on, every member of the internal tenant can sign in without an individual grant, and the row carries a warning badge. It is off by default and is meant for genuinely all-staff tools such as an intranet.

Granting, revoking and the open-to-all switch need the internal_apps:grant permission; the built-in Global Administrator role holds it. These permissions exist only on global-scoped administrator roles — a tenant-scoped role cannot carry them, and the console refuses to save one that tries.

Each internal application signs users in through its own client, with a login flow that:

Accepts an existing single sign-on session, so a staff member who is already signed in to a Beak product is not asked for credentials again.
Sends anyone who is not signed in straight to the company identity provider. No local password form is shown for an internal application.
Refuses the sign-in unless the user holds the application's access grant, even when they already have a valid session. The refusal is enforced by the identity platform itself, so it protects third-party tools that know nothing about Beak.

A customer tenant's users are further away still: their sign-in realm has no client for any internal application, so there is nothing for them to sign in to.

Configure a third-party tool

The OIDC configuration action (the key icon on the application's row) shows everything a standard OpenID Connect client needs, each with a copy button:

Issuer and Discovery URL — the tool reads its endpoints from here.
Client ID — beak-int-<code>.
Authorization, token and JWKS endpoints — for tools that want them spelled out.
Redirect URIs — the ones you registered.
Rotate secret — issues a new client secret and shows it once. The previous secret stops working immediately.

Configure the tool's own role mapping as you normally would; the identity platform has already refused anyone who is not granted before the tool sees them.

Protect a Beak-built service

A service written by Beak validates its sign-ins with beakiamauthlib. For an internal application, configure the library's internal mode:

from beakiamauthlib import configure

configure(
    audience="internal",
    trusted_issuers=["https://<your-iam-host>/iam/realms/<internal-tenant>"],  # exactly one realm
    client_id="beak-int-<code>",
    tenant_resolver=lambda realm: 1,
    users_schema="<your schema>",
    db=get_pool,
)

Internal mode is stricter than the product mode used by Beak products, and it fails closed:

Only the exact issuer is trusted. The base-URL wildcard that lets a product accept every tenant realm is ignored; a sign-in from any other realm — every customer realm included — is rejected.
The token must be issued for this application (aud contains the client ID) and carry its access grant (the client role access).
A missing claim is a refusal, never a pass. The library refuses to start if product-mode settings such as product_code are combined with internal mode.

Read the copyable values for trusted_issuers and client_id from the application's OIDC configuration panel.

What staff see

A staff member with at least one granted internal application sees an Internal section beneath the product tiles on the selection screen, marked with an Internal badge and grouped by the categories you gave the applications. Someone with no internal applications — every customer user — sees nothing extra, not even the heading.

Opening an internal application sends the browser to its launch URL in the same tab; the application then signs the user in through its own client, which is silent when a single sign-on session already exists.
A staff member with one product and one internal tool sees the selection screen rather than being sent straight into the product, because they have two places to go.
The section is refreshed at sign-in, like the product tiles. A grant made while someone is signed in appears after their next sign-in.

What customers can and cannot see

Nothing on the selection screen. The Internal section is not rendered, and the request that feeds it returns an empty list without consulting the registry at all.
Nothing in the admin console. The Internal Apps page is in the Platform section, which tenant administrators never see, and its permissions cannot be placed on a tenant-scoped role.
No sign-in. No client for any internal application exists in a customer tenant's realm, and a Beak-built internal service rejects any token that is not from the internal realm.
No grant. A grant can only name a user of the application's own internal tenant; the console, the service and the database each refuse anything else.

Best Practices

Keep one internal tenant. Mark the tenant Beak staff already use for products as internal, rather than creating a second staff realm; the single sign-on session then covers products and internal tools alike.
Grant by person and keep "open to all" rare. Reserve the switch for tools every employee genuinely needs, and review the applications carrying its warning badge.
Rotate a third-party secret when the people who saw it change. The old secret stops working the moment a new one is issued.
Give each application an owner team. It is shown on the row and in exports, and tells the next administrator who to ask before deactivating or deleting it.

Products and internal applications are different things​

Mark a tenant as internal​

Register an internal application​

Grant and revoke access​

Only granted members can sign in​

Configure a third-party tool​

Protect a Beak-built service​

What staff see​

What customers can and cannot see​

Best Practices​

Related Pages​