> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect identity and cloud platforms

> Connect Microsoft Entra ID, Microsoft Azure, and Okta to the AI Agent Gateway, so agents can answer questions about your directory, your subscriptions, and your Okta organization.

Microsoft Entra ID, Microsoft Azure, and Okta let an agent answer questions about your identity directory and your cloud control plane through the same governed path as every other application: people authorize the connection themselves, the gateway injects the credential per call, policy applies before each action, and activity is recorded.

They differ from each other in one respect - whose OAuth application the connection runs on.

| Application        | OAuth application used                                                                                                                                                                               | What you need to do                                                         |
| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |
| Microsoft Entra ID | Oleria's - an application used for this connection and nothing else                                                                                                                                  | Enable it, then have an administrator approve organization-wide access.     |
| Microsoft Azure    | Oleria's - again, its own application                                                                                                                                                                | Enable it, and assign the Azure roles that decide what each person can see. |
| Okta               | **Yours.** Okta has no cross-organization application - its sign-in and its API both live on your own `acme.okta.com` host - so the connection is only possible once an administrator registers one. | Create an app integration in Okta and enter its credentials.                |

Each Microsoft connection runs on a **separate** Oleria application - Entra ID, Azure and SharePoint do not share one. That is deliberate, and it changes what you are agreeing to: Microsoft grants consent per *application*, never per connector. Were they to share one, approving Entra ID's directory access would also approve SharePoint's access to your files and sites, and revoking either would revoke both. Because they are separate, the consent screen you see when you connect Entra ID asks for directory access and nothing else.

If you would rather Microsoft ran on an application your organization owns and can revoke, you can supply one - see [Bring your own OAuth app](/governance/ai-agent-gateway-byo-oauth).

<Note>
  Only Oleria Administrators can register an application's credentials. [View role permissions](/administration/default-user-roles).
</Note>

## What an agent can do once connected

Each connection is a governed path to the provider's own API, so an agent can answer questions across the whole read surface the permissions allow.

| Application        | REST API               | MCP | What agents can reach                                                         |
| :----------------- | :--------------------- | :-- | :---------------------------------------------------------------------------- |
| Microsoft Entra ID | Microsoft Graph        | No  | Users, groups, application assignments, and directory sign-in and audit data. |
| Microsoft Azure    | Azure Resource Manager | No  | Subscriptions, resource groups, resources, and role assignments.              |
| Okta               | Okta's management API  | No  | Users, groups, applications, and the system log for your Okta organization.   |

**None of these three is reached through an MCP server.** Azure and Okta each ship an official one, but it runs as a local process on your own machine rather than a hosted endpoint, so there is nothing for the gateway to reach on your behalf. Microsoft does host one for Entra ID, but it is a separate API permission and consent that Oleria's application does not carry. All three call the vendor's REST API, and nothing is lost in what an agent can ask.

See [Application permissions](/governance/ai-agent-gateway-app-permissions) for the mechanism behind every application the gateway brokers.

Questions like "which accounts in the directory have no MFA method registered", "who holds Owner on this subscription", or "which Okta users haven't signed in for 90 days" are answered from live data rather than an export.

Two limits are worth knowing before you connect:

**Entra ID and Okta are connected read-only.** The gateway requests read permissions for the directory. Write actions - creating a user, resetting a password - are not part of these connections, and a request to perform one is refused by the provider.

**In Azure, your own role assignments still decide everything.** The OAuth permission lets the gateway call Azure Resource Manager as you; it grants no access by itself. A person with no Azure role sees nothing, no matter what the gateway's policy says. Grant **Reader** on the subscriptions an agent should be able to answer questions about.

The rest of this page is one self-contained section per application. Follow the one you are connecting; you do not need to read the others.

## Microsoft Entra ID

Entra ID runs on Oleria's own application, so there is nothing to register. One thing is still yours to do, and skipping it produces a connection nobody can complete.

**Callback URL** - already configured on Oleria's application. You only need it if you register your own:

