Skip to main content

Keycloak - Admin SSO Provider

☑️ Prerequisites
  • Properly configure Strapi for SSO
  • Create your REPLACEME OAuth2 app by following the steps in the TODO.
  • Gather the required information to set as environment variables in your Strapi project:
    • // TODO

Required configuration before setting up SSO​

Server Configuration​

The following server configurations are required when using SSO, for more information on available options please see the Server Configuration documentation.

  • url: The public facing URL of your Strapi application. (e.g. https://api.example.com)
  • proxy.koa: Enabling trusted reverse proxy support. (true)
Admin Required Configuration Example
./config/server.js

module.exports = ({ env }) => ({
  // ...
  url: env('PUBLIC_URL', 'https://api.example.com'),
  proxy: {
    koa: env.bool('TRUST_PROXY', true),
  },
  // ...
});

There are also some optional configurations that you can set should it be necessary:

  • proxy.global: If you are in a restricted network environment that requires a forward proxy (e.g Squid) for all outgoing requests. (e.g. http://username:password@yourProxy:3128)
Admin Optional Configuration Example
./config/server.js

module.exports = ({ env }) => ({
  // ...
  url: env('PUBLIC_URL', 'https://api.example.com'),
  proxy: {
    koa: env.bool('TRUST_PROXY', true),
    global: env('GLOBAL_PROXY'),
  },
  // ...
});

Admin Configuration​

There are some optional configurations that you can set should it be necessary, for more information on available options please see the Admin Configuration documentation.

  • url: The public facing URL of your Strapi administration panel. (e.g. https://admin.example.com)
  • auth.domain: Setting a custom domain for cookie storage. (e.g. .example.com)
✏️ Note

When deploying the admin panel to a different location or on a different subdomain, an additional configuration is required to set the common domain for the cookies. This is required to ensure the cookies are shared across the domains.

✋ Caution

Deploying the admin and backend on entirely different unrelated domains is not possible at this time when using SSO due to restrictions in cross-domain cookies.

Admin Optional Configuration Example
./config/admin.js

module.exports = ({ env }) => ({
  // ...
  url: env('PUBLIC_ADMIN_URL', 'https://admin.example.com'),
  auth: {
    domain: env("ADMIN_SSO_DOMAIN", ".example.com"),
    providers: [
      // ...
    ],
  },
  // ...
});

Middlewares Configuration​

The following middleware configurations are required when using SSO, for more information on available options please see the Middlewares Configuration documentation.

  • contentSecurityPolicy: Allows you to configure the Content Security Policy (CSP) for your Strapi application. This is used to prevent cross-site scripting attacks by allowing you to control what resources can be loaded by your application.
✏️ Note

By default, Strapi security policy does not allow loading images from external URLs, so provider logos will not show up on the login screen of the admin panel unless a security exception is added or you use a file uploaded directly on your Strapi application.

Middlewares Configuration Example
./config/middlewares.js
module.exports = [
  // ...
  {
    name: 'strapi::security',
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          'connect-src': ["'self'", 'https:'],
          'img-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'cdn2.iconfinder.com', // Base URL of the provider's logo without the protocol
          ],
          'media-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'cdn2.iconfinder.com', // Base URL of the provider's logo without the protocol
          ],
          upgradeInsecureRequests: null,
        },
      },
    },
  },
  // ...
]

Provider Specific Notes​

Scopes​

The TODO OAuth2 provider requires the following scopes, however additional scopes can be added as needed depending on your use case and the data you need returned:

  • TODO

Profile Data​

Data returned from the provider is dependent on how your TODO OAuth2 application is configured. The example below assumes that the TODO OAuth2 application is configured to return the user's email, first name, and last name. Fields returned by the provider can change based on the scopes requested and the user's TODO account settings.

If you aren't sure what data is being returned by the provider, you can log the profile object in the createStrategy function to see what data is available as seen in the following example.

Configuration Example with Logging
// TODO

Redirect URL/URI​

The redirect URL/URI will be dependent on your provider configuration however in most cases should combine your application's public URL and the provider's callback URL. The example below shows how to combine the public URL with the provider's callback URL.

callbackURL:
  env('PUBLIC_URL', "https://api.example.com") +
  strapi.admin.services.passport.getStrategyCallbackURL("TODO"),

In this example the redirect URL/URI used by the provider will be https://api.example.com/admin/connect/TODO.

This is broken down as follows:

  • https://api.example.com is the public URL of your Strapi application
  • /admin/connect is the general path for SSO callbacks in Strapi
  • /TODO is the specific provider UID for TODO

Strapi Configuration​

Using: // TODO

Install the Provider Package​

// TODO

Adding the Provider to Strapi​

./config/admin.js

// TODO