Configure the hub

Your organization is the hub. It receives the approval requests of an application and asks your members to decide. In this guide, you give the application the identity of your hub, register the application, and choose who approves its requests. The example is Acme MDM, the laptop management service of Acme, at acme.example.com.

Share the hub metadata

In the Web App

1. Open the Web App (opens the SplitSecure web app).
2. In the sidebar, click StepAuth → Settings.

1. In the Hub metadata card, click Show metadata.
2. Click Copy.

The first click generates the keyset of the hub. Every later click shows the same document.

The document has three fields:

When the administrator of the Acme organization copies the hub metadata, the clipboard holds a document like this one. Your entity, keyset and host are different. The $schema line identifies the format in this guide only. The copied document does not have it.

{
	"$schema": "https://docs.splitsecure.com/schemas/stepauth/hub/v1.json",
	"entity": "Nz4kQb9mR2xVw7cA.hub.example.net",
	"keysets": [
		{
			"keysetId": "ks_AZsVb3pTq0e1Kx9m",
			"keys": [
				{
					"idx": 0,
					"alg": "ed25519",
					"pub": "G/OnfXxnOPrQjmfGEwWKhptVCeidyHHoSHlwNYfxo8w="
				},
				{
					"idx": 1,
					"alg": "ml-dsa-65",
					"pub": "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"
				}
			]
		}
	],
	"host": "https://api.example.net/stepauth/Nz4kQb9mR2xVw7cA"
}

The document identifies the hub only. It has no data about one application, so one copy serves every application you register. Send it to the developer of the application.

The Service providers page also has a Hub metadata button on each registered service provider. It copies the same document.

Register the service provider

In the Web App

On StepAuth → Settings, in the Service providers card, click Manage service providers.

1. Click Register service provider. The Register a service provider page opens.

2. Fill in the fields.

   Field	Value
   Display name	Acme MDMApprovers see this name on every request
   Service provider metadata JSON	The document from the developerIt must have an entity and at least one keyset
   Callback URL pattern (optional)	https://acme.example.com/stepauth/ Limits where the hub delivers decisions. See Callback URL patterns

3. Click Register.

The callbackUrl in the service provider metadata is the default callback URL. A request that sets no callback URL uses it. If the request and the registration both have no callback URL, the hub rejects the request with invalid_callback_url.

Route requests to approvers

Each request names its approver in action.approver. The value is a NameID, an identifier with a kind and an id, written here as kind:id.

A persistent: NameID and the system Everyone group are not accepted as approvers.

The id of a group is not its name, and nobody can guess it. The hub publishes a directory of the users, groups and policies that it accepts, and the SDK reads it. Tell the developer to offer choices from the directory, not a free-text field. The hub rejects a wrong value with unknown_approver.

The hub expands the approver to the people who can decide. A request can reach 99 groups or fewer and 5000 members or fewer, for example through a policy or a large group. Above either limit, the hub rejects the request with approver_set_too_large.

To write a policy, see Write a policy .

Callback URL patterns

Each request names the callback URL that receives its decision. The pattern on the registration limits the URLs that the hub accepts.

1. The callback URL must use https.
2. The scheme and the host of the callback URL must equal those of the pattern. The comparison ignores letter case. The host includes the port.
3. If the pattern has no path, or the path is /, the hub accepts any path on that host.
4. If the pattern has a path, the callback path must equal it, or continue it after a /. A / at the end of the pattern is optional.

The pattern https://acme.example.com/stepauth/ accepts https://acme.example.com/stepauth/callback. It rejects https://acme.example.com/stepauth-old/callback and https://acme.example.com/other.

Connect Slack

In the Web App

1. Open the Web App (opens the SplitSecure web app).
2. In the sidebar, click Organization → Advanced → Integrations.

1. Click Connect integration.
2. On Connect an integration, click the Slack card.
3. Slack opens its consent page. Select the workspace, and allow the SplitSecure app.

The app asks to send messages, to open direct messages, to read the users and their emails, and to add the /splitsecure command. Your workspace policy can require a Slack administrator to approve the install.

An organization can connect more than one workspace. To change the default, open the workspace and click Make default.

Members then subscribe themselves, as in Approve a request .

Replace a registration

In the Web App

You cannot edit a registration. To change the keysets, the callback URL or the pattern, delete the registration and register the service provider again.

1. On Service providers, click the trash icon on the row of the service provider.
2. Click Delete.
3. Register the new metadata, as in Register the metadata .

Requests that the hub accepted before the deletion continue to completion. Between the deletion and the new registration, the hub rejects new requests from the app with unknown_sender.

Remove a service provider

In the Web App

1. On Service providers, click the trash icon on the row of the service provider.
2. Click Delete.

Requests that the hub accepted before the deletion continue to completion. New requests from that application get unknown_sender.

Hand over a keyset rotation

The developer mints the new keyset and exports metadata that holds both keysets, as in Rotate the keyset . You replace the registration with that document, and later with the document that holds the new keyset only.

When the organization is locked

While SplitSecure locks the organization, the hub answers a valid request with org_locked, and the directory calls return the same code. Requests work again after the unlock. A deactivated organization answers org_deactivated instead.

Troubleshooting