```
https://ai-gateway.prod.oleria.io/connect/apps/entra-id/callback
```

<Steps>
  <Step title="Enable the application">
    In the admin portal, go to **Governance** -> **Oleria AI Agent Gateway**, and on the **OAuth Access** tab select the **Microsoft Entra ID** row. In **Registry**, turn the application on.
  </Step>

  <Step title="Approve organization-wide access">
    Entra ID asks for at least one permission that an ordinary user cannot approve for themselves. Until an administrator approves it, **everyone** who tries to connect is stopped at Microsoft's own screen and connects nothing - not a connection missing one permission - and because they never return to Oleria, the failure does not show up here.

    On the same panel, use **Approve for your organization** under **Organization-wide access**.

    Two different administrator rights are involved, and you need both:

    | Where        | Who                                                                                                                                                            |
    | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | In Oleria    | An Oleria Administrator. [View role permissions](/administration/default-user-roles).                                                                          |
    | At Microsoft | A **Global Administrator** or **Privileged Role Administrator** in your directory. Microsoft enforces this on its own consent screen, whoever starts the flow. |

    You can approve again at any time, and sometimes you will need to. Approval covers the permissions the application asked for on the day it was given, so it can go out of date without anyone revoking anything - when Oleria adds a permission to a connector, or when you change your own registration. The panel shows when it was last approved and who by, which is a record of what happened rather than a guarantee that it still holds: an administrator can revoke consent in Microsoft, or grant it directly there, and neither is visible to Oleria.
  </Step>

  <Step title="Set the risky-operation decisions">
    Entra ID has a roster of risky operations, all of them denied until an administrator decides otherwise. See [Application permissions](/governance/ai-agent-gateway-app-permissions) for what each one covers, and [Set the application's policy](/governance/ai-agent-gateway-admin-setup#set-the-applications-policy) for how to set them.
  </Step>

  <Step title="Verify it worked">
    Connect Entra ID as a user, from the Governance App under **AI Agent Gateway**. Then, in the Microsoft Entra admin center, open **Enterprise applications**, find the application the connection runs on, and review its sign-in activity - that is the evidence traffic is really flowing through it.
  </Step>
</Steps>

### Bringing your own application for Entra ID

Optional, and only if you would rather Entra ID ran on an application your organization owns and can revoke.

<Steps>
  <Step title="Register the application">
    In the Microsoft Entra admin center, go to **Identity** -> **Applications** -> **App registrations** and select **New registration**.

    Give it a name your administrators will recognize, such as `Oleria AI Agent Gateway - Entra ID`. Under **Redirect URI**, choose **Web** and enter the Entra ID callback URL above.
  </Step>

  <Step title="Create a client secret">
    Open **Certificates & secrets** -> **New client secret**. Copy the value immediately - Entra shows it once.

    Note the expiry you choose. When the secret expires, connections stop refreshing and people are treated as not connected until you supply a new one.
  </Step>

  <Step title="Add the API permissions">
    Open **API permissions** -> **Add a permission** -> **Microsoft Graph** -> **Delegated permissions**, and add:

    | Permission           | Why it's needed                                  |
    | :------------------- | :----------------------------------------------- |
    | `User.Read`          | Identify the account that connected.             |
    | `Directory.Read.All` | Read users, groups, and application assignments. |

    Then select **Grant admin consent**. `Directory.Read.All` cannot be consented to by an individual - without this step every person who tries to connect is stopped by Microsoft's own consent screen, not by Oleria.
  </Step>

  <Step title="Collect the values Oleria needs">
    From the registration's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**. You already have the client secret.

    Supply the **Directory (tenant) ID** whenever your registration is single-tenant, which is the default for a new one. Without it, Microsoft rejects the sign-in with `AADSTS50194`.
  </Step>

  <Step title="Enter the credentials in Oleria">
    On the **Microsoft Entra ID** row under **OAuth Access**, turn on **Bring your own credentials** and enter the **Application (client) ID**, the **Client Secret**, and the **Directory (tenant) ID**.

    The Directory (tenant) ID is not optional bookkeeping - it completes the address the gateway signs people in at. The gateway refuses to start a sign-in while it is missing, rather than sending people to an address that cannot work.

    The client secret is encrypted with your tenant's own key and is never displayed again after saving. Select **Save**.
  </Step>
</Steps>

<Note>
  Connecting Azure as well? Register a **second** application for it rather than adding Azure to this one - see the Azure section below for why.
</Note>

## Microsoft Azure

Azure runs on Oleria's own application, so there is nothing to register. One thing is still yours to do, and skipping it produces a connection that works and answers nothing.

**Callback URL** - already configured on Oleria's application. You only need it if you register your own:

```
https://ai-gateway.prod.oleria.io/connect/apps/azure/callback
```

<Steps>
  <Step title="Enable the application">
    In the admin portal, go to **Governance** -> **Oleria AI Agent Gateway**, and on the **OAuth Access** tab select the **Microsoft Azure** row. In **Registry**, turn the application on.
  </Step>

  <Step title="Grant Azure roles to the people who will use it">
    In each subscription an agent should cover, open **Access control (IAM)** and assign **Reader** (or a narrower custom role) to those people.

    The OAuth permission lets the gateway call Azure as you; it grants access to nothing by itself. Skipping this produces a connection that works and answers nothing: Azure returns an empty list of subscriptions, with no error to read.
  </Step>

  <Step title="Set the risky-operation decisions">
    Azure has a roster of risky operations, all of them denied until an administrator decides otherwise. See [Application permissions](/governance/ai-agent-gateway-app-permissions) for what each one covers, and [Set the application's policy](/governance/ai-agent-gateway-admin-setup#set-the-applications-policy) for how to set them.
  </Step>

  <Step title="Verify it worked">
    Connect Azure as a user, from the Governance App under **AI Agent Gateway**, and ask an agent which subscriptions it can see. An empty answer from someone who *should* see subscriptions means the role assignment in the previous step is missing, not the connection.
  </Step>
</Steps>

### Bringing your own application for Azure

Optional, and only if you would rather Azure ran on an application your organization owns and can revoke.

<Steps>
  <Step title="Register a separate application">
    Register it the same way as the Entra ID one - **App registrations** -> **New registration**, a recognizable name such as `Oleria AI Agent Gateway - Azure`, **Redirect URI** of type **Web** set to the Azure callback URL above - then create a client secret under **Certificates & secrets**.

    You *can* instead add Azure to your Entra ID registration, by adding the Azure callback as a second **Web** redirect URI. It works, and it is the trade most organizations regret. Consent in Microsoft is granted per **application**: one registration serving both means whoever approves Entra ID's directory access approves cloud control-plane access at the same moment, on the same screen, and revoking one revokes the other. A second registration costs one more secret to rotate and keeps the two decisions separate - which is why Oleria's own applications are split this way.
  </Step>

  <Step title="Add the API permission">
    Open **API permissions** -> **Add a permission** -> **Azure Service Management** -> **Delegated permissions**, and add `user_impersonation`.
  </Step>

  <Step title="Collect the values Oleria needs">
    From the registration's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**. You already have the client secret.

    Supply the **Directory (tenant) ID** whenever your registration is single-tenant, which is the default for a new one. Without it, Microsoft rejects the sign-in with `AADSTS50194`.
  </Step>

  <Step title="Enter the credentials in Oleria">
    On the **Microsoft Azure** row under **OAuth Access**, turn on **Bring your own credentials** and enter the **Application (client) ID**, the **Client Secret**, and the **Directory (tenant) ID**. Select **Save**.
  </Step>
</Steps>

## Okta

Okta has no cross-organization application - its sign-in and its API both live on your own `acme.okta.com` host - so there is always an app integration for you to create. Everything in this section is required.

**Callback URL** - enter this as the sign-in redirect URI on the integration you create:

```
https://ai-gateway.prod.oleria.io/connect/apps/okta/callback
```

<Steps>
  <Step title="Create the app integration">
    In the Okta Admin Console, go to **Applications** -> **Applications** -> **Create App Integration**. Choose **OIDC - OpenID Connect** and **Web Application**.

    Under **Sign-in redirect URIs**, enter the Okta callback URL above. Under **Grant type**, keep **Authorization Code** and also select **Refresh Token** - without it, people have to sign in again every hour.
  </Step>

  <Step title="Assign the people who will use it">
    On the integration's **Assignments** tab, assign the people or groups who will connect Okta - the same way you would for any other Okta application.

    Okta will not sign an unassigned person in, so skipping this stops each of them at Okta rather than at Oleria, with nothing on the Oleria side to show why.
  </Step>

  <Step title="Grant the Okta API scopes">
    This is the step that is easy to miss, because nothing about creating the integration hints at it.

    Open the integration's **Okta API Scopes** tab and grant these scopes:

    | Scope              | Why it's needed                                                |
    | :----------------- | :------------------------------------------------------------- |
    | `okta.users.read`  | Read user accounts and their status.                           |
    | `okta.groups.read` | Read groups and their membership.                              |
    | `okta.apps.read`   | Read application assignments.                                  |
    | `okta.logs.read`   | Read the system log, for sign-in and admin activity questions. |

    These are your organization's own Okta management scopes, granted to the integration on this tab - not scopes you add to a custom authorization server under **Security** -> **API**. Okta does not grant them because the gateway asks for them. An integration that skips this connects successfully and then refuses every call.
  </Step>

  <Step title="Collect the values Oleria needs">
    From the integration's **General** tab, copy the **Client ID** and the **Client Secret**. You also need your organization's Okta URL, such as `https://acme.okta.com` - the host you sign in to.
  </Step>

  <Step title="Enable the application and enter the credentials">
    In the admin portal, go to **Governance** -> **Oleria AI Agent Gateway**, and on the **OAuth Access** tab select the **Okta** row. In **Registry**, turn the application on, turn on **Bring your own credentials**, and fill in **Client ID**, **Client Secret**, and **Okta Org URL**.

    The org URL is not optional bookkeeping - it completes the address the gateway signs people in at, since Okta authenticates against your organization's own host. The gateway refuses to start a sign-in while it is missing, rather than sending people to an address that cannot work. It must be `https`.

    The client secret is encrypted with your tenant's own key and is never displayed again after saving.
  </Step>

  <Step title="Set the risky-operation decisions">
    Okta has a roster of risky operations, all of them denied until an administrator decides otherwise. See [Application permissions](/governance/ai-agent-gateway-app-permissions) for what each one covers, and [Set the application's policy](/governance/ai-agent-gateway-admin-setup#set-the-applications-policy) for how to set them.

    Then select **Save**. Every field shown for the application is required - the gateway will not start a sign-in until each is supplied.
  </Step>

  <Step title="Verify it worked">
    Connect Okta as a user, from the Governance App under **AI Agent Gateway**, and check the consent screen - it should name your own integration.

    Then confirm it from Okta's side, which is the evidence that traffic is running through your client: open the app integration and check **Reports** or the System Log for authorizations against it.
  </Step>
</Steps>

## When credentials change

Two changes break existing connections, and neither announces itself:

**Rotating a client secret you own.** Update it in the **Registry** section as soon as you rotate it in the provider. Until you do, tokens fail to refresh as they expire, and people are gradually treated as not connected. Oleria's own applications are rotated by Oleria, and need nothing from you.

**Switching to a different registration.** Tokens issued to the old client cannot be refreshed by a new one. Ask anyone already using the application to disconnect and reconnect - it takes a few seconds.

If a required field is missing, the gateway stops the sign-in and says so, naming the field to set. That is the intended behavior: a connection is never made against a partially configured application.

## Contact us

For questions, contact us at [support@oleria.com](mailto:support@oleria.com).