README

Craft Cognito Auth plugin

Enable authentication to Craft using AWS Cognito.

Overview

This plugin enables requests to Craft to be securely authenticated in the presence of a Cognito JWT that can be successfully verified as matching a JWKS signature.

JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.

-- jwt.io

Features

Create and verify users with Cognito.
Authenticate requests to Craft from mobile apps and websites via JWT.
SAML Authentication.

Requirements

This plugin requires Craft CMS 4.0 or later.

Installation

Follow the Craft CMS documentation to set up your local Craft instance.
Load the plugin with Composer:

nitro composer require unionco/craft-cognito-auth
On your browser, open your local Craft Control Panel, navigate to Settings → Plugins, and click the "Install" button for Craft Cognito Auth.

Configuration

Navigate to the settings page of the plugin and enter required settings to activate the plugin:

This plugin asumes AWS Cognito is configured so that users sign up and sign in with email instead of username and that the App client being used has the sign-in API for server-based authentication (ADMIN_NO_SRP_AUTH) enabled as stated in the AWS docs

Usage

The plugin will attempt to verify any incoming requests with a JWT present in the Authentication header with a Bearer prefix, or with the simpler X-Access-Token header value. An example:

# With Authorization: Bearer
curl --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o" MYCRAFTSITE.com

# With X-Access-Token
curl --header "X-Access-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o" MYCRAFTSITE.com

The plugin will attempt to verify the token using the lcobucci/jwt package for PHP. The package adheres to the IANA specifications for JWTs.

If a provided token can be verified AND can be matched to a user account with a username matching the provided sub key, the user will be authenticated and the request allowed to continue.

If the token is verifiable but a matching user account does NOT exist, but the Auto create user setting is enabled AND public registration is enabled in the Craft settings, a new user account will be created on-the-fly and the new user then logged in.

This plugin provides example templates for you to use as a reference when building out your authentication solution. The example templates can by found in the templates folder.

Deployment

Update version number in composer.json.
Add a new entry in CHANGELOG.md documenting the changes made.
Push a new tag matching the new version number with the following format: vX.Y.Z.

Contributing

Contributions are most welcome! Feel free to open a new issue or pull request to make this project better.

Credits

A big thank you to:

craft-jwt-auth - Copyright (c) 2019 Mike Pierce MIT License for the initial codebase.
@goraxan for the ongoing development.

License

This repo is covered under the MIT License.

Union Resources

Adding client secret setting: https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html#API_AdminInitiateAuth_RequestParameters Also not previously documented - in order to authenticate against any AWS service, you must configure the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY with an appropriate programmatic-access IAM user (in this case, the user must have Cognito access).

unionco / craft-cognito-auth

Maintainers

Details