Products and product grants API

What it is

A product is an application that a platform operator registers once, so that RealmSSO can grant it to accounts. A product grant lets one account use one product. The product grant is the permission. Registering a product provisions nothing.

A realm is the separate sign-in space that RealmSSO makes for each account. It has its own users, clients, identity-provider links and signing keys. The sign-in service keeps one client for each product grant, in the realm of the account that holds it. Everything below the realm is shared between accounts.

• Default deny. A product's client exists only in the realms of accounts that hold a product grant. A new realm receives only the product grants of its own account. Revoking a product grant removes the client from that realm.
• One client for each product grant. Provisioning a product grant gives the product a SAML client or an OIDC client of its own in that realm. The OIDC client ID is product-<slug>. No client is shared between accounts.
• One binding. The API accepts the redirect binding only.
• SAML audience. On the SAML leg, the assertion audience is the requesting product only. An automated test covers this. The test runs against the sign-in service, not against a real product.

No screen exists for customers or for product teams. This page is that surface. Platform operators also have the connector board. For the idea behind products, see Identity Gateway. For how accounts and realms relate, see Accounts and isolation.

Who can call it

A platform operator is RealmSSO staff with authority across all accounts. RealmSSO grants this authority outside the API. No API grants it, and no API key can hold it. RealmSSO checks it again on every request, so removing it takes effect on the next call.

A product-team role belongs to one person and one product. The API calls it idp-admins. It lets that person read the handout for one named account. A platform operator grants and revokes it. A person who is a member of any account cannot hold it, and RealmSSO checks this on every request. No screen manages the role.

The routes

The product routes live under /api/v1/products. The two platform reads live under /api/v1/platform. Every route needs a dashboard session. No route accepts an API key. There are 17 product routes and 2 platform reads.

Register a product

{
  "name": "Reports",
  "slug": "reports",
  "protocol": "oidc"
}

The slug uses lowercase letters, digits and single hyphens. It becomes part of the OIDC client ID. A slug that exists already returns 409. A SAML client ID is the product's spEntityId, so two products cannot share one.

Grant a product to an account

{
  "accountId": "clx8e1b3c0002efgh",
  "protocol": "oidc",
  "consumer": "product_idp",
  "placement": "private",
  "binding": "redirect",
  "acsOrRedirectUris": ["<absolute callback URL on the product's sign-in system>"]
}

A product that is inactive cannot receive a new product grant, and RealmSSO will not provision it. Its existing product grants stay editable.

Placement

placement is a label. The API checks one thing: whether the value fits consumer. A product_idp consumer fits private, published_login and mesh. An app consumer fits direct only. A pair that does not fit gets 400.

Beyond that check, nothing acts on the value. No setting in the sign-in service changes with it, and RealmSSO does not test which network a browser can reach. The value appears in the product grant, in the handout and in the audit row. Treat it as a note for people, not as a control.

The handout

The handout holds the non-secret values that one product team copies for one account. It returns one entry for each granted account. A platform operator can read all entries, or one entry with ?accountId=. A product-team role must name one account with ?accountId=. A mistyped query parameter gets 400.

The handout holds no secret. For an OIDC product, the client secret is a separate read that only a platform operator can make.

Every handout read writes an audit row in the audit log of each account it lists. A read that names one account with no product grant also writes a row, so an empty read leaves a record. The row says which authority admitted the call. Audit writes are best effort. See the Audit log page.

Secrets

Only a platform operator can call this route. It returns one client secret for each OIDC product grant, keyed by grantId and realm. A product has no single secret, because each granted realm has its own client. Add ?accountId= to read one account. A SAML product has no secret, so the route refuses it with 400.

The route is a POST on purpose. The response holds live credentials, and a GET could put them in browser history and proxy logs. RealmSSO stores no product secret. The sign-in service holds each secret, and RealmSSO reads it from there on each call. An entry that cannot be read has clientSecret: null and an error.

Every secret read writes an audit row with severity warn in the account's audit log. The row never holds the secret.

Rotating a secret

{ "note": "CHG-1042: planned rotation with the product team" }

• Who. Only a platform operator. A product-team role cannot rotate.
• Scope. One product grant, in one account and one realm. No product-wide rotation exists.
• Protocol. OIDC product grants only. A SAML product grant has no secret, and the route refuses it with 400.
• The note. note is required and has 1 to 500 characters. Use a change reference. Never write a secret in it. RealmSSO records it as written in the audit row.
• Cutover. The rotation is designed as an immediate cutover with no overlap. The old secret is designed to stop working when the sign-in service accepts the rotation. This is reasoned from the sign-in service's documentation. It is not measured.
• Effect. New logins to that product in that account are designed to fail until the product team installs the new secret. Agree a time with the product team first.
• No rollback. The old secret cannot be recovered. A platform operator can read the current secret again through the secrets route. A lost new value needs no second rotation.
• Record. RealmSSO writes an audit row with severity warn that holds the note and the time. It sets secretRotatedAt on the product grant. The response returns the new clientSecret, and RealmSSO does not store it.

The connector board

The connector board is a dashboard page for platform operators. It shows accounts against products. A platform operator can use it to register a product and to grant a product to an account. It can also provision, revoke, and show the handout values of one product grant. It can rename, deactivate or delete a product.

The board does not rotate a secret, show a secret, or manage the product-team role. Use the routes above for those. A customer has no screen, and a product team has no screen.

What is not built