MalleableMalleable

Single sign-on (SSO)

Malleable can use your own identity provider to sign in, using OpenID Connect (OIDC) or SAML 2.0. This page is for IT administrators setting that up. It walks through Microsoft Entra ID with OIDC and Google Workspace with SAML; any OIDC or SAML 2.0 provider works with the same values.

How it works

  • A connection links Malleable to one identity provider tenant and the email domains you own. One connection can cover several domains, such as a parent company and a brand.
  • On the sign-in page a person types their email address. If its domain belongs to your connection, they are sent to your identity provider and come back signed in.
  • SSO signs in people who already have a Malleable account or a pending invitation. It does not create accounts for everyone in your directory, and it does not change which organizations or workflows a person can reach. Invite people from Malleable as you do today.
  • If SSO fails, users will still be able to sign in with an emailed one-time code.

Our team will help you create the connection. There are three steps: we send you the values your identity provider needs, you create an application there, and you send us its details.

Microsoft Entra ID (OIDC)

1. Get your redirect URI

Ask your Malleable contact for your redirect URI. It looks like this, ending in an ID we choose for your connection:

https://www.usemalleable.com/auth/sso/callback/<connection-id>

2. Register the application in Microsoft Entra

In the Microsoft Entra admin center:

  1. Go to Identity → Applications → App registrations → New registration.
    • Name: Malleable
    • Supported account types: Accounts in this organizational directory only (single tenant)
    • Redirect URI: platform Web, with the redirect URI from step 1
  2. On the application's Overview page, copy the Application (client) ID and the Directory (tenant) ID.
  3. Go to Certificates & secrets → New client secret. Copy the secret's Value (not its Secret ID); it is shown only once. Note the expiry date: sign-in through SSO stops when the secret expires, so plan to send us a new one before then.
  4. Go to Token configuration → Add optional claim, choose the ID token type, and add email. Accept the prompt to add the Microsoft Graph email permission.
  5. Go to API permissions. A new registration lists User.Read, plus email from the previous step. Choose Add a permission → Microsoft Graph → Delegated permissions → OpenId permissions, tick openid and profile, and add them. Then choose Grant admin consent so your people are not asked to consent one by one. This matters most if your tenant does not let users consent to applications themselves. Malleable never uses User.Read; you can remove it.
  6. Optional: under Enterprise applications → Malleable → Properties, turn on Assignment required and assign the users or groups who should be able to sign in.

Malleable requests only the openid, email and profile scopes. It reads the ID token at sign-in and never calls Microsoft Graph or keeps a refresh token.

3. Send us the connection details

ValueWhere it comes from
Issuerhttps://login.microsoftonline.com/<tenant-id>/v2.0, using your Directory (tenant) ID. It must be tenant-specific, not common or organizations.
Client IDApplication (client) ID
Client secretThe secret Value from step 3
Email domainsEvery domain your people sign in with, for example example.com, example-brand.com. Subdomains are included automatically.

Google Workspace (SAML)

1. Get your SAML values

Ask your Malleable contact for your ACS URL and entity ID. They look like this, ending in an ID we choose for your connection:

ACS URL:   https://www.usemalleable.com/auth/sso/saml2/sp/acs/<connection-id>
Entity ID: https://www.usemalleable.com/auth/sso/saml2/sp/metadata?providerId=<connection-id>

2. Add a custom SAML app in Google Workspace

In the Google Admin console:

  1. Go to Apps → Web and mobile apps, then Add app → Add custom SAML app. Name it Malleable and continue.
  2. On Google Identity Provider details, copy the SSO URL, the Entity ID and the Certificate, then continue.
  3. On Service provider details:
    • ACS URL and Entity ID: the values from step 1
    • Start URL: leave blank
    • Signed response: leave unticked. Google still signs the assertion, which is what Malleable checks.
    • Name ID format: EMAIL
    • Name ID: Basic Information > Primary email
  4. Optional: on Attribute mapping, map First name to givenName and Last name to surname, so people invited to Malleable get their names from Google. Then finish.
  5. Open the new app, choose User access, and turn it on for everyone or for the organizational units and groups who should be able to sign in. Google can take a while to apply this.

3. Send us the connection details

ValueWhere it comes from
SSO URLGoogle Identity Provider details, step 2
Entity IDGoogle Identity Provider details, step 2. This is Google's entity ID, not the one we sent you.
CertificateGoogle Identity Provider details, step 2, including its BEGIN CERTIFICATE and END CERTIFICATE lines
Email domainsEvery domain your people sign in with, for example example.com, example-brand.com. Subdomains are included automatically.

Malleable only accepts assertions signed with that certificate and addressed to your connection. People can also open Malleable from the Google apps menu.

Test, then switch on

Once we have your details we send you a sign-in link:

https://www.usemalleable.com/sign-in/sso/<your-organization>/<connection-id>

Opening it goes straight to your identity provider. At this point nothing has changed for anyone else: the Malleable sign-in page still emails a one-time code to your domains. Have an administrator and one or two other people sign in through the link. When that works, tell us and we switch the sign-in page over for your domains.

The link keeps working afterwards. To give people a Malleable tile, set it as the application's Home page URL in Entra (Branding & properties), or as the Initiate login URI in Okta.

Matching people to accounts

Malleable matches a person by the address your identity provider reports, and only accepts addresses at your connection's domains. With OIDC it checks both the email claim and the sign-in name, so a person whose Malleable account is under one of your domains and whose sign-in name is under another is still matched. With SAML it uses the email attribute if your provider sends one, and the Name ID otherwise.

If someone signs in through your identity provider and sees a message that they don't have a Malleable account, invite them from Malleable under the address your identity provider reports for them, and have them sign in again.

Other identity providers

Any provider that supports OIDC with the authorization-code flow works. Create a confidential web application with the redirect URI we send you and the openid, email and profile scopes, and send us the issuer, client ID, client secret and domains. The issuer must serve a discovery document at <issuer>/.well-known/openid-configuration, and the ID token must carry the person's email address.

Any SAML 2.0 provider, such as Okta or Microsoft Entra ID, works the way Google Workspace does. Create a SAML application with the ACS URL and entity ID from us, send the person's email address as the Name ID, and sign assertions. Then send us the provider's SSO URL, entity ID and signing certificate, and your domains.

Changes after setup

Tell your Malleable contact when any of these happen and we will update the connection without interrupting anyone who is already signed in:

  • A client secret is about to expire. Create a new one and send it to us.
  • A SAML signing certificate is about to expire. Create the new one and send it to us before you make it active. We accept both while you switch.
  • You add a domain, for example after a rebrand or an acquisition.
  • A company you acquired uses a different tenant. We add a second connection for that tenant's domains; both can sign in to the same Malleable organization.

Questions

See Security & data handling or contact support.