Okta/Auth0

How to Integrate Okta with Strapi

Integrating Okta with Strapi requires careful configuration on both platforms. Let's walk through a step-by-step process to achieve a production-ready Single Sign-On implementation.

Prerequisites

Before starting, you'll need:

• Node.js: Version 18 or higher installed
• Strapi Enterprise Edition Gold: Version 4.0.1 or newer (SSO requires Enterprise plan or the add-on)
• Administrative Access: Admin privileges in both Okta and Strapi
• Network Access: Ability to configure redirect URIs and secure connections between platforms

We'll use OpenID Connect (OIDC) protocol, which is the recommended standard for new Okta integrations. Your Strapi instance must be able to communicate with Okta's authentication servers over HTTPS.

Step 1: Configure Okta

First, set up an OIDC application in your Okta admin dashboard.

Create the OIDC Application:

Go to Applications > Applications in your Okta admin console and click "Create App Integration." Choose "OIDC - OpenID Connect" as the sign-in method and "Web Application" as the application type.

Set up your application with these key settings:

• Application Name: Something descriptive like "Strapi CMS"
• Sign-in redirect URIs: Your Strapi admin callback URL (typically https://your-strapi-domain.com/admin/connect/okta/callback)
• Sign-out redirect URIs: Your Strapi logout URL
• Controlled access: Select which users or groups can access this application

Configure Scopes and Claims:

In the application's configuration, enable these scopes:

• openid (required for OIDC)
• profile (for user profile information)
• email (for email addresses)
• groups (if using group-based role mapping)

For better role mapping, set up custom claims by going to Security > API > Authorization Servers. Create custom claims that include role or group information to pass during authentication.

Obtain Configuration Details:

Note these important values from your Okta application:

• Client ID
• Client Secret
• Issuer URL (typically https://your-okta-domain.okta.com)
• Authorization endpoint
• Token endpoint

Step 2: Configure Strapi

With Okta ready, set up the Strapi side.

Install Required Dependencies:

Ensure your Strapi project has the necessary authentication packages. The core SSO functionality comes with Strapi Enterprise Edition, but you might need extra packages for enhanced OIDC support.

Configure the SSO Provider:

Find your Strapi project's /config/admin.js (or admin.ts for TypeScript) file. Add the Okta provider to the auth.providers array.

For JavaScript:

module.exports = ({ env }) => ({
  auth: {
    secret: env('ADMIN_JWT_SECRET'),
    providers: [
      {
        uid: 'okta',
        displayName: 'Okta',
        icon: 'https://cdn.okta.com/logos/okta-logo.svg',
        createStrategy: strapi => require('@strapi/provider-audit-logs-local'),
        config: {
          clientID: env('OKTA_CLIENT_ID'),
          clientSecret: env('OKTA_CLIENT_SECRET'),
          subdomain: env('OKTA_SUBDOMAIN'),
          audience: env('OKTA_AUDIENCE'),
          scope: ['openid', 'profile', 'email', 'groups'],
          callback: '/admin/connect/okta/callback',
          grantType: 'authorization_code',
        },
      },
    ],
  },
});

For TypeScript:

export default ({ env }) => ({
  auth: {
    secret: env('ADMIN_JWT_SECRET'),
    providers: [
      {
        uid: 'okta',
        displayName: 'Okta',
        icon: 'https://cdn.okta.com/logos/okta-logo.svg',
        createStrategy: (strapi: any) => require('@strapi/provider-audit-logs-local'),
        config: {
          clientID: env('OKTA_CLIENT_ID'),
          clientSecret: env('OKTA_CLIENT_SECRET'),
          subdomain: env('OKTA_SUBDOMAIN'),
          audience: env('OKTA_AUDIENCE'),
          scope: ['openid', 'profile', 'email', 'groups'],
          callback: '/admin/connect/okta/callback',
          grantType: 'authorization_code',
        },
      },
    ],
  },
});

Environment Variable Configuration:

Create or update your .env file with the Okta values:

OKTA_CLIENT_ID=your_client_id_here
OKTA_CLIENT_SECRET=your_client_secret_here
OKTA_SUBDOMAIN=your-okta-domain
OKTA_AUDIENCE=api://default
ADMIN_JWT_SECRET=your_admin_jwt_secret

Step 3: Set Up Role Mapping

Effective role mapping, such as when you implement RBAC in Strapi, ensures users receive appropriate permissions based on their Okta groups or claims.

Configure Okta Groups:

In your Okta admin dashboard, go to Directory > Groups and create groups that match your Strapi roles:

• strapi-super-admin for full admin access
• strapi-editor for content management
• strapi-author for content creation

Assign users to these groups based on the access they need in Strapi.

Implement Role Mapping Logic:

Set up custom claims to pass group information during authentication. In Strapi, add logic to process these claims and assign roles.

Create a custom service for role mapping:

// api/auth/services/role-mapper.js
module.exports = {
  mapOktaRolesToStrapi(oktaGroups) {
    const roleMapping = {
      'strapi-super-admin': 'Super Admin',
      'strapi-editor': 'Editor',
      'strapi-author': 'Author',
    };
    
    return oktaGroups
      .map(group => roleMapping[group])
      .filter(Boolean);
  },
};

Step 4: Test and Validate

Thorough testing ensures everything works across different scenarios.

Initial Authentication Test:

Restart your Strapi application to apply the changes. Go to your Strapi admin login page and check that the Okta SSO option appears. Click it and complete the login flow.

User Role Verification:

After logging in, verify that users get the correct roles based on their Okta group memberships. Test different user accounts with various group assignments.

Session Management Testing:

Test session behaviors including login persistence across browser sessions, logout from both Strapi and Okta, and token refresh for long sessions.

Performance and Security Testing:

Monitor authentication performance, especially token validation and role assignment time. Consider caching frequently accessed user data to improve performance.

Ensure all communications use HTTPS and tokens are properly validated. Test edge cases like expired tokens, invalid signatures, and network issues during authentication.

Project Example: Configure Role-Based Permissions with Strapi and Okta

See how a digital media company solved access control challenges by integrating Okta with Strapi for role-based permissions.

Business Context:

MediaPulse, a growing digital publishing company, needed to manage 50+ content creators across different departments with varying access requirements:

• Senior editors required full content management capabilities
• Department editors needed access to specific content categories
• Freelance writers needed limited publishing privileges
• Admin staff required system access without content modification rights

The company faced challenges with their previous manual permission system, including security inconsistencies, onboarding delays, and access management overhead.

Project Structure:

my-strapi-okta/
├── config/
│   ├── admin.js
│   └── plugins.js
├── src/
│   └── plugins/
│       └── okta-auth/
└── package.json

Complete Configuration Example:

The config/admin.js file handles the core SSO configuration:

module.exports = ({ env }) => ({
  auth: {
    providers: [
      {
        name: 'okta',
        type: 'saml',
        enabled: true,
        config: {
          entryPoint: env('OKTA_SSO_URL'),
          issuer: env('OKTA_ENTITY_ID'),
          cert: env('OKTA_X509_CERTIFICATE'),
          attributeMapping: {
            email: 'email',
            username: 'username',
            role: 'department'
          }
        }
      }
    ],
  },
});

Role Mapping Implementation:

Custom role mapping logic processes Okta groups to assign appropriate Strapi permissions:

const processOktaRoles = (oktaGroups) => {
  const roleMapping = {
    'content-admin': 'Super Admin',
    'content-editor': 'Editor',
    'content-author': 'Author'
  };
  
  return oktaGroups.map(group => roleMapping[group]).filter(Boolean)[0] || 'Author';
};

In MediaPulse's implementation, they extended this basic mapping to accommodate their complex organizational structure:

const departmentContentMapping = {
  'news': ['breaking_news', 'politics', 'world_events'],
  'lifestyle': ['health', 'travel', 'food'],
  'entertainment': ['movies', 'music', 'celebrity']
};

// Apply department-specific content permissions
const applyDepartmentRestrictions = (user, oktaGroups) => {
  const department = oktaGroups.find(g => Object.keys(departmentContentMapping).includes(g));
  if (department) {
    user.allowedContentTypes = departmentContentMapping[department];
  }
  return user;
};

Implementation Results:

After implementing the Okta-Strapi integration, MediaPulse experienced:

• 85% reduction in time spent on access management
• Elimination of unauthorized content modifications
• Streamlined onboarding process (from 2 days to 10 minutes)
• Improved content workflow with proper role enforcement
• Enhanced security compliance for sensitive content

Strapi Open Office Hours

If you have any questions about Strapi 5 or just would like to stop by and say hi, you can join us at Strapi's Discord Open Office Hours Monday through Friday at 12:30 pm – 1:30 pm CST.

For more details, visit the Strapi documentation and Okta.