Integrating with Agentic Fabriq MCP using External IdP Authentication

Part 1: External IdP Setup (Okta Example)

Step 1: Create an Application in Your IdP

For Okta:

1. Log in to Okta Admin Console
2. Go to Applications → Create App Integration
3. Select:
   • Sign-in method: OIDC - OpenID Connect
   • Application type: Web Application
4. Configure:
   • Name: Your application name
   • Grant type: Authorization Code
   • Sign-in redirect URIs: http://localhost:8080/callback
   • Controlled access: Based on your requirements
5. Save and note:
   • Client ID
   • Client Secret
   • Okta Domain (e.g., trial-3670632.okta.com)

Step 2: Configure Scopes

Ensure these scopes are enabled:

• openid (required)
• profile (recommended)
• email (recommended)

Step 3: Assign Users

1. Go to your app → Assignments
2. Assign users or groups that should have access

Step 4: Configure Access Policies

1. Go to Security → API → default
2. Under Access Policies, ensure your app is allowed
3. Create a policy/rule if needed that grants openid, profile, email scopes

Step 5: Get Credentials

Find and save the APP_ID and APP_SECRET assigned to the app you just created in your IDP.

Part 2: Agentic Fabriq Setup

Step 1: Create an Application

1. Log in to Agentic Fabriq Dashboard
2. Navigate to the admin console, and find the tab: Applications → Create Application
3. Fill in: Application Name: Your app name
4. Add scopes that you want the application to have
5. Click Create
6. Save the activation key
7. Select which users will have access to this application

Step 2: Activate and Get Credentials

1. After creation, click Activate
2. Fill in:
   • Application ID: Application ID from Step 1
   • IdP Client ID: APP_ID from app setup in IdP
   • IdP Client Secret: APP_SECRET from app setup in IdP
3. Save these credentials securely:
   • App ID: org-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_my-app
   • App Secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Step 3: Get Your Organization Identifier

Your organization identifier (org_url) is provided by Agentic Fabriq. This identifies your organization in the token exchange process.

Example values:

• testuser
• mycompany
• acme-corp

Step 4: Configure Tool Access

1. Go to your application → Tools tab
2. Enable the MCP servers/tools your users should access
3. Configure permissions for each tool as needed

Part 3: Application Integration

Step 1: Install the SDK

pip install agentic-fabriq-sdkcopy

Step 2: Configure Environment Variables

# Agentic Fabriq Application Credentials
AF_APP_ID="org-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_my-app"
AF_APP_SECRET="your-app-secret"
AF_ORG_URL="your-org-identifier"

# External IdP (Okta) Configuration
OAUTH_CLIENT_ID="your-okta-client-id"
OAUTH_CLIENT_SECRET="your-okta-client-secret"
OPENID_PROVIDER_URL="https://your-domain.okta.com/oauth2/default/.well-known/openid-configuration"
OAUTH_REDIRECT_URI="http://localhost:8080/callback"
OAUTH_SCOPES="openid profile email"copy

Step 3: Implement the OAuth Flow

Your application needs to authenticate users through your external IdP:

from authlib.integrations.starlette_client import OAuth

oauth = OAuth()
oauth.register(
    name='okta',
    client_id=OAUTH_CLIENT_ID,
    client_secret=OAUTH_CLIENT_SECRET,
    server_metadata_url=OPENID_PROVIDER_URL,
    client_kwargs={'scope': 'openid profile email'}
)

@app.get("/login")
async def login(request: Request):
    redirect_uri = OAUTH_REDIRECT_URI
    return await oauth.okta.authorize_redirect(request, redirect_uri)

@app.get("/callback")
async def callback(request: Request):
    token = await oauth.okta.authorize_access_token(request)
    access_token = token.get("access_token")
    # Store access_token in session for MCP calls
    request.session["idp_token"] = access_token
    return RedirectResponse("/")copy

Step 4: Connect to MCP Servers

