Home Manual Reference Source Test Repository

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:

  1. no-verification - the state transitions directly to LOGGING_IN
  2. fetch-attributes - attributes are fetched then transitions to LOGGING_IN
  3. 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

  1. Go to your user pool and go to "Users and groups"
  2. Click "create user"
  3. 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

  1. Go to your deployed example application webserver
  2. You should see the login form
  3. Enter the username and password created above
  4. You should be asked for a new password, since this is your first login
  5. Enter a new password. It must conform to the rules of the user pool.
  6. You should then be taken to a verification code entry screen. check your email and enter the code.
  7. 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

  1. Click 'log out'
  2. You should see the login form
  3. Login again using your username and the new password you chose above.
  4. You should be taken to the logged in screen

Password changing

  1. Click 'Change password'
  2. Enter your existing password and a new password
  3. Click set new password
  4. you should see a message saying your password has been changed
  5. Click 'Home'

Change email address

  1. Click 'Change email address'
  2. You should see a form with your existing email address
  3. Enter a new valid email address
  4. You should be asked for a verification code. Check your email for the code.
  5. Enter the code.
  6. 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

  1. Log out
  2. Click 'Password Reset'
  3. Enter your username
  4. Click 'send verification code'
  5. It should say 'verification code sent'
  6. Check your email and get the code
  7. enter the code and your new password
  8. Click 'set new password'
  9. It should say 'Password reset'
  10. Click 'Home'
  11. 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

authenticate(username: string, password: string, userPool: object): Promise<object>

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

cognito(state: object, action: object): *

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

direct(state: object, dispatch: function)

transitions directly from AUTHENTICATED to LOGGING_IN

public

sends the email verification code and transitions to the correct state

public

requires email verification before transitioning from AUTHENTICATED

public

enable(store: object, f: function)

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

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

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

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