API documentation

Single sign on

Single sign on (SSO) lets the people of your bank sign in to Stonewake through your own identity provider. With Microsoft Entra ID it runs over SAML 2.0 through an enterprise application in your own Entra tenant, so credentials, multi factor authentication and conditional access stay with your identity team. It is switched on per workspace, for the email domains your bank owns, and it stays off until your identity team and Stonewake switch it on together. This page is the guide for the administrators who set it up, with the steps for Microsoft Entra ID.

How it works

Your users open the Stonewake login page, enter their work email and choose Continue with your organization. Stonewake sends them to your identity provider, which checks their credentials, multi factor authentication and conditional access. Stonewake never sees a password.
Microsoft Entra ID is supported, over SAML 2.0. For another identity provider, ask us before you plan around it.
The first sign in creates the account inside your workspace with the default role you chose, which is viewer, analyst or compliance. A sign in never makes anyone an administrator. Administrators are named by a person, as described under Enterprise onboarding.
Every first sign in is written to the audit trail of your workspace, with the role it received and where that role came from. So is every later role change a sign in brings, described below.

Roles from your directory

You can let a claim your identity provider states raise the role of a user, for example Entra app roles or group values. You name the claim and map each value to viewer, analyst or compliance.
Only values your identity provider states in the sign in are read. Values without a mapping are ignored and counted, and a mapped role never goes below the default role.
With a mapping, the role follows your directory. Every new sign in reads the claim again, so a user who lost a mapped value in your directory drops to the role the remaining values give, at the latest at the next sign in after the session lifetime. A change in your directory applies at the latest at that next sign in. Each change is written to the audit trail with the old role, the new role and the sign in it came from.
An administrator is never changed by a sign in, and no claim value can make anyone an administrator.
Without a mapping every user receives the default role, and changing a role later works as for any other account.

The domain check

An account only ever lands in the workspace that owns its email domain, and only when the sign in came through the identity provider of that workspace with the issuer you registered. A sign in that fails either check is refused and gets no workspace.
A domain belongs to one workspace at a time. We never assign a public mail domain such as gmail.com to a workspace.
With Microsoft Entra ID your IT publishes nothing for this. A domain can only be verified in one Entra directory, and your IT verified yours with Microsoft when it added the domain to your tenant. We add the domain to your workspace once Microsoft's public records show that it belongs to the managed Entra tenant your Stonewake application sits in, and once our sign in service reads the application's signing certificate from Microsoft for that same tenant. Microsoft's answers and their time are kept in the audit trail of your workspace.
With another identity provider we add a domain once your DNS proves you own it. Your Stonewake contact sends you one TXT record per domain, named _stonewake-challenge. followed by the domain, and the domain is added once our lookup finds exactly that value. The lookup's answer and time are kept in the audit trail of your workspace.
If the issuer or the identity provider of your workspace changes later, single sign on stays off until the domain is proven again.
The check runs at the first sign in and again on every request, so an account can never act in another workspace.

Sessions and signing out

An SSO session lasts at most the session lifetime you set, between 15 minutes and 24 hours, counted from the sign in through your identity provider. Set it to the sign in frequency your identity provider enforces. After it ends the user signs in again at your identity provider.
Signing out of Stonewake ends the Stonewake session and then sends the browser to the sign out page of your identity provider. With Microsoft Entra ID that page signs the browser out of Microsoft as well, so other Microsoft applications open in the same browser ask for a new sign in.
Our sign in service does not support SAML single logout. Ending a session only at your identity provider does not end the Stonewake session before its lifetime runs out, which is why the lifetime should stay short.
Password sign in stays available for the accounts that have a password, unless your workspace signs in through single sign on only.

Joiners and leavers

A joiner can sign in once your administrators assign them, or a group they belong to, to the Stonewake application in Entra. The first sign in creates their account, as described above. With provisioning over SCIM, described below, Entra creates the account when the person is assigned.
A leaver is cut off by removing them in your identity provider, or, with Assignment required set to Yes, by removing their assignment to the Stonewake application. A sign in through single sign on always goes through your identity provider, so they can no longer sign in that way. With provisioning over SCIM their access ends at once when Entra deactivates or deletes them, and without it a session they hold ends at the latest when the session lifetime runs out.
An administrator who removes a member under Workspace settings ends the member's access at once. Every session of the member ends on its next request, the API keys the member created and the assistants the member approved are revoked, and the account can no longer sign in.

Assistants approved through single sign on

