Skip to main content
Connect OneLogin to authenticate end users with your Char widget. Create an OIDC application in OneLogin and configure Char for token validation.

Prerequisites

  • A OneLogin account with admin access
  • Access to create applications in OneLogin Admin Portal
  • Access to the Char dashboard

SDK References

Configuration Steps

1

Create an OIDC Application in OneLogin

  1. Sign in to the OneLogin Admin Portal
  2. Navigate to ApplicationsApplications
  3. Click Add App
  4. Search for “OpenID Connect” or “OIDC”
  5. Select OpenId Connect (OIDC) from the results
  6. Click Save
2

Configure Application Settings

On the Configuration tab:
SettingValue
Login URLYour application’s login page URL
Redirect URI’sYour callback URLs (e.g., https://yourapp.com/callback)
Post Logout Redirect URIYour logout redirect URL
Token EndpointWeb
Application TypeSingle Page App (SPA)
Click Save.
3

Configure SSO Settings

On the SSO tab:
  1. Note your Client ID
  2. Set Token Endpoint Authentication Method to None (for SPA)
  3. Under Token, ensure ID Token is enabled
  4. Click Save
OneLogin SSO Settings

Find your Client ID and configure SSO settings

4

Note Your Subdomain and Client ID

From OneLogin:
  1. Subdomain: Your OneLogin subdomain (e.g., acme from acme.onelogin.com)
  2. Client ID: Found on the SSO tab of your application
  3. Region: Note if you’re using US (us) or EU (eu) region
The issuer URL format depends on your region:
  • US: https://{subdomain}.onelogin.com/oidc/2
  • EU: https://{subdomain}.eu.onelogin.com/oidc/2
5

Configure Char

In the Char Dashboard:
  1. Navigate to SettingsIntegration
  2. Under SSO Configuration, select Custom OIDC as the provider
  3. Enter your configuration:
FieldValue
Client IDYour OneLogin Client ID
Issuer URLhttps://{subdomain}.onelogin.com/oidc/2
  1. Click Test Connection to verify
  2. Click Save Changes

Configuration Reference

Char FieldOneLogin ValueExample
Provider TypeCustom OIDCcustom_oidc
Client IDApplication Client IDa1b2c3d4-e5f6-7890-abcd-ef1234567890
Issuer URLOIDC issuerhttps://acme.onelogin.com/oidc/2
OneLogin uses /oidc/2 in the issuer URL path. This is the OIDC 2.0 endpoint. Don’t omit this suffix.

Token Requirements

Char validates OneLogin tokens with these requirements:
ClaimRequirement
issMust match https://{subdomain}.onelogin.com/oidc/2
audMust include your configured Client ID
subRequired - OneLogin user ID
expMust not be expired

Standard OneLogin ID Token Claims

ClaimDescription
subOneLogin user ID
emailUser’s email address
preferred_usernameUser’s username
nameUser’s full name
given_nameFirst name
family_nameLast name
groupsUser’s group memberships (if configured)
paramsCustom parameters (if configured)

Example: Obtaining and Passing the Token

import { UserManager } from 'oidc-client-ts';
import "@mcp-b/embedded-agent/web-component";

const userManager = new UserManager({
  authority: 'https://acme.onelogin.com/oidc/2',
  client_id: 'your-client-id',
  redirect_uri: window.location.origin + '/callback',
  response_type: 'code',
  scope: 'openid profile email groups',
});

// After callback handling
userManager.getUser().then((user) => {
  if (user && user.id_token) {
    const agent =
      document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

    if (!agent.isConnected) {
      document.body.appendChild(agent);
    }

    agent.setAttribute("auth-token", user.id_token);
  }
});

Including Groups in Token

To include group memberships in the ID token:
  1. In OneLogin Admin, go to your OIDC application
  2. Navigate to Parameters tab
  3. Click Add Parameter
  4. Configure:
SettingValue
Field namegroups
Include in SAML assertionUnchecked
Include in OpenID Connect assertionChecked
ValueUser Roles (or Groups)
  1. Click Save
// Groups are now included in the token
const tokenClaims = parseJwt(idToken);
console.log('User groups:', tokenClaims.groups);

Custom Parameters

Add custom claims to your tokens:
  1. Navigate to your application’s Parameters tab
  2. Click Add Parameter
  3. Configure:
SettingValue
Field nameYour custom claim name
Include in OpenID Connect assertionChecked
ValueSelect source (User attribute, Macro, etc.)
  1. Click Save
Example for adding department:
// Custom department claim
const tokenClaims = parseJwt(idToken);
console.log('Department:', tokenClaims.department);

OneLogin Regions

OneLogin has multiple regional deployments:
RegionAdmin URLIssuer URL
USadmin.us.onelogin.comhttps://{subdomain}.onelogin.com/oidc/2
EUadmin.eu.onelogin.comhttps://{subdomain}.eu.onelogin.com/oidc/2
Ensure you use the correct regional URL for your OneLogin instance. EU customers must include .eu in the issuer URL.

Troubleshooting

The issuer URL doesn’t match:
  1. Include /oidc/2 suffix: The issuer URL must include /oidc/2
  2. Check region: EU customers must use {subdomain}.eu.onelogin.com
  3. Verify subdomain: Ensure the subdomain matches exactly
  4. No trailing slash: The URL should not end with /
The token’s audience doesn’t match:
  • Verify the Client ID matches exactly (including hyphens)
  • Check that you’re using the ID token, not the access token
  • Ensure the application type is set correctly (SPA for public clients)
Char couldn’t reach OneLogin’s JWKS endpoint:
  • JWKS endpoint: https://{subdomain}.onelogin.com/oidc/2/certs
  • Verify your subdomain is correct
  • Check regional endpoint if applicable
  • Use Test Connection in the dashboard
If groups aren’t in the token:
  • Verify the groups parameter is configured on the application
  • Ensure Include in OpenID Connect assertion is checked
  • Request the groups scope in your authentication request
If users can’t authenticate:
  • In OneLogin Admin, go to Users → select user → Applications
  • Ensure the user is assigned to the OIDC application
  • Or configure the application with Self Service enabled

Directory Integration

OneLogin can sync users from various directories:
  • Active Directory: Via OneLogin AD Connector
  • LDAP: Direct LDAP integration
  • Google Workspace: Via API integration
  • Workday: HR-driven provisioning
Directory attributes can be mapped to custom token claims using the Parameters feature.

Security Best Practices

  • Enable MFA in OneLogin policies
  • Configure session timeout appropriately for your security requirements
  • Use role-based access to control which users can access your application
  • Enable Smart Hooks for additional authentication logic
  • Monitor sign-in events in OneLogin Events
  • Review application access regularly
  • Configure IP restrictions if needed for your organization
  • Enable Account Recovery securely