The Redux Model
The Redux Model
State Machine
Users start in state LOGGED_OUT
.
When they enter a username and password we call authenticateUser
on the CognitoUser
object and transition to a new state if the credentials worked:
MFA_REQUIRED
NEW_PASSWORD_REQUIRED
CONFIRMATION_REQUIRED
AUTHENTICATED
If in AUTHENTICATED
then a transition happens using a store subscriber. There are
three options:
- no-verification - the state transitions directly to LOGGING_IN
- fetch-attributes - attributes are fetched then transitions to LOGGING_IN
- verify-email - the attributes are fetched and email_verified checked, then transitions to LOGGING_IN or EMAIL_VERIFICATION_REQUIRED.
From LOGGING_IN default behaviour is to get a session (using CognitoUser.getSession
) from which we can get an auth token, then establishing a session with a Federated Identity Pool.
If all of that succeeds we transition to 'LOGGED_IN'.
react-cognito
react-cognito
If you are writing an application using react-cognito, then just install it using npm:
npm install react-cognito --save-dev
You will also need some dependencies:
npm install react react-dom react-redux redux amazon-cognito-identity-js --save-dev
For developers
If you want to hack on react-cognito itself:
Install the prerequisites:
sudo apt install npm
Check out the code somewhere:
git clone [email protected]:isotoma/react-cognito.git
Change into that directory, and then run the npm installer:
npm install
Configuration
Configuration
when you call the setup function, or dispatch a configuration action yourself, provide a configuration object like:
{
region: 'eu-west-1',
userPool: 'eu-west-1_xxxxxxxxx',
identityPool: 'eu-west-1:xxxxxx-xxxx-xxxx-xxxxxxxxxx',
clientId: 'xxxxxxxxxxxxxxxxxxxxxx',
}
You can find these magic strings as follows:
userPool
tbc
identityPool
tbc
clientId
tbc
Usage
Usage
Running the example
The package local-web-server
is included as a development dependency, so if
you have installed the development packages you should have the ws
command in
node_modules/.bin
.
First build the library, and then the examples, then change into the htdocs directory and run the webserver:
webpack -d
webpack -d --config webpack.examples.js
cd examples/htdocs
ws -s index.html
The -s
means all requests are sent to the single page application.
Trying it out
Set up your user and identity pools
TBC
Try it out
Create a test user
- Go to your user pool and go to "Users and groups"
- Click "create user"
- Complete the form:
- Enter a username
- Enter a password that conforms to the rules of the user pool
- Uncheck 'Mark phone number as verified?'
- Uncheck 'Mark email as verified?'
- Enter a valid email address
- Click 'Create User'
First time login
- Go to your deployed example application webserver
- You should see the login form
- Enter the username and password created above
- You should be asked for a new password, since this is your first login
- Enter a new password. It must conform to the rules of the user pool.
- You should then be taken to a verification code entry screen. check your email and enter the code.
- You should now see the logged in screen, showing your attributes and giving you some options.
Note that during this flow quitting and reloading the browser, then navigating back to this page, will result in you returning to the correct step.
Logout and Login
- Click 'log out'
- You should see the login form
- Login again using your username and the new password you chose above.
- You should be taken to the logged in screen
Password changing
- Click 'Change password'
- Enter your existing password and a new password
- Click set new password
- you should see a message saying your password has been changed
- Click 'Home'
Change email address
- Click 'Change email address'
- You should see a form with your existing email address
- Enter a new valid email address
- You should be asked for a verification code. Check your email for the code.
- Enter the code.
- You will be taken to the logged in screen.
Note that you can also reload the page after step 4, or close your browser, and you will be required to enter the verification code.
Password recovery
- Log out
- Click 'Password Reset'
- Enter your username
- Click 'send verification code'
- It should say 'verification code sent'
- Check your email and get the code
- enter the code and your new password
- Click 'set new password'
- It should say 'Password reset'
- Click 'Home'
- Log in with your new password
References
References
Class Summary
Static Public Class Summary | ||
public |
Container for logout behaviour. |
Function Summary
Static Public Function Summary | ||
public |
Authenticates with a user pool, and handles responses. |
|
public |
buildLogins(username: string, jwtToken: string, config: object): * builds the federated identity pool login structure |
|
public |
changePassword(user: object, oldPassword: string, newPassword: string) Change a user's password |
|
public |
reducer function to be passed to redux combineReducers |
|
public |
createGuard(store: object, forbiddenUrl: string): function creates a guard function you can use in <Route> tags |
|
public |
transitions directly from AUTHENTICATED to LOGGING_IN |
|
public |
emailVerificationFlow(user: object, attributes: object): Promise<object> sends the email verification code and transitions to the correct state |
|
public |
emailVerificationRequired(state: object, dispatch: function) requires email verification before transitioning from AUTHENTICATED |
|
public |
subscribes a "policy" function to the store, and calls it with the state and the dispatch function |
|
public |
fetchAttributes(state: object, dispatch: function) fetches and stores attributes before transitioning from AUTHENTICATED |
|
public |
getUserAttributes(user: object): Promise Fetches the user attributes from Cognito, and turns them into an object |
|
public |
identityPoolLogin(state: object, dispatch: function) logs into the single federated identity pool to transition from LOGGING_IN to LOGGED_IN |
|
public |
mkAttrList(attributes: object): array convert an attribute dictionary to an attribute list |
|
public |
performLogin(user: object, config: object): Promise<object> establishes a session with the user pool, and logs into the federated identity pool using a token from the session |
|
public |
registerUser(userPool: object, config: object, username: string, password: string, attributes: object): Promise<object> sign up this user with the user pool provided |
|
public |
sendAttributeVerificationCode(user: object, attribute: string) Request that a verification code is sent by email or SMS to verify an attribute |
|
public |
setupCognito(store: *, config: *) sets up react-cognito with default policies. |
|
public |
updateAttributes(user: object, attributes: object): Promise<object> update the attributes in Cognito |
Variable Summary
Static Public Variable Summary | ||
public |
Action: {"configure": *, "authenticated": *, "loggingIn": *, "login": *, "logout": *, "loginFailure": *, "mfaRequired": *, "newPasswordRequired": *, "newPasswordRequiredFailure": *, "emailVerificationRequired": *, "emailVerificationFailed": *, "beginPasswordResetFlow": *, "finishPasswordResetFlow": *, "updateAttributes": *, "confirmationRequired": *} container for all the actions |
|
public |
CognitoState: {"LOGGED_OUT": string, "AUTHENTICATED": string, "LOGGING_IN": string, "LOGGED_IN": string, "NEW_PASSWORD_REQUIRED": string, "MFA_REQUIRED": string, "EMAIL_VERIFICATION_REQUIRED": string, "CONFIRMATION_REQUIRED": string} states stored in store.cognito.state |
|
public |
Confirm: * Container for a confirmation form. |
|
public |
Wrapper for an Email Verification Form. |
|
public |
Login: * Container for login behaviour, wrapping a login form. |
|
public |
Wrapper for a New Password Required form |
|
public |
Container for a Password Reset form |