Skip to content

Use SAML identity providers through OIDC ​

Tara does not speak SAML. Organization SSO uses OpenID Connect (OIDC) only. Most identity providers (IdPs) that people call "SAML" also offer OIDC. If yours does, register Tara as an OIDC app there. If it only offers SAML, put Keycloak in between: Keycloak signs in against your SAML IdP, and Tara signs in against Keycloak.

This page lists what Tara needs, then gives the steps for each provider. For the Tara side (where to paste the values, test, roles, Require SSO), see Organization SSO (OIDC).

What Tara needs ​

FieldWhat to give Tara
Callback (redirect) URIhttps://tara.phillipcli.cloud/auth/sso/<org>/callback, where <org> is your organization's slug. Register it at the provider exactly.
IssuerThe provider's issuer URL. Tara reads <issuer>/.well-known/openid-configuration, so that address must work. It must be a public https address (private, loopback and internal addresses are refused) and must match the iss in the tokens exactly. A trailing / is dropped.
Client ID and client secretFrom the OIDC app. Use a confidential (web) app. The secret is stored encrypted and never shown again.
FlowAuthorization code with PKCE (S256) and a nonce. Tara checks the signature of the id_token against the provider's signing keys (JWKS), plus iss, aud and expiry.
Scopesopenid profile email by default (openid is always sent). Change them only from the terminal: ph org sso set --scopes.
ClaimsLogin: preferred_username (if it has an @, Tara keeps the part before it). If there is no such claim, the part of the email before @. Email: email. Name: name. Change the names only from the terminal: --claim-login, --claim-email, --claim-name.

Things to know:

  • The login must start with a letter or digit and use only letters, digits, _, . and -. Otherwise sign-in fails and the error names the claim.
  • The email is kept only if it is at one of your verified domains, and even then Tara does not treat it as verified. Require SSO also needs a verified domain.
  • Tara does not read groups from your provider for organization SSO. Roles come from the role you choose for new people, and from Members.
  • The Portal asks for issuer, client ID and secret. Scopes and claim names are set with ph org sso set.
  • ph org sso test (or the Portal test) fetches the provider's configuration and keys and saves nothing if that fails.

Microsoft Entra ID ​

Entra ID speaks OIDC directly.

  1. In the Microsoft Entra admin center, open App registrations and create a new registration. Choose the account types that match your tenant, and add a Web redirect URI with the Tara callback.
  2. Copy the Application (client) ID.
  3. Under Certificates & secrets, create a client secret and copy its value.
  4. Under Token configuration, add the optional email claim to the ID token, so Tara can read an email address.
  5. In Tara, the issuer is https://login.microsoftonline.com/<tenant-id>/v2.0. Use your tenant ID, not common, because the issuer must match the tokens.
  6. To limit who may sign in, use Enterprise applications for this app and assign users or groups.

Entra sends the user principal name as preferred_username. Tara keeps the part before @ as the login.

Okta ​

  1. In the Okta Admin Console, create an app integration of type OIDC - OpenID Connect and application type Web Application.
  2. Add the Tara callback as a Sign-in redirect URI.
  3. Assign the app to the people or groups who may sign in.
  4. Copy the Client ID and Client secret from the app's General tab.
  5. In Tara, the issuer is https://<your-company>.okta.com. If you use a custom authorization server, use its issuer, for example https://<your-company>.okta.com/oauth2/default.

Google Workspace ​

  1. In the Google Cloud console, open APIs & Services and set up the OAuth consent screen. Choose the Internal user type to keep sign-in to your Workspace users.
  2. Under Credentials, create an OAuth client ID of type Web application. Add the Tara callback as an Authorized redirect URI.
  3. Copy the client ID and client secret.
  4. In Tara, the issuer is https://accounts.google.com.

Google sends no preferred_username, so Tara builds the login from the part of the email before @.

AD FS (Windows Server 2016 and later) ​

  1. In AD FS Management, create an Application Group with a Server application (confidential client). Add the Tara callback as its redirect URI.
  2. Copy the client identifier and generate a shared secret for the application.
  3. Allow the scopes openid, profile and email for the application.
  4. In Tara, the issuer is https://<adfs-host>/adfs.
  5. Make sure the id_token carries a username and an email. In the application group's settings, add an issuance transform rule that sends the user's UPN and email address as claims. Then give Tara the names of those claims with ph org sso set --claim-login <name> --claim-email <name>. A claim whose name is a URL is read as written.

If Tara reports that the claim is missing or not a valid login, the id_token does not contain the claim Tara was told to read. Check the rule and the claim names.

Keycloak as a bridge for SAML-only providers ​

Use this when your IdP offers SAML only. Keycloak is the OIDC provider that Tara talks to, and your SAML IdP is one of Keycloak's identity providers (identity brokering).

  1. In Keycloak, create or pick a realm for Tara.
  2. Open Identity providers and add a SAML v2.0 provider. Import your IdP's metadata (URL or file). Keycloak shows its own SAML service-provider metadata for this provider. Give it to your IdP's administrator so they register Keycloak as a SAML app.
  3. Add attribute mappers on that provider so each user gets an email, and a username Tara can use. Map the SAML attributes your IdP sends to Keycloak's email and username.
  4. Create the OIDC client for Tara: type OpenID Connect, turn on Client authentication, enable only the standard flow, and put the Tara callback in Valid redirect URIs. Copy the secret from Credentials.
  5. In Tara, the issuer is https://<keycloak>/realms/<realm> (Keycloak before version 17 adds /auth).

From the terminal ​

bash
echo "$CLIENT_SECRET" | ph org sso set --issuer https://login.microsoftonline.com/<tenant-id>/v2.0 \
  --client-id <client-id> --client-secret-stdin --jit-role member --enable
ph org sso test

Limits ​

  • Tara has no SAML endpoint, no SAML metadata and no SAML assertions. If you need that, the bridge above is the supported path.
  • One OIDC provider per organization.