Mashroom OpenID Connect Security Provider

Plugin for Mashroom Server, a Microfrontend Integration Platform.

This plugin adds an OpenID Connect/OAuth2 security provider that can be used to integrate Mashroom Server with almost all Identity Providers or Identity Platforms.

Tested with:

• Github OAuth 2.0
• Google Identity Platform
• Keylcoak Identity Provider
• Open AM

Should work with (among others):

• Auth0
• Facebook Login
• Gluu
• Microsoft Identity Platform
• Okta
• OneLogin
• PingIdentity

Usage

If node_modules/@mashroom is configured as plugin path just add @mashroom/mashroom-security-provider-ldap as dependency.

To activate this provider, configure the Mashroom Security plugin like this:

{
    "plugins": {
        "Mashroom Security Services": {
            "provider": "Mashroom OpenID Connect Security Provider"
        }
    }
}

And configure this plugin like this in the Mashroom config file:

{
    "plugins": {
        "Mashroom OpenID Connect Security Provider": {
            "mode": "OIDC",
            "issuerDiscoveryUrl": "http://localhost:8080/.well-known/openid-configuration",
            "issuerMetadata": null,
            "scope": "openid email profile",
            "clientId": "mashroom",
            "clientSecret": "your-client-secret",
            "redirectUrl": "http://localhost:5050/openid-connect-cb",
            "responseType": "code",
            "usePKCE": false,
            "extraAuthParams": {},
            "extraDataMapping": {
                "phone": "phone",
                "birthdate": "birthdate",
                "updatedAt": "updated_at"
            },
            "rolesClaimName": "roles",
            "adminRoles": [
                "mashroom-admin"
            ],
            "httpRequestTimeoutMs": 3500
        },
        "Mashroom OpenID Connect Security Provider Callback": {
           "path": "/openid-connect-cb"
        }
    }
}

• mode: Can be OIDC (default) or OAuth2. Pure OAuth2 usually does not support permission roles (for authorization).
• issuerDiscoveryUrl: The OpenID Connect Discovery URL, this is usually https://<your-idp-host>/.well-known/openid-configuration. See Example Configurations below.
• issuerMetadata: The issuer metadata if no issuerDiscoveryUrl is available. Will be passed to the Issuer constructor. See examples below.
• scope: The scope (permissions) to ask for (Default: openid email profile)
• clientId: The client to use (Default: mashroom)
• clientSecret: The client secret
• redirectUrl: The full URL of the callback (as seen from the user). This is usually https://<mashroom-server-host>/openid-connect-cb. The path corresponds with the path property in the Mashroom OpenID Connect Security Provider Callback config.
• responseType: The OpenID Connect response type (flow) to use (Default: code)
• usePKCE: Use the Proof Key for Code Exchange extension for the code flow (Default: false)
• extraAuthParams: Extra authentication parameters that should be used
• extraDataMapping: Optionally map extra claims to user.extraData. The key in the map is the extraData property, the value the claim name (Default: null)
• rolesClaimName: Defines the name of the claim (the property of the claims or userinfo object) that contains the user roles array (Default: roles)
• adminRoles: A list of user roles that should get the Mashroom Administrator role (Default: ["mashroom-admin"])
• httpRequestTimeoutMs: Request timeout when contacting the Authorization Server (Default: 3500)

Roles

Since the authorization mechanism relies on user roles it is necessary to configure your identity provider to map the user roles to a scope (which means we can get it as claim). See Example Configurations below.

Secrets

The plugin maps the ID/JWT Token to user.secrets.idToken so it can for example be used in a Http Proxy Interceptor to set the Bearer for backend calls.

Authentication Expiration

The implementation automatically extends the authentication via refresh token every view seconds (as long as the user is active). So, if the authentication session gets revoked in the identity provider the user is signed out almost immediately.

The expiration time of the access token defines after which time the user is automatically signed out due to inactivity. And the expiration time of the refresh token defines how long the user can work without signing in again.

Example Configurations

Keycloak

Setup:

