> ## Documentation Index > Fetch the complete documentation index at: https://docs.prophia.com/llms.txt > Use this file to discover all available pages before exploring further. # OAuth Setup for Your Organization > One-time identity-provider configuration so your users can connect via SSO This is a **one-time setup** performed once for your organization. Once complete, everyone at your company can connect their MCP clients through your corporate sign-in — no API keys to manage, and nothing for individual users to configure beyond a URL. Prophia supports any standards-compliant OIDC identity provider: Okta, Azure AD / Entra ID, Auth0, Google Workspace, Keycloak, and others. ## Who does what The setup spans two admin consoles, and in most organizations two different people. Expect to pass values back and forth between them. | Role | Does | | - | - | | **An admin user for your account** | Copies the redirect URL out of Prophia (Step 1), then registers the finished application back in Prophia (Step 3) | | **Your identity-provider admin** | Creates the OIDC application and assigns users to it (Step 2) | | **Each user** | Pastes a URL into their MCP client and signs in — nothing else | > [!NOTE] > > "Admin" here means an administrator **at your organization**, not a Prophia employee. Prophia Support can complete the registration for you if you'd rather not do it yourself — see [If you get stuck](#if-you-get-stuck). ## Before you start * **Admin access on your Prophia account.** The setup lives on the **API/MCP Config** tab in Account Settings, which appears only for account admins on accounts with API access enabled. If you don't see the tab, contact Prophia Support to confirm API access is enabled. * **Admin access to your identity provider**, so you can create an OIDC application. > [!NOTE] > > **Setup is per Prophia account.** If your company has more than one Prophia account, repeat these steps for each — every account has its own API Name and its own redirect URL. ## How the connection flow works Once setup is complete, this is what happens when a user connects an MCP client — no client IDs or secrets ever reach the user: ```mermaid theme={null} sequenceDiagram autonumber participant Client as MCP client (Claude, Cursor, …) participant Prophia as Prophia MCP server participant IdP as Your identity provider Client->>Prophia: Connect to /mcp/v1/{api-name} Prophia-->>Client: 401 + OAuth discovery metadata Client->>Prophia: Register client automatically (RFC 7591) Prophia-->>Client: client_id, plus a client secret if the client asked for one Client->>Prophia: Authorization request (browser opens) Prophia->>IdP: Redirect to your corporate sign-in IdP-->>Prophia: Signed-in user (email claim) Prophia->>Prophia: Consent screen: the user chooses what the client can access Prophia-->>Client: Access token, plus a refresh token if the client has a secret Client->>Prophia: Tool calls with the user's Prophia permissions ``` The user experiences steps 1–9 as a single browser prompt: they sign in with their work account and, on accounts that use role-based permissions, go through the consent screen (step 8). Every OAuth client gets the consent screen, whichever one the user connects. There the user chooses which Prophia capabilities the client gets, and every tool call on that connection is limited to them. A client with a refresh token keeps that choice when it refreshes. A client without one repeats steps 5–9 when its access token expires after 12 hours, consent screen included, and so does any client once the connection reaches its maximum lifetime. See [Choosing what a connection can access](https://docs.prophia.com/developers/mcp/overview.md#choosing-what-a-connection-can-access) and [How long a connection lasts](#how-long-a-connection-lasts). ### How long a connection lasts * **Access tokens last 12 hours.** A client that registered without a client secret signs the user in again when its access token expires. * **A client that registered with a client secret also gets a refresh token**, which it uses to get new access tokens without the user signing in again. Each refresh token lasts 30 days and is replaced every time it's used, so a connection left unused for 30 days ends. * **Every connection ends at your account's maximum connection lifetime**, counted from the user's sign-in, however actively it's used. The client can't refresh past that point, but the access token it already has keeps working until it expires, so a connection can last up to 12 hours longer. After it ends, the user signs in again through your IdP. The lifetime defaults to 30 days. To change it, enter any number of days from 1 to 180 in the **Maximum connection lifetime (days)** field on the **OAuth client for MCP** card (Account Settings → **API/MCP Config** → **Authorization Options** → **MCP OAuth**). ## Step 1 — Copy your redirect URL from Prophia Start in Prophia, not in your IdP — you need the redirect URL before you can create the OIDC application. **1. Open the API/MCP Config tab** In Prophia, go to **Account Settings** and open the **API/MCP Config** tab. **2. Select MCP OAuth** Scroll to the **Authorization Options** card and select the **MCP OAuth** segment. **3. Copy the redirect URL** In the **OAuth client for MCP** card, find **Redirect URL** and click **Copy**. The value is specific to your account and looks like this: ``` https://yosemite-api.prophia.com/mcp/auth/login/oauth2/code/{your-api-name} ``` > [!WARNING] > > **Copy it from the app rather than typing it.** Note the host: the customer-facing MCP URL uses `api.prophia.com`, but the redirect URL uses `yosemite-api.prophia.com`. Registering the wrong host is the most common *configuration* mistake, and it fails silently until a user tries to log in. ## Step 2 — Create an OIDC application in your IdP In your identity provider's admin console, create a new OIDC / OAuth2 application for Prophia: | Setting | Value | | - | - | | **Application type** | Web application, confidential or public. See [Client secret or PKCE?](#client-secret-or-pkce) below before you choose. | | **Redirect URI** | The redirect URL you copied in Step 1. Okta calls this field *Sign-in redirect URIs*. | | **Grant type** | Authorization Code | | **Scopes** | `openid`, `profile`, `email` | | **ID token claims** | Must include the user's `email` | The application you create represents **Prophia** — not Claude, not Cursor. You create one no matter how many users or clients you have. > [!NOTE] > > On some identity providers — Okta custom authorization servers in particular — the `email` claim has to be added to the ID token explicitly rather than relying on the `email` scope. ### Client secret or PKCE? Prophia supports both. Your IdP registration must match the **Public client (PKCE) — no client secret** checkbox you set in Prophia in Step 3; if the two disagree, login fails. **A confidential client with a client secret is the recommended setup**, and the more widely supported of the two. Prophia's server is what talks to your IdP, so it can hold a secret safely. Register the app as a confidential / web application, copy the client secret your IdP generates, and leave the PKCE box unchecked in Prophia. **Use a public client with PKCE** if your IdP won't issue a secret for the app type you need, or your security policy prohibits sharing a client secret with a third party. PKCE (Proof Key for Code Exchange) replaces the stored secret with a one-time challenge generated per login, so there is no shared credential to distribute or rotate. Register the app as a public client with PKCE required, and check the PKCE box in Prophia. If your IdP showed you a client secret to copy, you have a confidential client — public clients don't get one. You can switch later by changing the registration in your IdP and updating the matching setting in Prophia. ### Assign your users to the application Most identity providers won't let anyone sign in to an application they haven't been assigned to. In Okta this is the **Assignments** tab; in Entra ID it's **Users and groups** under **Enterprise applications**, and if the app's **Assignment required?** setting is Yes, unassigned users are refused at the Microsoft sign-in screen. Assign every user or group who should be able to reach Prophia from an AI assistant. > [!WARNING] > > Skipping this produces a login that fails immediately after the IdP screen appears, and it is the most common cause of a setup that looks correct but doesn't work. ### Email matching is required The `email` claim returned by your IdP must exactly match the email on an **existing** Prophia user account. Prophia does not create users on the fly — a user who doesn't already exist in Prophia is rejected with *access denied*, however successfully they signed in. ### Microsoft Entra ID (Azure AD) Here are some typical pitfalls and suggested settings when creating an Entra ID app registration for connecting to Prophia's MCP server. **1. Register the app on the Web platform** In **App registrations → your app → Authentication**, add the Prophia redirect URL under the **Web** platform. > [!WARNING] > > **Do not use "Single-page application."** Entra treats a redirect URI on that platform as a public client and won't let Prophia's server complete the sign-in, with or without a client secret. * Leave **Allow public client flows** set to **Disabled**. * Leave the implicit-grant checkboxes (Access tokens, ID tokens) unchecked. **2. Create a client secret and copy its Value** In **Certificates & secrets → New client secret**, copy the **Value** column, not **Secret ID**. * Entra shows the value only once, right after you create it. If you didn't copy it then, create a new secret. * A secret value is about 40 characters and contains `Q~` near the start, for example `abc8Q~…`. If what you have is a GUID, it's the Secret ID. If it has no `~`, part of it was lost when copying. * Note the expiry date. When the secret expires, logins stop working until you create a new one and save it in Prophia. **3. Find your issuer URL and client ID** * **Issuer URL:** `https://login.microsoftonline.com/{Directory (tenant) ID}/v2.0`, using your tenant ID from the app's Overview page. Don't use `common` or `organizations`. * **Client ID:** the **Application (client) ID** on the app's Overview page. This is a confidential client, so leave the PKCE box unchecked when you enter these values in Step 3. **4. Make sure each user's primary email matches Prophia** Entra fills the `email` claim from the user's **primary email address** (the `mail` attribute), which is not always the sign-in name (UPN). * The primary email must exactly match the email on the user's Prophia account. * **Aliases don't count.** Secondary addresses and proxy addresses aren't sent in the token, so an alias that matches Prophia won't help. * If a user signs in successfully at Microsoft but then gets *access denied*, this mismatch is almost always the reason. Change the user's primary email in Entra or the email in Prophia so they match. ### Collect these values When you're done, take these from your IdP to Step 3: | Field | What it is | Example | | - | - | - | | **Issuer URL** | Base URL of your IdP's OIDC discovery document, *without* `/.well-known/openid-configuration` | `https://acme.okta.com/oauth2/default` | | **Client ID** | The OAuth2 client ID your IdP issued | `0oa1b2c3d4e5f6g7h8i9` | | **Client Secret** | The secret your IdP issued. Skip this only if you registered a public client using PKCE. | — | > [!WARNING] > > **Confirm the issuer URL before you move on.** Many IdPs expose more than one. Okta uses `https://your-org.okta.com` for the org authorization server and `https://your-org.okta.com/oauth2/default` for the default custom one, and only one is right for your application. Open `{issuer-url}/.well-known/openid-configuration` in a browser and check that the `issuer` value in the response matches exactly what you're about to paste into Prophia. ## Step 3 — Register the application with Prophia Return to the **OAuth client for MCP** card — Account Settings → **API/MCP Config** → **Authorization Options** → **MCP OAuth** — and fill in the form: | Field | What to enter | | - | - | | **Issuer URL** | The issuer URL from Step 2. Must start with `http://` or `https://`, or Prophia rejects it. | | **Client ID** | The client ID from Step 2. | | **Public client (PKCE) — no client secret** | Check this **only** if you registered a public client using PKCE. Checking it hides the client secret field. | | **Client secret** | The client secret from Step 2. Required unless you checked the PKCE box. Stored securely and never shown again — on return visits you'll see a masked hint. | | **Maximum connection lifetime (days)** | How many days, from 1 to 180, a user's connection lasts after they sign in before they have to sign in again. Defaults to 30. See [How long a connection lasts](#how-long-a-connection-lasts). | | **Enabled** | Leave checked to turn the OAuth connection on. Uncheck to save the configuration without activating it. | Click **Create**. On success you'll see a confirmation that the OAuth client configuration was saved, and the **Remove** button appears alongside **Save changes**. > [!WARNING] > > **The PKCE checkbox must match how you registered the application in your IdP.** A confidential client with the box checked, or a public client with it unchecked, fails at login. If your IdP showed you a client secret to copy, you have a confidential client — leave the box unchecked. The **Create** button stays greyed out until the issuer URL and client ID are both filled in, the issuer URL starts with `http://` or `https://`, and either a client secret is entered or the PKCE box is checked. When you return later to edit an existing configuration, the secret already stored also satisfies that last condition, so **Save changes** stays available without re-typing it. Prefer not to do this yourself? Send the three values from Step 2 to your Prophia contact or Prophia Support and they'll complete the registration for you. ## Step 4 — Verify There is no test button, and a successful save means the details were *stored*, not that they're *correct*. Verify end to end. Ask a Prophia user at your organization — yourself, if you have an account — to connect an MCP client to `https://api.prophia.com/mcp/v1/{your-api-name}` following [Connect Claude](https://docs.prophia.com/developers/mcp/connect-claude.md) or [Connect other clients](https://docs.prophia.com/developers/mcp/connect-other-clients.md). They should be redirected to your IdP's login page. After signing in, and choosing what the client can access if your account uses role-based permissions, they should be able to use Prophia tools from their assistant. If login fails, work through [Troubleshooting](#troubleshooting) in order. ## Changing or removing the configuration later Return to the same card: * **Update a value** — edit the field and click **Save changes**. * **Rotate the client secret** — create the new secret in your IdP first, paste it in, and click **Save changes**. Leaving the field blank keeps the secret currently stored, so you can change other fields without re-entering it. Remove the old secret from your IdP once you've verified the new one works. * **Turn the connection off** — uncheck **Enabled** and click **Save changes**. Your details are kept, so you can switch it back on later. * **Delete the configuration** — click **Remove** and confirm. This deletes the stored OIDC details entirely; you'd need to re-enter them to restore OAuth access. API key connections are unaffected. > [!NOTE] > > **Turning the connection off, removing it, or changing the issuer URL or client ID ends existing connections.** Users who are already connected keep working until their current access token expires, at most 12 hours, and then have to sign in again. A new maximum connection lifetime also applies to existing connections, so lowering it ends any connection already older than the new limit in the same way. Rotating the client secret or editing other settings doesn't affect them. ## Troubleshooting ### OAuth login opens but fails Check these in order — the first two account for most failures: **1. Are your users assigned to the OIDC application in your IdP?** An unassigned user fails right after the IdP login screen. This is the most common cause. **2. Does the redirect URI in your IdP exactly match the Redirect URL on the card?** Including the `yosemite-api.prophia.com` host. Copy it again from Prophia and compare character for character. **3. Is the issuer URL right?** Fetch `{issuer-url}/.well-known/openid-configuration` and confirm the `issuer` in the response matches what you entered. **4. Does your IdP registration match the PKCE checkbox?** A confidential client with the box checked, or a public client with it unchecked, will fail. **5. Is Enabled checked and saved?** On the **OAuth client for MCP** card. **6. Does the ID token include an email claim that matches a Prophia user?** Your IdP's system log will usually show the claims it issued. ### If you use Microsoft Entra ID Also check these, in order: **1. Is the redirect URI on the Web platform?** Not **Single-page application**. Entra won't let Prophia's server complete the sign-in from a redirect URI registered there. **2. Is Allow public client flows disabled?** In **App registrations → your app → Authentication**. **3. Is the client secret in Prophia the secret's Value, and is it still valid?** Not the **Secret ID**. Check the expiry date in **Certificates & secrets**. **4. Does the user's primary email in Entra exactly match their Prophia email?** Entra sends the primary email (the `mail` attribute), not the sign-in name or any alias. ### Other problems > [accordion] I don't see the API/MCP Config tab > > The tab appears only if you're an **admin** on the Prophia account you're currently viewing, and that account has API access enabled. If you have access to more than one account, check you're focused on the right one. If you're an admin and still don't see it, contact Prophia Support to confirm API access is enabled. > [accordion] The MCP card shows an API Name of "Unknown" > > Your account doesn't have one configured yet, and the connection URL shown alongside it will not work. Contact Prophia Support to have one set before continuing. > [accordion] Prophia rejects the issuer URL when I save > > It must start with `http://` or `https://`. A bare hostname like `acme.okta.com` is rejected. > [accordion] Login succeeds but the user gets "access denied" > > The email your IdP returns doesn't match that user's Prophia email, or they don't have a Prophia user account at all. Prophia won't create one for them. ### If you get stuck If you can't reach the **API/MCP Config** tab, or setup fails and none of the above helps, contact your Prophia contact or Prophia Support and we'll configure it for you. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.