Lightweight AWS Cognito Identity Provider client, supporting various sign-up, sign-in, password management, and user attribute functions. Methods return results wrapped in `Result<T>` for error handling.
Lightweight AWS Cognito Identity Provider client for Kotlin Multiplatform and Typescript projects.
Not all requests, errors, and auth flows are implemented.
Feel free to contribute if there is something missing for you.
Version 2 introduced breaking changes, please refer to the migration document for help.
sourceSets {
val commonMain by getting {
dependencies {
implementation("com.liftric:cognito-idp:<version>")
}
}
}
yarn add @liftric/cognito-idp@<version>
npm i @liftric/cognito-idp@<version>
val provider = IdentityProviderClient("<region>", "<clientId>")
import {IdentityProviderClientJS} from '@liftric/cognito-idp';
const provider = new IdentityProviderClientJS('<region>', '<clientId>');
All methods are suspending and return a Result<T>, which wraps the desired object T on success or a Throwable on failure.
provider.signUp("user", "password").fold(
onSuccess = {
// Do something
},
onFailure = {
// Handle exceptions
}
)
All methods return a Promise object.
Request related exceptions are defined as a sealed class of type IdentityProviderException. They contain the http status code and the message. Common AWS exceptions are implemented as subclasses. In case that we don't have implemented the exception type it will default to IdentityProviderException.Unknown, which will contain the AWS exception type.
Network related exceptions (e.g. no internet) are of type IOException.
Signs up the user.
Attributes are optional.
val attribute = UserAttribute("email", "name@url.tld")
signUp("<username>", "<password>", listOf(attribute)): Result<SignUpResponse>
Confirms the sign up (also the delivery medium).
confirmSignUp("<username>", "<confirmationCode>"): Result<Unit>
Resends the confirmation code.
resendConfirmationCode("<username>"): Result<CodeDeliveryDetails>
Signs in the users.
signIn("<username>", "<password>"): Result<SignInResponse>
Responds to the auth challenge of the sign in response.
val challengeResponses = mapOf<String, String>()
respondToAuthChallenge("<challengeName>", challengeResponses, "<session>"): Result<SignInResponse>
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): Result<SignInResponse>
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)
val phoneNumber = idToken.claims.phoneNumber
val sub = idToken.claims.sub
Custom attributes of the IdToken get mapped into customAttributes.
You have to drop the custom: prefix.
val twitter = idToken.claims.customAttributes["twitter"]
Returns the users attributes and metadata on success.
More info about this in the official documentation.
getUser("<accessToken>"): Result<GetUserResponse>
Updates the users attributes (e.g. email, phone number, ...).
val attributes: List<UserAttribute> = ...
updateUserAttributes("<accessToken>", attributes): Result<UpdateUserAttributesResponse>
Updates the users password
changePassword("<accessToken>", "<currentPassword>", "<newPassword>"): Result<Unit>
Invokes password forgot and sends a confirmation code the the users' delivery medium.
More info about the ForgotPasswordResponse in the official documentation.
forgotPassword("<username>"): Result<ForgotPasswordResponse>
Confirms forgot password.
confirmForgotPassword("<confirmationCode>", "<username>", "<newPassword>"): Result<Unit>
Gets the user attribute verification code for the specified attribute name
getUserAttributeVerificationCode("<accessToken>", "<attributeName>", "<clientMetadata>"): Result<GetAttributeVerificationCodeResponse>
Verifies the specified user attribute.
verifyUserAttribute("<accessToken>", "<attributeName>", "<confirmationCode>"): Result<Unit>
Signs out the user globally.
signOut("<accessToken>"): Result<SignOutResponse>
Revokes all access tokens generated by the refresh token.
revokeToken("<refreshToken>"): Result<Unit>
Associate software token. Either with access token or session (not both).
associateSoftwareToken("<accessToken>", "<session"): Result<AssociateSoftwareTokenResponse>
Verifies software token. Either with access token or session (not both).
verifySoftwareToken("<accessToken>", "<friendlyDeviceName>", "<session", "<userCode>"): Result<VerifySoftwareTokenResponse>
Set MFA preferences.
val smsMfaSettings = null
val softwareTokenMfaSettings = MfaSettings(true, true)
setUserMFAPreference("<accessToken>", smsMfaSettings, softwareTokenMfaSettings): Result<Unit>
Deletes the user from the user pool.
deleteUser("<accessToken>"): Result<Unit>
Cognito-idp is available under the MIT license. See the LICENSE file for more info.
Surfaced from shared tags and platforms — no rankings paid for.