Craft Cognito Auth
Craft Cognito Auth Overview
From the official JWT website:
JSON Web Tokens are an open, industry standard RFC 7519 method for representing claims securely between two parties.
This plugin enables logging into Craft using an Amazon Cognito User Pool. Uses Cognito JWT "Implicit Grant" (type=token
) requests.
Configuring Craft Cognito Auth
Once installed, navigate to the settings page of the plugin and enter required settings to activate the plugin:
Setting | Description |
---|---|
Auto create users | Optional. Activate to enable auto-creation of a public user when provided a verifiable JWT. |
Auto create users when Public Registration is disabled | Optional. Activate to enable auto-creation of a user even when Public Registration is disabled. |
Default user group | Optional. Set to a group to add newly-created users to. |
Enable CP login button | Optional. Enable to add a button to the CP login screen to login using Cognito. |
Customize login button text | Optional. Used to override the default text on the Login with Cognito button. |
Customize login button URL | Optional. Used to override the generated URL to the Hosted UI used for the login button. |
Redirect URL | Optional. Used to redirect the user after they have logged in, default is the current site's base url. |
AWS Settings | |
User Pool Region | Required. The AWS Region where the User Pool is hosted. |
App Domain | Optional. Used to generate the login link for the Login with Cognito button. |
App Client ID | Required. Used to generate the login link, and to verify the JWT was created for the correct pool. |
User Pool ID | Required. Used to get the key Cognito used to sign the JWT. |
The Cognito User Pool also needs to be configured to allow the callback URL to your site.
This is generated by the plugin and is shown as the last "setting" in the plugin's setting page.
The callback URL is "Control Panel URL (usually /admin
)"/cognitologin
.
To configure the User Pool:
- Go to AWS Cognito (
<region>.console.aws.amazon.com/cognito/users
) and select your user pool - Go to App integration / App client settings
- Add the callback URL to
Callback URL(s)
underSign in and sign out URLs
- While you're there, make sure
Implicit grant
is enabled underOAuth 2.0
|Allowed OAuth Flows
- Click Save changes at the bottom.
Using Craft Cognito Auth
The plugin will attempt to verify incoming requests to the control panel URL (usually /admin
) /cognitologin
with a JWT present in the parameters.
The plugin will get the Json Web Token Set (JWKS) from Cognito, and use it to 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 an email address matching the provided email
key
or a username matching the provided cognito:username
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 - OR the
Auto create user
setting is enabled, public registration is disabled, but theAuto create users when Public Registration is disabled
setting is enabled
in the Craft settings, a new user account will be created on-the-fly and the new user then logged in.
Package Name
To install this plugin, search for its package name on the Plugin Store and click “Install”.