Use the af_sdk.MCPClient with the idp method:

from af_sdk import MCPClient

# Get the external IdP token from your session
external_token = get_user_idp_token()  # Your session management

# Create the MCP client
async with MCPClient(
    method="idp",
    app_id="org-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_my-app",
    app_secret="your-app-secret",
    external_token=external_token,
    org_url="your-org-identifier",
) as client:
    # List available tools
    tools = await client.list_tools()
    print(f"Available tools: {[t['name'] for t in tools]}")
    
    # Call a tool
    result = await client.call_tool("tool-name", {"param": "value"})
    print(result)copy

Part 4: SDK Reference

MCPClient Parameters (IdP Method)

Available Methods

# List all available tools
tools = await client.list_tools()

# Call a specific tool
result = await client.call_tool(name="tool-name", arguments={"key": "value"})

# Check if a tool exists
exists = client.has_tool("tool-name")

# Get tool names
names = client.tool_names

# Get a specific tool definition
tool = client.get_tool("tool-name")copy

Synchronous Usage

from af_sdk import MCPClient

with MCPClient(
    method="idp",
    app_id=APP_ID,
    app_secret=APP_SECRET,
    external_token=token,
    org_url=ORG_URL,
) as client:
    tools = client.list_tools_sync()
    result = client.call_tool_sync("tool-name", {"param": "value"})copy

Part 5: Token Lifecycle

Token Expiration

• External IdP tokens typically expire in 1-24 hours (varies by IdP)
• The SDK exchanges tokens on connect()
• For long sessions, refresh the IdP token and create a new client

# When IdP token is refreshed
new_idp_token = await refresh_idp_token()

# Create new MCP client with fresh token
client = MCPClient(
    method="idp",
    app_id=APP_ID,
    app_secret=APP_SECRET,
    external_token=new_idp_token,
    org_url=ORG_URL,
)
await client.connect()copy

Part 6: Error Handling

Common Errors

from af_sdk.auth.applications import AuthenticationError

try:
    async with MCPClient(...) as client:
        tools = await client.list_tools()
except AuthenticationError as e:
    if "401" in str(e):
        # Token expired or invalid
        print("Please log in again")
    elif "Organization" in str(e):
        # org_url is incorrect
        print("Check your organization identifier")
    elif "AUTHENTICATION_FAILED" in str(e):
        # Credentials incorrect
        print("Check your app_id, app_secret, or org_url")copy

Troubleshooting

External IdP Troubleshooting

Part 7: Supported Identity Providers

The idp method works with any OAuth 2.0 / OIDC compliant identity provider:

Provider-Specific Notes

Okta:

# Use the access token, not the ID token
external_token = oauth_response.get("access_token")copy

Part 8: Best Practices

Security

1. Never expose secrets - Keep app_secret server-side only
2. Use HTTPS - Always use TLS in production
3. Validate tokens - Verify IdP tokens before using them
4. Principle of least privilege - Only enable needed tools
5. Rotate secrets - Regularly rotate both IdP and AF credentials

Performance

1. Reuse clients - Keep MCPClient instances for multiple calls
2. Handle disconnects - Implement reconnection logic
3. Cache tool lists - Don't call list_tools() on every request

Quick Start Checklist

• ☐ Created application in your external IdP (Okta, etc.)
• ☐ Configured redirect URIs and scopes in IdP
• ☐ Assigned users to the IdP application
• ☐ Set up access policies in IdP
• ☐ Created application in Agentic Fabriq Dashboard
• ☐ Activated AF application and saved credentials
• ☐ Got your organization identifier (org_url) from AF
• ☐ Configured tool access permissions in AF
• ☐ Installed agentic-fabriq-sdk
• ☐ Implemented OAuth flow with external IdP
• ☐ Integrated MCPClient with method="idp" and org_url
• ☐ Tested tool listing and calling
• ☐ Implemented token refresh logic
• ☐ Added error handling for auth failures