SSO Configuration Guide: SAML 2.0 and OIDC

Single sign-on (SSO) lets your team sign in to Inkfree with the same work account they use for the rest of your company's apps. Inkfree works with any identity provider (IdP) that supports SAML 2.0 or OpenID Connect (OIDC), including Okta, Microsoft Entra ID (formerly Azure AD), Google Workspace, OneLogin, Ping Identity, JumpCloud, and Auth0.

The setup is the same for every provider. Only the names of the fields in your IdP's admin console differ, so this guide lists the common names side by side for you to follow along whichever provider you use.

Tip: You'll copy values back and forth between Inkfree and your identity provider, so keep both open in separate browser tabs while you work.

Before You Begin

Make sure you have the following:

• Enterprise SSO on your Inkfree plan. If Settings → Enterprise SSO shows "Enterprise SSO isn't included in your plan," contact the support team before continuing.
• An Inkfree administrator account. Enterprise SSO appears in Settings only for administrators.
• An administrator for your identity provider who can create app integrations and assign users to them.
• The email domains your team signs in with, such as acme.com. Inkfree decides who is sent to SSO by matching the domain of the email address a user signs in with, so use domains your organization owns.

Each Inkfree account can have one SAML 2.0 connector and one OIDC connector, and only one of them can be live at a time.

Choosing Between SAML 2.0 and OIDC

Both protocols give your users the same sign-in experience. Choose the one your identity provider and IT team prefer:

• SAML 2.0: the most widely supported enterprise option. Choose it if your IdP offers SAML apps or your security team standardizes on SAML.
• OIDC / OAuth 2.0: a modern protocol built on OAuth 2.0. Choose it if your IdP favors OIDC apps, such as app registrations in Microsoft Entra ID or OAuth clients in Google Cloud.

If you're unsure, start with SAML 2.0. Every major identity provider supports it.

Step 1: Create an SSO Connector in Inkfree

1. Go to Settings → Enterprise SSO and click Add Connector. The Add SSO Configuration dialog opens with three steps: Name & domains, Configure your IdP, and Submit IdP details.
2. Choose the protocol: SAML 2.0 or OIDC / OAuth 2.0.
3. Optionally enter a Connector name, a friendly label such as acme-okta. Inkfree saves it in lowercase with hyphens, so "Acme Okta" becomes acme-okta. If you leave it blank, Inkfree names it after your account. The name can't be changed later.
4. In Email Domains, type each domain that should use this connector and press Enter. You can add more than one.
5. Leave Enforce SSO turned off for now. You'll turn it on after testing, in Step 5.
6. Keep Send login hint turned on so your IdP's sign-in page is pre-filled with the user's email.
7. To create Inkfree accounts automatically the first time new users sign in, turn on Automatically onboard new SSO users and choose a Default role for new users.
8. Click Reserve connector.

Inkfree reserves the connector and shows the values you'll need in your identity provider. The connector is listed as Setup incomplete and won't accept sign-ins until you finish Step 3.

Step 2: Set Up the App in Your Identity Provider

In your identity provider's admin console, create a new application: a SAML 2.0 app, or for OIDC, a Web application that uses the Authorization Code flow. Then copy the values from the Inkfree dialog into it. Each value has its own Copy button.

Note: The URLs include an ID that is unique to your connector. Always copy the exact values shown in your Inkfree account rather than typing them or reusing values from another account.

SAML 2.0 Values for Your IdP

The first three values are required. The SP Single Logout URL is needed only if you want single logout.

• If your IdP can import service provider metadata, give it the SP Entity ID / Audience URI / Metadata URL value instead of entering each field by hand.
• Inkfree identifies users by email address, so the NameID (subject) your IdP sends must be the user's email.
• Inkfree signs requests with RSA-SHA256. If your IdP requires signed requests or single logout, download the SP Signing Certificate from the dialog (Download .crt or Download .pem) and upload it to your IdP.
• You can also send first name, last name, display name, and phone number as attributes. See Map User Attributes below.

OIDC Values for Your IdP

The Redirect URI is required. The other two values are needed only for single logout and for signing in from your IdP's app dashboard.

• Use the Authorization Code grant type, and allow the openid, email, and profile scopes.
• Copy the Client ID and Client Secret your IdP generates. You'll need them in Step 3, and some IdPs show the secret only once.
• If your IdP allows only one shared Initiate Login URI for all apps, use the shared URI shown below the values in Inkfree instead. It works as long as the same issuer isn't used by another connector on your Inkfree account.

Assign Users to the App

Assign the new app to the users or groups who should have access to Inkfree. Only assigned users can sign in through SSO. Assigning a user doesn't create their Inkfree account on its own; see User Provisioning and Roles below.

When you're done in your IdP, return to Inkfree and click Continue to IdP details. If you closed the dialog, open the connector's ⋮ menu and select Complete setup to pick up where you left off.

Step 3: Enter Your IdP Details and Activate SSO

Enter the details your identity provider generated. For both protocols, the recommended option reads everything Inkfree needs from a single URL.

Entering SAML 2.0 IdP Details

Under IdP Configuration, choose one of two tabs:

• Metadata URL (recommended): paste your IdP's metadata URL into IdP Metadata URL. Inkfree reads the issuer, sign-in URL, and signing certificate from it.
• Manual entry: enter the IdP Entity ID / Issuer, IdP SSO URL, and IdP Signing Certificate (PEM), plus the IdP Single Logout URL if you use single logout. Use this option if your IdP doesn't publish a metadata URL.

Entering OIDC IdP Details

Under IdP Configuration, choose Issuer URL or Manual entry, then complete the rest of the form:

• Issuer URL (recommended): paste your IdP's issuer URL. Inkfree discovers the authorization, token, user info, and JWK Set endpoints automatically.
• Manual entry: enter the Authorization Endpoint, Token Endpoint, User Info Endpoint, and JWK Set Endpoint individually.
• End Session Endpoint (optional): add it if signing out of Inkfree should also sign the user out of your IdP.
• Client ID and Client Secret: from the app you created in Step 2.
• Client Authentication Method: defaults to Client Secret Basic (HTTP Basic header). Choose Client Secret Post (form body) if your IdP app is set up that way.
• Use PKCE (recommended): leave this on unless your IdP doesn't support PKCE.
• Scopes: openid is always included, and email and profile are selected by default. Add any other scopes your IdP requires.

Advanced Options

Most setups don't need these. Expand Advanced at the bottom of the form to:

• SAML: set a custom Email Attribute if your IdP sends the email address in a non-standard attribute, override the SP Entity ID, or supply your own SP certificate and private key. Inkfree generates a signing key pair for each connector automatically, so you only need your own for a specific reason.
• OIDC: set an Email Claim (override) if the email arrives in a non-standard claim, or use ACR Values, Prompt, and Max Age to control how your IdP authenticates users.

Click Activate SSO. The connector's status changes from Setup incomplete to Live.

Note: Only one connector can be live at a time. If your connector for the other protocol is already live, Inkfree asks you to confirm, and activating the new connector pauses the other one.

Step 4: Test Single Sign-On

Test SSO before you enforce it, while password sign-in still works as a fallback:

• From Enterprise SSO: open the connector's ⋮ menu and select Test SSO. This works once the connector is Live.
• From the Inkfree sign-in page: click Sign in with SSO, enter a work email on one of your connector's domains, and click Continue with SSO. You should be sent to your IdP and returned to Inkfree signed in.
• From your identity provider: open your IdP's user dashboard, such as the Okta End-User Dashboard or Microsoft My Apps, and click the Inkfree app tile.
• New user onboarding: if you turned on Automatically onboard new SSO users, sign in as an assigned user who doesn't have an Inkfree account yet and confirm that one is created.
• Sign-out: if you set up single logout, sign out of Inkfree and confirm your IdP session ends too.

Tip: Test in a private or incognito browser window so an existing Inkfree or IdP session doesn't hide a problem.

Step 5: Enforce SSO for Your Domains

Once SSO works, you can require it for everyone on your domains:

1. In Settings → Enterprise SSO, open the connector's ⋮ menu and select Edit.
2. Turn on Enforce SSO (block password login for these email domains).
3. Choose a Password-fallback user (break-glass account). This one user can still sign in with a password if your IdP is ever unavailable. It defaults to the person who set up SSO.
4. Click Save Changes.

From now on, everyone else with an email address on the connector's domains must sign in through your identity provider. If they try to sign in with a password, Inkfree tells them their organization requires single sign-on and switches them to SSO sign-in.

Tip: The password-fallback user is the one account that can bypass SSO, so protect it with two-factor authentication.

Tips for Popular Identity Providers

Menu names in identity providers change from time to time. If a label below doesn't match what you see, search your IdP's documentation for the equivalent SAML or OIDC setting.

Okta

