Warrant

Makes working with AWS Cognito easier for Python developers.

Getting Started

• Cognito Utility Class warrant.Cognito
• Cognito SRP Utility warrant.aws_srp.AWSSRP
  • Using AWSSRP
• Django Utilities
  • Auth Backend warrant.django.backend.CognitoBackend
    • Using the CognitoBackend
    • CognitoBackend Behavior
    • Customizing CognitoBackend Behavior
  • Profile Views
  • API Gateway Integration
    • API Key Middleware warrant.django.middleware.APIKeyMiddleware

Create a Cognito Instance

Example with All Arguments

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id',
        username='optional-username',
        id_token='optional-id-token',
        refresh_token='optional-refresh-token',
        access_token='optional-access-token',
        access_key='optional-access-key',
        secret_key='optional-secret-key'
        )

Arguments

• user_pool_id: Cognito User Pool ID
• client_id: Cognito User Pool Application client ID
• username: User Pool username
• id_token: ID Token returned by authentication
• refresh_token: Refresh Token returned by authentication
• access_token: Access Token returned by authentication
• access_key: AWS IAM access key
• secret_key: AWS IAM secret key

Examples with Realistic Arguments

User Pool Id and Client ID Only

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id')

Username####

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id',
        username='bob',
        )

Tokens

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id',
    id_token='your-id-token',
    refresh_token='your-refresh-token',
    access_token='your-access-token'
)

Cognito Methods

Register

Register a user to the user pool

Important: The keyword arguments used for this method depend on your user pool's configuration, and make sure the client id (app id) used has write permissions for the attriubtes you are trying to create. Example, if you want to create a user with a given_name equal to Johnson make sure the client_id you're using has permissions to edit or create given_name for a user in the pool.

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id')

u.register('username','password',email='[email protected]',some_random_attr='random value') #**kwargs are the other attributes that should be set ex. email, given_name, family_name

Authenticate

Authenticates a user

If this method call succeeds the instance will have the following attributes id_token, refresh_token, access_token, expires_in, expires_datetime, and token_type.

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id',
    username='bob',password='bobs-password')

u.authenticate()

Change Password

Changes the user's password

from warrant import Cognito

#If you don't use your tokens then you will need to
#use your username and password and call the authenticate method
u = Cognito('your-user-pool-id','your-client-id',
    id_token='id-token',refresh_token='refresh-token',
    access_token='access-token')

u.change_password('previous-password','proposed-password')

Confirm Sign Up

Use the confirmation code that is sent via email or text to confirm the user's account

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id')

u.confirm_sign_up('users-conf-code',username='bob')

Update Profile

Update the user's profile

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id',
    id_token='id-token',refresh_token='refresh-token',
    access_token='access-token')

u.update_profile({'given_name':'Edward','family_name':'Smith',})

Send Verification

Send verification email or text for either the email or phone attributes.

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id',
    id_token='id-token',refresh_token='refresh-token',
    access_token='access-token')

u.send_verification(attribute='email')

Get User

Get all of the user's attributes

Important: Returns a UserObj project

from warrant import Cognito

u = Cognito('your-user-pool-id','your-client-id',
    username='bob')

user = u.get_user()

Logout

Logs the user out of all clients. Erases the access token.

from warrant import Cognito

#If you don't use your tokens then you will need to
#use your username and password and call the authenticate method
u = Cognito('your-user-pool-id','your-client-id',
    id_token='id-token',refresh_token='refresh-token',
    access_token='access-token')

u.logout()

Cognito SRP Utility

The AWSSRP class is used to perform SRP(Secure Remote Password protocol) authentication.
This is the preferred method of user authentication with AWS Cognito.
The process involves a series of authentication challenges and responses, which if successful,
results in a final response that contains ID, access and refresh tokens.

Using AWSSRP

The AWSSRP class takes a username, password, cognito user pool id, cognito app id, and an optional
boto3 client. Afterwards, the authenticate_user class method is used for SRP authentication.

import boto3
from warrant.aws_srp import AWSSRP

client = boto3('cognito-idp')
aws = AWSSRP(username='username', password='password', pool_id='user_pool_id',
             client_id='client_id', client=client)
tokens = aws.authenticate_user()

Django Utilities

Django Auth Backend

Using the CognitoBackend

1. In your Django project settings file, add the dotted path of CognitoBackend to your list of AUTHENTICATION_BACKENDS. Keep in mind that Django will attempt to authenticate a user using each backend listed, in the order listed until successful.

   AUTHENTICATION_BACKENDS = [
       'warrant.django.backend.CognitoBackend',
       ...
   ]

2. Set COGNITO_USER_POOL_ID and COGNITO_APP_ID in your settings file as well. Your User Pool ID can be found in the Pool Details tab in the AWS console. Your App ID is found in the Apps tab, listed as "App client id".

3. Set COGNITO_ATTR_MAPPING in your settings file to a dictionary mapping a Cognito attribute name to a Django User attribute name.
   If your Cognito User Pool has any custom attributes, it is automatically
   prefixed with custom:. Therefore, you will want to add a mapping to your
   mapping dictionary as such {'custom:custom_attr': 'custom_attr'}.
   Defaults to:

   {
       'email': 'email',
       'given_name': 'first_name',
       'family_name': 'last_name',
   }

4. Optional - Set CREATE_UNKNOWN_USERS to True or False, depending on if
   you wish local Django users to be created upon successful login. If set to False,
   only existing local Django users are updated.
   Defaults to True.

CognitoBackend Behavior

Since the username of a Cognito User can never change, this is used by the backend to match a Cognito User with a local Django User.

If a Django user is not found, one is created using the attributes fetched from Cognito. If an existing Django user is found, their attributes are updated.

If the boto3 client comes back with either a NotAuthorizedException or
UserNotFoundException, then None is returned instead of a User.
Otherwise, the exception is raised.

Upon successful login, the three identity tokens returned from Cognito (ID token, Refresh token, Access token) are stored in the user's request session. In Django >= 1.11, this is done directly in the backend class. Otherwise, this is done via the user_logged_in signal.

Check the django/demo directory for an example app with a login and user details page.

Customizing CognitoBackend Behavior

Setting the Django setting CREATE_UNKNOWN_USERS to False prevents the backend from creating a new local Django user and only updates existing users.

If you create your own backend class that inhereits from CognitoBackend, you may
want to also create your own custom user_logged_in so that it checks
for the name of your custom class.

API Gateway Integration

API Key Middleware

The APIKeyMiddleware checks for a HTTP_AUTHORIZATION_ID header
in the request and attaches it to the request object as api_key.