Skip to main content

Securing Coginiti with OAuth OIDC Authentication

This guide walks you through configuring OAuth OpenID Connect (OIDC) authentication for Coginiti Team and Enterprise using popular identity providers. OIDC integration enables single sign-on (SSO) and centralized user management for your organization.

Overview​

OAuth OIDC authentication allows users to log into Coginiti using their existing corporate credentials from supported identity providers. This eliminates the need for separate Coginiti passwords and provides centralized access control.

Supported Identity Providers​

Coginiti supports any OIDC-compliant identity provider, including:

  • Okta
  • Microsoft Azure Active Directory (Entra ID)
  • Google Workspace
  • Auth0
  • Keycloak
  • AWS Cognito
  • Ping Identity
  • Custom OIDC providers

Prerequisites​

Before configuring OIDC authentication, ensure you have:

Coginiti Requirements​

  • Admin access to your Coginiti Team or Enterprise instance
  • Coginiti hostname configured with HTTPS (required for OIDC)
  • Valid SSL certificate installed and properly configured

Identity Provider Requirements​

  • Admin access to your identity provider (Okta, Azure AD, etc.)
  • Ability to create applications in your identity provider
  • User accounts in the identity provider with email addresses matching Coginiti users
HTTPS Required

OIDC authentication requires HTTPS. Ensure your Coginiti instance is properly configured with a valid SSL certificate before proceeding.

Okta Configuration​

Step 1: Access Okta Admin Console​

  1. Log into your Okta account as an administrator
  2. Your Okta admin URL should resemble: https://{your-org}-admin.okta.com/

Step 2: Create New Application​

  1. Navigate to Applications → Applications
  2. Click Create App Integration
  3. Select the following options:
    • Sign-in method: OIDC - OpenID Connect
    • Application type: Web Application
  4. Click Next

Step 3: Configure Application Settings​

Fill in the application configuration:

Basic Settings:

  • App integration name: Coginiti Team (or your preferred name)
  • Logo: Upload Coginiti logo (optional)

Grant Types:

  • ✅ Authorization Code (required)
  • ✅ Refresh Token (recommended)
  • ❌ Client Credentials (not needed for user authentication)

Sign-in redirect URIs:

https://your-coginiti-hostname/api/auth/authorization-code/callback

Sign-out redirect URIs:

https://your-coginiti-hostname

Controlled access:

  • Select Allow everyone in your organization to access or limit to specific groups
  1. Click Save to create the application

