SSO Integrations

Single sign-on (SSO) lets your team reach Altana with the credentials they already use every day, with no separate Altana password to keep track of. You're in control of the whole setup: you register an app in your identity provider (IdP), enter a few values on Altana's SSO settings page, test it with a real sign-in, and switch it on whenever you're ready. Altana works with any OpenID Connect (OIDC) identity provider, and this guide walks you through it step by step, with dedicated instructions for Microsoft Entra, Okta, and PingFederate.

Before you begin

Is SSO available to you? SSO self-service must be enabled for your organization, and you need permission to manage SSO. Open Settings → SSO: if you see "SSO self-service is not enabled," contact Altana support to have it turned on.

You'll move a few values between your IdP and Altana:

Altana gives you: the Redirect URI, shown on the SSO settings page (use Copy redirect URI). Register it in your IdP before you save.
You enter on the SSO settings page: the OIDC Discovery URL (the .well-known/openid-configuration endpoint), the Client ID, the Client Secret of the app you register for Altana, and the secret's expiry date.

Altana requests the standard openid, profile and email scopes, and also requests groups when your IdP advertises it, so group-based access works without extra scope configuration on your side.

How setup works

The whole flow moves between Altana and your IdP once:

In Altana, open Settings → SSO and choose your provider: Generic OIDC, Microsoft Entra ID, Okta, or PingFederate.
Copy the Redirect URI shown there.
In your IdP, register an app for Altana using that Redirect URI (the provider steps below), and note its Discovery URL, Client ID, and Client Secret.
Back in Altana, enter the Discovery URL, Client ID, Client Secret, and the secret's expiry date, and check "I've registered this Redirect URI in my identity provider."
Map your groups and set a default group.
Test with a real sign-in, then turn SSO on.

Generic OIDC provider

If you chose Generic OIDC, any standards-compliant OpenID Connect provider works. The essentials:

Register the OIDC client. Create a confidential OIDC client for Altana, enable the Authorization Code flow with a client secret, and add the Redirect URI shown on the SSO page to its allowed redirect URIs.
Send the identity claims. The ID token must carry email, given_name and family_name. Most IdPs emit these with the standard email and profile scopes, which Altana already requests.
Emit a groups claim. Add a claim named groups to the ID token so group mapping works. If your provider can emit either group names or IDs, names are easier to map.

Without a claim named groups in the ID token, group mapping has nothing to match and new users only land in the default group.

Microsoft Entra

Register the Redirect URI. App registrations → your app → Authentication → Add Redirect URI → Web applications → Web, then paste the Redirect URI shown on the SSO page.
Verify API permissions. Only the delegated Microsoft Graph permissions openid, profile and email are required, with no admin consent needed. User.Read is added by Azure to every new app, but Altana never calls the Graph API, so it's safe to remove.
Emit the groups claim. Token configuration → Add groups claim → select Security groups and check the ID token box.
- Group ID (the default) works for every group.
- If your groups are synced from on-premises Active Directory via Microsoft Entra Connect, you can instead choose a name format such as sAMAccountName so the values you map in Altana are readable AD group names, not GUIDs.
- Whatever format you choose, that exact value is what you map in Altana. Running a test sign-in pre-fills the real values your IdP sends.
Prepare your users. Each SSO user needs the Email property set on their Entra profile and at least one security-group membership for group mapping.

Entra caveats we see most often:

Name formats (sAMAccountName, Domain\name, SID) only apply to AD-synced groups. Cloud-only groups keep their GUID. If you sync more than one AD domain, use a domain-qualified format to avoid name collisions.
Selecting Directory roles emits a wids claim, not groups, so group mapping never sees it.
Cloud-only test accounts often have no Email set; those users are asked to complete their profile at first sign-in.

Custom claim names in Entra. You normally don't need them — Entra emits the standard email, given_name and family_name, so leave Altana's claim-mapping fields blank. The groups claim name is fixed and cannot be renamed, so leave Altana's Groups claim field blank for Entra (choosing a different value format, above, is fine — that's not a rename). If you do rename or add claims under Enterprise applications → your app → Single sign-on → Attributes & Claims, Entra requires the app to accept the modified token: set acceptMappedClaims to true in the app manifest (single-tenant apps) or configure a custom signing key. Without one of these, sign-in fails at the token step with AADSTS50146.

Okta

Create the app integration. Admin → Applications → Applications → Create App Integration → OIDC - OpenID Connect → Web Application. Under Grant type → Core grants, keep Authorization Code checked, then add the Redirect URI shown on the SSO page under Sign-in redirect URIs.
Add the groups claim. Sign On → OpenID Connect ID Token → expand Show legacy configuration → Group Claims → Edit. Set Groups claim type to Filter, then under Groups claim filter enter the name groups, condition Matches regex, value .*, then Save. Okta emits readable group names, so the values you map in Altana are already legible (no GUIDs).
Assign users. Applications → your app → Assignments: assign every user or group that should have access to Altana.

Leave Client Credentials unchecked. Altana signs users in with the Authorization Code flow. If sign-in returns "You are not allowed to access this app," check that the user is assigned and that the app's authentication policy permits them.

Custom authorization server (advanced, optional): The steps above use Okta's org authorization server, which is recommended. If your organization standardizes on a custom authorization server, point the Discovery URL at that server (/oauth2/{authServerId}/.well-known/openid-configuration) and, on that server, add a groups claim (Include: Always, Any scope) plus an access policy. A custom authorization server refuses to issue tokens without one. If it doesn't recognize the groups scope, add groups to its Scopes.

PingFederate

