Admin Area > Extending Functionality
Cognito Federation
Learn how to configure Cognito Federation to sign into the Admin app.
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
Overview
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).
Custom OIDC providers are not supported at this point.
Using Google IdP to Sign Into the Admin AppPrerequisites
In this article, we’re using Google as the identity provider of choice. To set up a Google Cloud project and obtain the client_id and 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.
Configure AWS Infrastructure
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_id and 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 identityProviders array.
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:
Core App OutputConfigure GraphQL API
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.
Open your apps/api/graphql/src/security.ts file, and update the existing cognitoAuthentication configuration:
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 api app:
Configure Admin App
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:
Using Google IdP to Sign Into the Admin App