Step 4: Retrieve Client Credentials​

  1. Navigate to the newly created application's General tab
  2. Note the following values (you'll need these for Coginiti configuration):
    • Client ID
    • Client Secret (click Show to reveal)

Step 5: Assign Users and Groups​

  1. Go to the Assignments tab
  2. Click Assign → Assign to People or Assign to Groups
  3. Add users who should have access to Coginiti
  4. Ensure assigned users have email addresses that match their Coginiti user accounts

Step 6: Get Okta URLs​

From your Okta organization, note these URLs (replace your-org with your actual Okta organization name):

  • Authorization URL: https://your-org.okta.com/oauth2/default/v1/authorize
  • Token URL: https://your-org.okta.com/oauth2/default/v1/token
  • User Info URL: https://your-org.okta.com/oauth2/default/v1/userinfo

Azure Active Directory (Entra ID) Configuration​

Step 1: Access Azure Portal​

  1. Log into the Azure Portal as an administrator
  2. Navigate to Microsoft Entra ID (formerly Azure Active Directory)

Step 2: Register New Application​

  1. Go to App registrations → New registration

  2. Configure the registration:

    • Name: Coginiti Team
    • Supported account types: Accounts in this organizational directory only
    • Redirect URI:
      • Platform: Web
      • URI: https://your-coginiti-hostname/api/auth/authorization-code/callback

  3. Click Register

Step 3: Configure Authentication​

  1. Navigate to Authentication in the left sidebar
  2. Under Redirect URIs, ensure you have: 
    https://your-coginiti-hostname/api/auth/authorization-code/callback
  3. Under Front-channel logout URL, add: 
    https://your-coginiti-hostname
  4. Under Implicit grant and hybrid flows, check:
    • ✅ ID tokens (used for implicit and hybrid flows)

Step 4: Create Client Secret​

  1. Navigate to Certificates & secrets
  2. Click New client secret
  3. Add description: Coginiti OIDC Integration
  4. Choose expiration (recommend 24 months maximum)
  5. Click Add and copy the secret value immediately (it won't be shown again)

Step 5: Configure API Permissions​

  1. Navigate to API permissions
  2. Ensure these Microsoft Graph permissions are granted:
    • openid (Sign users in)
    • profile (View users' basic profile)
    • email (View users' email address)
  3. Click Grant admin consent if required

Step 6: Get Azure AD URLs​

From your application's Overview page, note:

  • Application (client) ID
  • Directory (tenant) ID

Your Azure AD URLs will be:

  • Authorization URL: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
  • Token URL: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
  • User Info URL: https://graph.microsoft.com/oidc/userinfo

Google Workspace Configuration​

Step 1: Access Google Cloud Console​

  1. Go to the Google Cloud Console
  2. Select your project or create a new one

Step 2: Enable Google+ API​

  1. Navigate to APIs & Services → Library
  2. Search for "Google+ API" and enable it
  3. Also enable "OpenID Connect" if available

Step 3: Create OAuth Client​

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth client ID
  3. If you haven't already configured the OAuth consent screen, you'll be prompted to do so first. Fill out the required fields and save.
  4. Configure the OAuth client:
    • Application type: Web application
    • Name: Coginiti Team
    • Authorized JavaScript origins: 
      https://your-coginiti-hostname
    • Authorized redirect URIs: 
      https://your-coginiti-hostname/api/auth/authorization-code/callback

Step 4: Get Google Credentials​

After creating the OAuth client, note:

  • Client ID
  • Client Secret

Google's OIDC URLs are:

  • Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
  • Token URL: https://oauth2.googleapis.com/token
  • User Info URL: https://openidconnect.googleapis.com/v1/userinfo

Coginiti Configuration​

Step 1: Access Coginiti Admin Settings​

  1. Log into Coginiti Team or Enterprise as an administrator
  2. Navigate to Settings → Authentication or Identity Providers section
Navigation May Vary

The exact navigation path may vary depending on your Coginiti version. Look for "Authentication", "SSO", "Identity Providers", or "OIDC" settings.

Step 2: Configure OIDC Provider​

Fill in the OIDC configuration form with the values from your identity provider:

For Okta:​

  • Provider Name: Okta (or custom name)
  • Client ID: {client-id-from-okta}
  • Client Secret: {client-secret-from-okta}
  • Authorization URL: https://your-org.okta.com/oauth2/default/v1/authorize
  • Token URL: https://your-org.okta.com/oauth2/default/v1/token
  • User Info URL: https://your-org.okta.com/oauth2/default/v1/userinfo
  • Scopes: openid profile email
  • Redirect URI: https://your-coginiti-hostname/api/auth/authorization-code/callback

For Azure AD:​

  • Provider Name: Azure AD (or custom name)
  • Client ID: {application-client-id}
  • Client Secret: {client-secret-value}
  • Authorization URL: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
  • Token URL: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
  • User Info URL: https://graph.microsoft.com/oidc/userinfo
  • Scopes: openid profile email
  • Redirect URI: https://your-coginiti-hostname/api/auth/authorization-code/callback

For Google Workspace:​

  • Provider Name: Google (or custom name)
  • Client ID: {google-client-id}
  • Client Secret: {google-client-secret}
  • Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
  • Token URL: https://oauth2.googleapis.com/token
  • User Info URL: https://openidconnect.googleapis.com/v1/userinfo
  • Scopes: openid profile email
  • Redirect URI: https://your-coginiti-hostname/api/auth/authorization-code/callback

Step 3: Save and Test Configuration​

  1. Click Save or Update to save the OIDC configuration
  2. The system should validate the configuration automatically
  3. If validation fails, check your URLs and credentials

User Management​

Creating Users in Coginiti​

Before users can authenticate via OIDC, they must exist in Coginiti with matching email addresses:

Option 1: Pre-create Users​

  1. Navigate to Users or User Management in Coginiti admin
  2. Create users with email addresses that match their identity provider accounts
  3. Users can be created without passwords when using OIDC

Option 2: Just-in-Time (JIT) Provisioning​

Some Coginiti configurations support automatic user creation:

  1. Enable JIT provisioning in OIDC settings (if available)
  2. Set default roles/permissions for new users
  3. Users will be created automatically on first login

User Role Mapping​

Configure how identity provider roles/groups map to Coginiti permissions:

  1. Manual Assignment: Assign Coginiti roles manually after user creation
  2. Group Mapping: Map identity provider groups to Coginiti roles (if supported)
  3. Claim Mapping: Use OIDC claims to determine user permissions

Testing OIDC Authentication​

Step 1: Test Configuration​

  1. Log out of Coginiti completely
  2. Navigate to your Coginiti login page
  3. You should see an OIDC login option (e.g., "Sign in with Okta")

Step 2: Perform Login Test​

  1. Click the OIDC login button
  2. You should be redirected to your identity provider's login page
  3. Enter your identity provider credentials
  4. You should be redirected back to Coginiti and logged in

Step 3: Verify User Information​

  1. Check that your user profile shows correct information from the identity provider
  2. Verify you have appropriate permissions and roles assigned

Troubleshooting​

Common Issues​

"Invalid Redirect URI" Error​

Symptoms: Error during login redirect Solutions:

  1. Check redirect URI configuration in both identity provider and Coginiti
  2. Ensure URLs match exactly (including https:// and port if needed)
  3. Verify there are no trailing slashes or extra characters

"Invalid Client ID or Secret" Error​

Symptoms: Authentication fails with client credential errors Solutions:

  1. Verify Client ID and Secret are copied correctly
  2. Check for extra spaces or hidden characters
  3. Regenerate client secret in identity provider if needed

"User Not Found" Error​

Symptoms: Authentication succeeds but user cannot access Coginiti Solutions:

  1. Ensure user exists in Coginiti with matching email address
  2. Check user is active and has appropriate roles assigned
  3. Verify email claim is being returned correctly from identity provider

SSL/HTTPS Issues​

Symptoms: OIDC redirects fail or connection errors Solutions:

  1. Ensure Coginiti is accessible via HTTPS with valid certificate
  2. Check certificate expiration and CA trust chain
  3. Test HTTPS connectivity from identity provider's perspective

Debugging Steps​

Check OIDC Configuration​

  1. Verify all URLs are accessible from Coginiti server
  2. Test OIDC discovery endpoint if available: 
    curl https://your-org.okta.com/.well-known/openid_configuration
  3. Confirm scopes are supported by identity provider

Examine Logs​

Check Coginiti application logs for OIDC-related errors:

  • Authentication request logs
  • Token exchange logs
  • User information retrieval logs
  • Permission assignment logs

Test Claims​

Verify that required claims are being returned:

  • sub (subject/user ID)
  • email (user email address)
  • name or given_name/family_name (user name)
  • Custom claims for role mapping

Security Best Practices​

Credential Management​

  • Never expose client secrets in client-side code or public repositories
  • Rotate credentials regularly (every 6-12 months)
  • Use secure storage for client secrets in production
  • Limit client permissions to only required scopes

Network Security​

  • Use HTTPS for all OIDC endpoints and redirects
  • Validate SSL certificates and certificate chains
  • Implement proper firewall rules for identity provider communication
  • Consider IP whitelisting for enhanced security

User Access Control​

  • Review user assignments regularly in identity provider
  • Implement least privilege access principles
  • Monitor authentication logs for suspicious activity
  • Set up alerts for failed authentication attempts

Token Security​

  • Use short-lived tokens when possible
  • Implement proper token refresh mechanisms
  • Secure token storage in browser/client applications
  • Log out users when tokens expire

Advanced Configuration​

Custom Claims Mapping​

If your identity provider supports custom claims:

  1. Configure claims in your identity provider to include:

    • User roles or groups
    • Department information
    • Custom attributes

  2. Map claims in Coginiti to:

    • User permissions
    • Default workspaces
    • Resource access levels

Multiple Identity Providers​

Coginiti may support multiple OIDC providers simultaneously:

  1. Configure each provider with unique names
  2. Present multiple login options to users
  3. Handle user conflicts when same email exists across providers
  4. Manage provider priorities and fallback options

SAML vs OIDC​

Consider SAML if your organization requires:

  • Enhanced security assertions
  • Complex attribute mapping
  • Encrypted assertions
  • Legacy system compatibility

Support and Resources​

Getting Help​

For OIDC configuration assistance:

  • Coginiti Support: support@coginiti.co
  • Identity Provider Documentation: Consult your IdP's official docs
  • Community Forums: Stack Overflow with appropriate tags

Additional Resources​

Summary​

You have successfully configured OAuth OIDC authentication for Coginiti! Key achievements:

✅ Identity Provider: Configured application in your IdP with proper settings ✅ Coginiti Integration: Configured OIDC settings with correct URLs and credentials ✅ User Management: Set up user accounts and role assignments ✅ Security: Implemented secure authentication flow with HTTPS ✅ Testing: Verified login flow works correctly

Your users can now authenticate to Coginiti using their existing corporate credentials, providing a seamless single sign-on experience while maintaining centralized access control.