An assistant such as Claude or ChatGPT that a person approved after a sign in through your organization keeps reading while that person signs in to Stonewake through your organization at least once every seven days. At the latest seven days and one hour after their last such sign in it stops reading, so removing a leaver in your identity provider also stops their assistants.
While single sign on to your workspace is off or a piece of its configuration is missing, these assistants pause within a minute. They read again once single sign on is back, unless the seven days ran out meanwhile. A pause ends no assistant.
An assistant approved through one identity provider pauses while your workspace uses another. After a move to a new identity provider, each person approves their assistant again through the new one.
An assistant also pauses while the email domain its person approved it from is no longer one of your workspace's domains, and reads again once that domain is proven again.
Workspace settings lists each assistant as Active, Paused or Ended, and says in plain words why a paused one reads nothing.
To stop one assistant at once, the person who approved it or an administrator of your workspace ends it in Workspace settings.

Existing logins

A person who signs in to Stonewake with a password keeps their work and their settings at their first sign in through Microsoft. Our sign in service creates a new login at that first sign in, and we carry the existing login over to it.
We carry it over when the email address Microsoft states for the person, verified, matches exactly one other open login of your workspace. The new login joins the same team with the same role, and the person's alert channels with their quiet hours, alert subscriptions, read markers on deals, acceptance of the evaluation terms and connector approvals move with them, and so do the settings of their own account, the display language, the display name and whether they finished the walkthrough. The work of a desk belongs to its team and stays where it is.
An administrator role is never carried. A person of your bank names the administrator again, as for every administrator.
The old login is then closed and can no longer sign in, unless it is one of your break glass accounts, which keep their password. Both steps are written to the audit trail of your workspace.
When no login or more than one login of your workspace matches, nothing is carried. The new login starts with the default role and team, and we follow it up with you.
API keys belong to your workspace and not to a login, so they keep working.

Single sign on only

Your workspace can be set to sign in through single sign on only. Then every sign in to your workspace by password or by a link sent by mail is refused, and the login page tells the person to continue with your organization.
Switching to single sign on only also ends every connector approval given without a sign in through your organization, such as one given with a password, except those of break glass accounts, and a new approval then needs a sign in through your organization.
Break glass accounts are your choice, from none to five. A break glass account keeps its password, so your bank keeps access during an outage at your identity provider.
A break glass account signs in with its password, and also with a code from an authenticator app when your workspace asks for a second factor at password sign in. Give each one a long and unique password kept in your password vault, and name as few as you need.
With break glass accounts, the setting applies only while single sign on is on and complete. When single sign on is off, password sign in works again for the accounts that have a password.
Without a break glass account, password sign in never reopens by itself. It stays off while single sign on is off or a piece of its configuration is missing, and the login page then tells the person to ask their Stonewake contact. Only Stonewake lifts the setting, at the request of your identity team, and the reason is written to the audit trail of your workspace.
Without a break glass account, Stonewake restores access when single sign on to Stonewake fails while your identity provider works. We learn at once when a piece of the configuration goes missing. We act on the day of your request, within the support hours of your order form, and the change takes effect within a minute.
When your identity provider itself is down, lifting the setting opens password sign in only for the accounts that still have a password. A person whose login was carried over to single sign on has none with Stonewake and signs in again once your identity provider is back. A bank that needs a way in during such an outage keeps a break glass account.

When something is missing

Single sign on fails closed. While any piece of the configuration is missing, it stays off and nobody can sign in through it. The pieces are the identity provider, its issuer, the default role, the team new accounts join, the session lifetime, the sign out address of your identity provider and at least one email domain, each proven for that identity provider. Switching SSO off for a workspace ends every SSO session of that workspace within a minute.

No secret is kept in the Stonewake configuration. Signing certificates and client secrets stay with our sign in service and are never written to our code or our database.

Set up Microsoft Entra ID with SAML 2.0

Your Stonewake contact sends you two values for your workspace, the Identifier (Entity ID) and the Reply URL. Then an administrator of your Entra tenant takes these steps.

Step 1. In the Microsoft Entra admin center open Enterprise applications, choose New application and then Create your own application. Name it Stonewake and choose to integrate an application you do not find in the gallery.
Step 2. In the new application open Single sign-on and choose SAML.
Step 3. In Basic SAML Configuration enter the Identifier (Entity ID) and the Reply URL from your Stonewake contact. As Sign on URL enter https://app.stonewake.ai/login. It is required, because Stonewake completes only a sign in that starts on its own sign in page. Leave Relay State and Logout URL empty.
Step 4. In Attributes & Claims keep the email address claim (user.mail). Leave the Unique User Identifier (Name ID) as Entra sets it, and never edit it after the first sign in, because a changed Name ID makes each user a new Stonewake login. Every user needs an email address in one of the domains of your workspace. If roles should come from your directory, add the role or group claim you want us to read.
Step 5. In SAML Certificates keep the defaults, a SHA-256 signature on the SAML assertion and a certificate valid for three years, and add the address your Stonewake contact gives you to the notification email addresses, so the expiry notices reach us too. Tell your Stonewake contact before you make a new certificate active, so that our sign in service holds it first. Send your Stonewake contact the App Federation Metadata Url from the same section. It is the only value we need from you, because the Microsoft Entra Identifier, the signing certificate and your tenant come with it, and we use the sign out address Microsoft publishes for your tenant.
Step 6. In Users and groups assign the people or groups who may use Stonewake, and in Properties set Assignment required to Yes. Entra then lets only assigned users sign in, apart from Global Administrators, who can sign in regardless of that setting. Assigning a group needs Microsoft Entra ID P1 or P2, and the members of a group nested inside an assigned group are not assigned.

Stonewake asks for no DNS record and for no permission on your directory.

Provisioning users with SCIM

Microsoft Entra ID can create, deactivate and delete the accounts of your workspace over SCIM 2.0, so joiners and leavers follow your directory before anyone signs in.

Step 1. Under Workspace settings, in Sign in and directory, an administrator issues a SCIM token. It is shown once, so copy it at once.
Step 2. In the Stonewake enterprise application in Entra open Provisioning and set the Provisioning Mode to Automatic.
Step 3. Enter the Tenant URL https://api.stonewake.ai/scim/v2 and the token as the Secret Token, then choose Test Connection.
Step 4. Keep the user mappings for userName, active and externalId. Groups are not provisioned.
Step 5. Set the Provisioning Status to On. Entra then works in its cycles, about every 40 minutes.

The directory acts within these limits.

A user Entra creates gets an account in your workspace with the role and team of your single sign on settings, never the administrator role. The address must be in one of the email domains your workspace verified for single sign on.
A user Entra deactivates or deletes loses access at once, as after a removal under Workspace settings. A user Entra reactivates signs in again, and no session from before the deactivation comes back.
The directory sees and changes only the accounts it provisioned. It never changes an administrator or a break glass account, and never removes the last administrator of your workspace.
A workspace holds at most three tokens that are not revoked. To rotate one, issue a new token, enter it in Entra, then revoke the old one under Workspace settings. Every token issued or revoked is in the audit trail.

An administrator can ask for a second factor at password sign in, under Workspace settings in Sign in and directory. From then on a person who signs in with a password also enters a six digit code from an authenticator app such as Microsoft Authenticator. At the first sign in after the change Stonewake shows a QR code to set the app up. A sign in through single sign on keeps the factors your identity provider asks for, which you set in Entra.

What to tell your Stonewake contact

Every email domain your users' addresses carry, not only the main one, because a user whose address carries a domain missing from the list cannot sign in. With Microsoft Entra ID each must be a verified domain of the tenant your Stonewake application sits in, and nothing is published for them. With another identity provider, publish the TXT record we send for each one in your DNS.
The default role for new accounts, and the team they join if it is not the default team of the workspace.
The role mapping, if roles should come from your directory.
The session lifetime, matching the sign in frequency of your identity provider.
Whether your workspace signs in through single sign on only, and which accounts, if any, are its break glass accounts.
The App Federation Metadata Url from step 5 above.

We register your identity provider from that URL and test one sign in with one account of yours. Single sign on only is switched on last, after that test.

What your administrators see

Administrators of your workspace see the single sign on configuration under Workspace settings, read only. It shows whether SSO is on, the protocol, the email domains and how they were proven, the role at first sign in, how many role values are mapped, the session lifetime, whether sign in is single sign on only, how many break glass accounts there are and how many connector approvals single sign on only has ended. Changes go through your Stonewake contact, who makes them together with your identity team. Under Sign in and directory they ask for a second factor at password sign in themselves, and issue and revoke the SCIM tokens of Entra provisioning.

The same page lets them download the audit trail of the workspace for its whole retention as CSV, with every sign in, first sign in, role change and member removal. A system such as your SIEM can collect it with an API key that carries the audit scope, see Keys and access management.

What we do not offer

There is no self service SSO setup in the dashboard.
SCIM provisioning covers users, not groups.
SAML single logout is not supported.
A sign in never grants the administrator role.

Questions go to contact@stonewake.ai. See also the Security overview and Enterprise onboarding.