• SAML: in the Admin Console, go to Applications → Applications → Create App Integration and choose SAML 2.0. After saving, copy the Metadata URL from the app's Sign On tab.
• OIDC: choose OIDC - OpenID Connect with the Web Application type. Your issuer URL is your Okta domain (for example, https://your-org.okta.com) or the URL of your custom authorization server (for example, https://your-org.okta.com/oauth2/default).
• Assigned users see the Inkfree tile on their Okta End-User Dashboard automatically.

Microsoft Entra ID

• SAML: go to Enterprise applications → New application → Create your own application and choose the non-gallery option. Open Single sign-on, select SAML, and enter the Inkfree values under Basic SAML Configuration. Then copy the App Federation Metadata Url from the SAML Certificates section.
• OIDC: go to App registrations → New registration and add the Redirect URI under the Web platform. Create a client secret under Certificates & secrets and copy its Value (not the Secret ID). Your issuer URL is https://login.microsoftonline.com/your-tenant-id/v2.0.
• Make sure your users have an email address in Entra ID. If the email isn't returned when using OIDC, add the email optional claim under Token configuration.
• Assign users and groups on the enterprise application's Users and groups page.

Google Workspace

• SAML: in the Admin console, go to Apps → Web and mobile apps → Add app → Add custom SAML app. Google shows its own details (SSO URL, Entity ID, and certificate) first. Google doesn't provide a metadata URL, so use Manual entry in Inkfree.
• Custom SAML apps are off by default. Under User access, turn the app on for everyone or for the organizational units that need Inkfree.
• OIDC: in the Google Cloud console, go to APIs & Services → Credentials, create an OAuth client ID of type Web application, and add the Redirect URI under Authorized redirect URIs. Your issuer URL is https://accounts.google.com. Set the OAuth consent screen to Internal so only users in your organization can sign in, and leave End Session Endpoint blank in Inkfree, since Google doesn't offer one.

OneLogin

• SAML: add the SAML Custom Connector (Advanced) app and enter the Inkfree values on its Configuration tab. OneLogin also asks for an ACS (Consumer) URL Validator, a regular expression that matches the ACS URL. Then copy the Issuer URL (your metadata URL) from the SSO tab.
• OIDC: add the OpenId Connect (OIDC) app. Enter the Login Url, Redirect URI's, and Post Logout Redirect URI on the Configuration tab, then copy the Client ID and Client Secret from the SSO tab. Set the token endpoint authentication method to match the Client Authentication Method in Inkfree. Your issuer URL is https://your-subdomain.onelogin.com/oidc/2.

Other Identity Providers

Ping Identity, JumpCloud, Auth0, Keycloak, and any other standards-based IdP work the same way. Create a SAML 2.0 or OIDC web application, paste in the Inkfree values from Step 2, make sure the user's email address is sent as the NameID (SAML) or email claim (OIDC), and bring the metadata URL or issuer URL back to Inkfree.

User Provisioning and Roles

• Automatic onboarding: with Automatically onboard new SSO users turned on, Inkfree creates an account the first time an assigned user on your domain signs in through SSO. With it off, only people who already have an Inkfree account can sign in through SSO.
• Default role: new users get the Default role for new users set on the connector. You can change a user's role in Inkfree afterward. Mapping IdP groups to Inkfree roles is coming soon.
• Removing access: unassigning or deactivating a user in your IdP stops them from signing in through SSO, but it doesn't deactivate their Inkfree account. If SSO isn't enforced on your domain and they have an Inkfree password, they could still sign in with it. When someone leaves, always deactivate them in Settings → Teams as well.
• Inkfree doesn't support SCIM provisioning at this time.

Map User Attributes

An email address is all Inkfree needs to sign a user in. To fill in more profile details, open the connector's ⋮ menu, select Attribute mapping, and map the attribute (SAML) or claim (OIDC) names your IdP sends to these Inkfree fields:

• Email: used to find or create the user. It must be an email address.
• Display name: takes precedence over first and last name.
• First name and Last name
• Phone

Inkfree uses these mappings to find or create users and to update their profile details when they sign in.

Manage, Pause, or Delete a Connector

Each connector in Settings → Enterprise SSO shows its status (Setup incomplete, Live, or Paused) and has a ⋮ menu with these options:

• SP Setup Info (SAML) or RP Setup Info (OIDC): view and copy the values to enter in your IdP.
• Test SSO: run a test sign-in. Available for live connectors.
• Edit (or Complete setup while setup is incomplete): update domains, IdP details, and sign-in settings. The connector name and protocol can't be changed.
• Attribute mapping: map profile fields from your IdP.
• Delete: remove the connector.

To pause SSO without losing your configuration, open Edit, switch Active off, and click Save Changes. The connector shows as Paused until you switch it back on.

Note: Deleting a connector turns off SSO for its domains immediately. Users who have only ever signed in with SSO won't have an Inkfree password and will need to reset it, so make sure they have a way to sign in before you delete.

Troubleshooting

Need Help?

If you get stuck, contact the support team or email support@inkfree.app with your connector name, the protocol you're using, your identity provider, and the approximate time of a failed sign-in. Never send client secrets, private keys, or passwords.