• Create a new client in your realm (e.g. mashroom)
• In the Settings tab set Access Type confidential
• Make sure the Valid Redirect URIs contain your redirect URL (e.g. http://localhost:5050/*)
• In the Credentials tab you'll find the client secret
• To map the roles to a scope/claim goto Mappers, click Add Builtin and add a realm roles mapper. In the field Token Claim Name enter roles. Also check Add to ID token.
• You should create a role (e.g. mashroom-admin) for users with Administrator rights

You'll find more details about the configuration here: https://www.keycloak.org/documentation.html

If your Keycloak runs on localhost, the Realm name is test amd the client name mashroom, then the config would look like this:

{
    "plugins": {
        "Mashroom OpenID Connect Security Provider": {
            "issuerDiscoveryUrl": "http://localhost:8080/auth/realms/test/.well-known/uma2-configuration",
            "clientId": "mashroom",
            "clientSecret": "xxxxxxxxxxxxxxxx",
            "redirectUrl": "http://localhost:5050/openid-connect-cb",
            "rolesClaim": "roles",
            "adminRoles": [
                "mashroom-admin"
            ]
        }
    }
}

OpenAM

Setup:

• Create a new Realm (e.g. Test)
• Create a new OIDC configuration: OAuth provider -> Configure OpenID Connect -> Create from the Dashboard)
• Create a new Agent (e.g. mashroom): Applications -> OAuth 2.0 -> Agent from the Dashboard)
• Make sure the agent has at least the scopes openid email profile and the ID Token Signing Algorithm is set to RS256
• Follow this KB article to add the OpenAM groups as roles claim

You'll find more details about the configuration here: https://backstage.forgerock.com/docs/openam/13.5/admin-guide

If your OpenAM server runs on localhost, the Realm name is Test amd the client name mashroom, then the config would look like this:

{
    "plugins": {
        "Mashroom OpenID Connect Security Provider": {
            "issuerDiscoveryUrl": "http://localhost:8080/openam/oauth2/Test/.well-known/openid-configuration",
            "scope": "openid email profile",
            "clientId": "mashroom",
            "clientSecret": "mashroom",
            "redirectUrl": "http://localhost:5050/openid-connect-cb",
            "rolesClaim": "roles",
            "adminRoles": [
                "mashroom-admin"
            ]
        }
    }
}

Google Identity Platform

Setup:

• Go to: https://console.developers.google.com
• Select Credentials from the menu and then the auto created client under OAuth 2.0 Client IDs
• Make sure the Authorized redirect URIs contains your redirect URL (e.g. http://localhost:5050/openid-connect-cb)
• Create a OAuth consent screen

Possible config:

{
    "plugins": {
        "Mashroom OpenID Connect Security Provider": {
            "issuerDiscoveryUrl": "https://accounts.google.com/.well-known/openid-configuration",
            "scope": "openid email profile",
            "clientId": "xxxxxxxxxxxxxxxx.apps.googleusercontent.com",
            "clientSecret": "xxxxxxxxxxxxxxxx",
            "redirectUrl": "http://localhost:5050/openid-connect-cb",
            "extraAuthParams": {
                "access_type": "offline"
            },
            "usePKCE": true
        }
    }
}

The access_type=offline parameter is necessary to get a refresh token.

Since Google users don't have authorization roles there is no way to make some users Administrator.

GitHub OAuth2

Setup:

• Go to: https://github.com/settings/developers
• Click on "New OAuth App"
• Enter the application name and correct callback URL (e.g. http://localhost:5050/openid-connect-cb)

Possible config:

{
    "plugins": {
        "Mashroom OpenID Connect Security Provider": {
            "mode": "OAuth2",
            "issuerMetadata": {
                "issuer": "GitHub",
                "authorization_endpoint": "https://github.com/login/oauth/authorize",
                "token_endpoint": "https://github.com/login/oauth/access_token",
                "userinfo_endpoint": "https://api.github.com/user",
                "end_session_endpoint": null
            },
            "scope": "openid email profile",
            "clientId": "xxxxxxxxxxxxxxxx",
            "clientSecret": "xxxxxxxxxxxxxxxx",
            "redirectUrl": "http://localhost:5050/openid-connect-cb"
        }
    }
}

Since GitHub uses pure OAuth2 the users don't have permission roles and there is no way to make some users Administrator. It also supports no userinfo endpoint, so it actually makes not much sense to use it with Mashroom.