This feature is available since Webiny v5.37.6.
- how to configure federated identity providers in the Admin app
- what are the prerequisites necessary to enable federated providers
Out of the box, Webiny comes with an AWS Cognito setup to manage its admin users. There’s a preconfigured Cognito User Pool dedicated to admin users. This user pool doesn’t allow external users to sign-up, which means that new admin user accounts can only be created by a Webiny admin, from within the Admin app.
In this article, we show the process of configuring your Webiny project to use one or more public identity providers (Google, Facebook, Apple, Amazon).
OIDC providers are not supported at this point.
In this article, we’re using Google as the identity provider of choice. To set up a Google Cloud project and obtain the
client_secret, follow the official documentation. In particular, see the To register an app with Google section.
If your project was created before v5.37.6, and you used our AWS Cloudformation template to setup your deployment user, make sure you update the permissions using the template.
Cognito resources are part of the Core app, which is responsible for stateful resources (databases, user pools, S3 buckets, etc.). To configure Cognito to use federated identity providers, we need to modify the
webiny.application.ts file of the
core app. Webiny provides a utility to facilitate the configuration of infrastructure resources involved.
Once you have your
client_secret ready, you can store them in your project’s
.env file, like so:
You can add multiple identity providers to your Cognito user pool. Simply add more identity provider configs to the
Note that for development purposes, it’s enough to have just the
localhost defined in the
callbackUrls. This article assumes that you’ll be researching this feature in a development environment, on localhost.
However, once you deploy your Admin app, and want to use the real Cloudfront URL, or a custom domain, you’ll need to go back to this config, and update the
callbackUrls with the live URL. You’ll also need to redeploy your
core app for your config to apply.
Once the config of your identity provider is in place, you need to deploy your
core app, to apply the new infrastructure configuration:
Once deployed, you need to whitelist your Cognito domain in your Google OAuth 2.0 Client ID, as described in the official documentation (see points 13-14 in the To register an app with Google section).
To get the domain name, copy the value of
cognitoUserPoolDomain output from the following command:
Cognito will be handling the communication with the external identity providers, and creating the
idToken which is then sent to the API from the Admin app. This means that the authentication process remains the same as with regular Cognito users. However, external user profiles do not exist in the Admin app, and cannot be mapped to a security group or a team using their profile.
To help Webiny map your external users to specific user groups, we need to add the group information to the identity object , generated in the authentication process.
apps/api/graphql/src/security.ts file, and update the existing
In this basic example, we’re checking if the token contains the
identities claim, which is only present on tokens of identities coming from external IdPs. If so, we map those identities to a
full-access user group.
group is an identity attribute which Webiny uses to map the identity to the specified user group. This gives identities their permissions, which are then used in the authorization process. If this attribute is not set (or is
undefined), Webiny will attempt to load the user group using a user profile, which exist only for users created via the Admin app.
With this approach, we can manage group mapping programmatically, and decide where the mapping information is coming from. We might fetch the group slug from the
idToken claim (which can be managed outside Webiny, within Cognito, or within the external identity provider), or we can use a hardcoded map (as we do in this example, using the
full-access group slug).
Once the config is in place, you need to deploy your
We need to update the default Cognito configuration in the Admin app, to enable sign in via Google:
Notice the use of
localhost redirect URLs. In your staging and production environments, you’ll
need to update these values to reflect the domains of your deployed systems.
And lastly, we need to get the value of
REACT_APP_USER_POOL_DOMAIN environment variable in the code above. Its value is the fully qualified Cognito User Pool domain, which lives in the Core app. It looks something like this:
webiny-admin.auth.us-east-1.amazoncognito.com, and is generated once the User Pool Domain is created in your AWS infrastructure.
To pull this value from the Core app, and inject it into the Admin app, there’s a utility provided by Webiny. Update your
apps/admin/webiny.config.ts file like so:
To run and test the new identity provider, start your Admin app:
Once your app is up and running, you should see the following login screen: