Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Liftric/cognito-idp
Lightweight AWS Cognito Identity Provider client for Kotlin Multiplatform and Typescript projects.
https://github.com/Liftric/cognito-idp
android auth aws aws-cognito cognito cognito-api cognito-idp hacktoberfest identity-provider ios kotlin kotlin-multiplatform kotlin-native liftric typescript
Last synced: 2 months ago
JSON representation
Lightweight AWS Cognito Identity Provider client for Kotlin Multiplatform and Typescript projects.
- Host: GitHub
- URL: https://github.com/Liftric/cognito-idp
- Owner: Liftric
- License: mit
- Created: 2020-07-08T17:03:51.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-11-30T07:43:26.000Z (about 1 year ago)
- Last Synced: 2024-11-01T22:36:42.120Z (2 months ago)
- Topics: android, auth, aws, aws-cognito, cognito, cognito-api, cognito-idp, hacktoberfest, identity-provider, ios, kotlin, kotlin-multiplatform, kotlin-native, liftric, typescript
- Language: Kotlin
- Homepage:
- Size: 520 KB
- Stars: 30
- Watchers: 4
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: Contributing.md
- License: LICENSE
Awesome Lists containing this project
- awesome-kotlin-multiplatform - cognito-idp - Lightweight AWS Cognito Identity Provider client for Kotlin Multiplatform projects. (Libraries / Network)
- kmp-awesome - Cognito-idp - AWS Cognito Identity Provider (Libraries / 🧩 Service SDK)
README
# Cognito-idp
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](Contributing.md) if there is something missing for you.
> Version 2 introduced breaking changes, please refer to the [migration](Migrating.md) document for help.
## Import
### Kotlin
#### Gradle
```kotlin
sourceSets {
val commonMain by getting {
dependencies {
implementation("com.liftric:cognito-idp:")
}
}
}
```
### Typescript
#### Yarn
```bash
yarn add @liftric/cognito-idp@
```
#### npm
```sh
npm i @liftric/cognito-idp@
```
## How-to
### Init
#### Kotlin
```kotlin
val provider = IdentityProviderClient("", "")
```
#### Typescript
```typescript
import {IdentityProviderClientJS} from '@liftric/cognito-idp';
const provider = new IdentityProviderClientJS('', '');
```
### Usage
#### Kotlin
All methods are suspending and return a `Result`, which wraps the desired object `T` on success or a `Throwable` on failure.
```kotlin
provider.signUp("user", "password").fold(
onSuccess = {
// Do something
},
onFailure = {
// Handle exceptions
}
)
```
#### Typescript
All methods return a [Promise](https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Promise) object.
### Errors
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`.
### Requests
#### Sign Up
Signs up the user.
Attributes are optional.
```kotlin
val attribute = UserAttribute("email", "[email protected]")
signUp("", "", listOf(attribute)): Result
```
#### Confirm Sign Up
Confirms the sign up (also the delivery medium).
```kotlin
confirmSignUp("", ""): Result
```
#### Resend Confirmation Code
Resends the confirmation code.
```kotlin
resendConfirmationCode(""): Result
```
#### Sign In
Signs in the users.
```kotlin
signIn("", ""): Result
```
#### Respond To Auth Challenge
Responds to the auth challenge of the sign in response.
```kotlin
val challengeResponses = mapOf()
respondToAuthChallenge("", challengeResponses, ""): Result
```
#### Refresh access token
Refreshes access token based on refresh token that's retrieved from an earlier sign in.
```kotlin
val signInResponse: SignInResponse = ... // from earlier login or refresh
val refreshToken = signInResponse.AuthenticationResult.RefreshToken
refresh(refreshToken): Result
```
#### Get Claims
You can retrieve the claims of both the IdTokens' and AccessTokens' payload by converting them to either a `CognitoIdToken` or `CognitoAccessToken`
```kotlin
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.
```kotlin
val twitter = idToken.claims.customAttributes["twitter"]
```
#### Get User
Returns the users attributes and metadata on success.
More info about this in the [official documentation](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUser.html).
```kotlin
getUser(""): Result
```
#### Update User Attributes
Updates the users attributes (e.g. email, phone number, ...).
```kotlin
val attributes: List = ...
updateUserAttributes("", attributes): Result
```
#### Change Password
Updates the users password
```kotlin
changePassword("", "", ""): Result
```
#### Forgot Password
Invokes password forgot and sends a confirmation code the the users' delivery medium.
More info about the ForgotPasswordResponse in the [official documentation](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CodeDeliveryDetailsType.html).
```kotlin
forgotPassword(""): Result
```
#### Confirm Forgot Password
Confirms forgot password.
```kotlin
confirmForgotPassword("", "", ""): Result
```
#### Get user Attribute Verification Code
Gets the user attribute verification code for the specified attribute name
```kotlin
getUserAttributeVerificationCode("", "", ""): Result
```
#### Verify User Attribute
Verifies the specified user attribute.
```kotlin
verifyUserAttribute("", "", ""): Result
```
#### Sign Out
Signs out the user globally.
```kotlin
signOut(""): Result
```
#### Revoke Token
Revokes all access tokens generated by the refresh token.
```kotlin
revokeToken(""): Result
```
#### Associate Software Token
Associate software token. Either with access token or session (not both).
```kotlin
associateSoftwareToken("", "
```
#### Verify Software Token
Verifies software token. Either with access token or session (not both).
```kotlin
verifySoftwareToken("", "", ""): Result
```
#### Set User MFA Preference
Set MFA preferences.
```kotlin
val smsMfaSettings = null
val softwareTokenMfaSettings = MfaSettings(true, true)
setUserMFAPreference("", smsMfaSettings, softwareTokenMfaSettings): Result
```
#### Delete User
Deletes the user from the user pool.
```kotlin
deleteUser(""): Result
```
## License
Cognito-idp is available under the MIT license. See the LICENSE file for more info.