Auth

Auth is a lightweight AWS Cognito client for Kotlin Multiplatform projects

In its current state it provides only the bare minimum that was needed for our project. Feel free to contribute if there is something missing for you.

Import

Kotlin

sourceSets {
    val commonMain by getting {
        dependencies {
            implementation("com.liftric:auth:<version>")
        }
    }
}

Typescript

Yarn

yarn add @liftric/auth@<version>

npm

npm i @liftric/auth@<version>

How-to

Instantiating

The handler needs a configuration object consisting of the region code and the client ID.

val configuration = Configuration(region = Region.euCentral1,
                                  clientId = "CLIENT_ID") 

Kotlin

val authHandler = AuthHandler(configuration) 

Typescript

import {AuthHandlerJS} from '@liftric/auth';

const auth = new AuthHandlerJS('<regionString>', '<clientId>');

API

General usage of the request methods.

Kotlin

All methods are suspending and will return a Result<T> object which wraps the desired return object T and can contain an exception.

val response = signUp(username = "user", password = "password")
if (response.isSuccess) {
    println(signUpResponse.getOrNull())
} else {
    println(signUpResponse.exceptionOrNull())
}

Typescript

All methods return a Promise that returns the desired object T on success.

Sign Up

Signs up the user.

Attributes are optional.

val attribute = UserAttribute(Name = "email", Value = "name@url.tld")

signUp(username = "USERNAME", password = "PASSWORD",
       attributes = listOf(attribute)): Result<SignUpResponse>
...

Confirm Sign Up

Confirms the sign up (also the delivery medium).

confirmSignUp(username = "USERNAME", confirmationCode = "CODE_FROM_DELIVERY_MEDIUM"): Result<Unit>

Sign In

Signs in the users.

signIn(username = "USERNAME", password = "PASSWORD"): Result<SignInResponse>

Refresh access token

Refreshes access token based on refresh token that's retrieved from an earlier sign in.

val signInResponse: SignInResponse = ... // from earlier login or refresh
val refreshToken = signInResponse.AuthenticationResult.RefreshToken
refresh(refreshToken = refreshToken): Result<SignInResponse>

Get Claims

You can retrieve the claims of both the IdTokens' and AccessTokens' payload by converting them to either a CognitoIdToken or CognitoAccessToken

val idToken = CognitoIdToken(idTokenString)
// or
val accessToken = CognitoAccessToken(accessTokenString)

val phoneNumber = idToken.claims.phoneNumber
val sub = idToken.claims.sub

Custom attributes of the IdToken get mapped into customAttributes

val twitter = idToken.claims.customAttributes["custom:twitter"]

Get User

Returns the users attributes and metadata on success.

More info about this in the official documentation.

getUser(accessToken = "TOKEN_FROM_SIGN_IN_REQUEST"): Result<GetUserResponse>

Update User Attributes

Updates the users attributes (e.g. email, phone number, ...).

updateUserAttributes(accessToken = "TOKEN_FROM_SIGN_IN_REQUEST",
                     attributes = listOf(...)): Result<UpdateUserAttributesResponse>

Change Password

Updates the users password

changePassword(accessToken = "TOKEN_FROM_SIGN_IN_REQUEST",
               currentPassword = "OLD_PW",
               newPassword = "NEW_PW"): Result<Unit>

Forgot Password

Invokes password forgot and sends a confirmation code the the users' delivery medium.

More info about the ForgotPasswordResponse in the official documentation.

forgotPassword(username = "USERNAME"): Result<ForgotPasswordResponse>

Confirm Forgot Password

Confirms forgot password.

confirmForgotPassword(confirmationCode = "CODE_FROM_DELIVERY_MEDIUM", username = "USERNAME", 
                      password = "NEW_PASSWORD_FROM_DELIVERY_MEDIUM"): Result<Unit>

Get user Attribute Verification Code

Gets the user attribute verification code for the specified attribute name

getUserAttributeVerificationCode(accessToken = "TOKEN_FROM_SIGN_IN_REQUEST", attributeName = "EMAIL", clientMetadata = null): Result<GetAttributeVerificationCodeResponse>

Verify User Attribute

Verifies the specified user attribute.

verifyUserAttribute(accessToken = "TOKEN_FROM_SIGN_IN_REQUEST", attributeName = "EMAIL", code = "CODE_FROM_DELIVERY_MEDIUM"): Result<Unit>

Sign Out

Signs out the user globally.

signOut(accessToken = "TOKEN_FROM_SIGN_IN_REQUEST"): Result<SignOutResponse>

Revoke Token

Revokes all access tokens generated by the refresh token.

revokeToken(refreshToken = "TOKEN_FROM_SIGN_IN_REQUEST"): Result<Unit>

Delete User

Deletes the user from the user pool.

deleteUser(accessToken = "TOKEN_FROM_SIGN_IN_REQUEST"): Result<Unit>

Contributing

Auth is a simple kotlin project with one caveat: We're using a live Cogntio Userpool for integration tests and the values are provided using code generation at compile time.

The build needs both region and clientid configured, either using our hashicorp vault cluster (obviously not accessible from the outside), or via env var (github actions approach). region expects the AWS Region Code for the target region, like "us-east-1".

So if you only want to build the project, provide region and clientid env var with garbage values...

... and if you want to execute to tests yourself, you can use your own congito user pool client values.

License

Auth is available under the MIT license. See the LICENSE file for more info.