Create the OAuth client. APPLICATIONS → OAuth → Clients → Add Client (or open the existing client for Altana). Under General Info set a Client ID and Client Name; under Client Authentication choose Client Secret. Add the Redirect URI shown on the SSO page under Redirect URIs, and under Grant Types check Authorization Code. Save.
Add the claims to the OpenID Connect policy. APPLICATIONS → OAuth → OpenID Connect Policy Management → open your policy (or Add Policy). On the Attribute Contract tab, extend the contract with email, given_name, family_name and groups (mark groups as Multi-Valued). On the Contract Fulfillment tab, map each of those to the matching value from your data store so they're populated at sign-in.
Grant users access. Make sure the users who should reach Altana can authenticate through the adapter or authentication policy bound to this client.

A claim that isn't in the contract, or isn't fulfilled, never reaches the token: email is required for sign-in, groups for group mapping. Leave Client Credentials unchecked under Grant Types.

Claims Altana uses

Claim	Used for	Required
`email`	Sign-in identity for each user	Yes
`given_name` + `family_name`	Display name	Recommended
`groups`	Mapping IdP groups to Altana groups	For group-based access
`email_verified`	Trusting the email without a second prompt	Optional

Connecting with SAML instead of OIDC? The SAML NameID supplies the username, and the email too when the NameID is in email-address format — so email can resolve from the NameID even if you don't map an email attribute. First name, last name and groups have no such fallback: release them as SAML attributes under the names Altana expects, or users are asked to complete their profile at first sign-in.

Map your groups

A group mapping connects a group from your IdP to an Altana group, which controls what its members can see and do. You manage Altana groups on the Role Groups page.

In the Group Mappings section of the SSO page, add one mapping per group: enter the IdP group value exactly as your provider sends it (a name or a GUID, depending on the format you chose above) and pick the Altana group to grant. You can type the values in by hand, or run a test sign-in first so the Claims Inspector pre-fills the real values your IdP sent.

Default group. Set a Default Group to catch users whose IdP groups don't match any mapping. It's a fallback, not an addition: a user who matches one or more mappings gets exactly those groups, and only users who match nothing get the default. A user who once matched a mapping that is later removed falls back to the default at their next sign-in.

Membership is reconciled on every sign-in. Removing a user from a group at your identity provider removes the matching Altana access the next time they sign in.

Turn on SSO

Once you've saved the connection and confirmed the Redirect URI on the SSO page, you can go live. You have two ways to do it: activate right away, or run a test sign-in first, which we recommend. Use the enable/disable switch to turn SSO on or off at any time. If you activate without testing, the connection is marked verified automatically the first time a real user signs in successfully through it.

No one gets locked out. Turning on SSO doesn't remove your organization's existing sign-in, so users can still sign in the way they do today. You can also designate specific people as SSO Bypass users, who can always sign in without SSO. Setting up a bypass user or two during onboarding is a good safeguard while you finish configuring a connection.

Test with a real sign-in (recommended)

On the SSO page, generate a shareable test link (you can copy it to your clipboard) and open it in a private window, or send it to a colleague who signs in with their own IdP account. The test never signs you out of Altana. When the sign-in completes, the Claims Inspector shows the exact claims your IdP returned, including the real group values, so you can confirm the connection and fill in your group mappings from live data.

Editing an existing connection

The Client Secret and its expiry are editable at any time; rotating the secret asks you to test again.
Changing the Client ID resets the verified status. Run a test or let the next real sign-in re-verify it.
The Discovery URL and provider are locked after setup. To change them, delete the connection and create a new one. Your Redirect URI stays the same, so you don't need to reconfigure your IdP.

Client-secret expiry and rotation

Client secrets issued by your IdP expire. To keep a lapse from becoming a sign-in outage, you set the secret's expiry date when you save the connection, and Altana escalates reminders as that date approaches:

30 days out — your SSO administrators see a reminder banner; everyone else signs in as usual.
7 days out — everyone signing in sees the banner, so the rotation isn't missed.
Expired — the connection shows a red status, and new sign-ins through it fail until you rotate the secret.

To rotate, use Update Secret on the connection: paste the new secret from your IdP and set its new expiry date. Your IdP registration, Redirect URI, and group mappings all stay exactly as they are — only the secret changes — and rotating asks you to test the connection again.

Pre-filling the sign-in field

Altana can forward the email a user types on the Altana sign-in page to your identity provider so it pre-fills the provider's own sign-in field. It's on by default.

Leave it on for Okta and other providers where people sign in with their email — it makes sign-in smoother.
Turn it off only if your users sign in with something other than their email (for example a Windows username or a UPN in a directory-federated setup), where a pre-filled email would be the wrong value they have to clear.

Pre-fill does not control whether your provider re-asks who you are. It only fills the sign-in field when your provider shows it. If a user already has an active session with your identity provider, the provider may go straight to the password or verification step whether pre-fill is on or off — to sign in as a different user, sign out of your identity provider first.

Troubleshooting and getting help

"SSO self-service is not enabled." The feature isn't turned on for your organization yet. Contact Altana support to enable it.
Redirect URI mismatch at sign-in. The Redirect URI registered in your IdP must match the one on the SSO page exactly. Use Copy redirect URI to avoid typos.
Groups come back empty. Your IdP isn't sending the groups claim in the ID token. Recheck the groups-claim step for your provider, and remember that Entra's Directory roles emit wids, not groups.
Okta: "You are not allowed to access this app." The user isn't assigned to the app, or the app's authentication policy blocks them.
Users are asked to complete their profile. Their IdP account has no email set. Add an email to the account in your IdP.
Sign-in started failing and the connection shows expired. The client secret reached its expiry date. In your IdP, generate a new secret, then use Update Secret on the SSO page to paste it in and set the new expiry date.

If you're still stuck, contact your Altana representative or Altana support with the provider you're configuring and the error you see.