-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #22 from Achintha444/main
docs: improve doc site
- Loading branch information
Showing
9 changed files
with
245 additions
and
142 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| <!-- | ||
| * Copyright (c) 2024, WSO2 LLC. (https://www.wso2.com). | ||
| * | ||
| * WSO2 LLC. licenses this file to you under the Apache License, | ||
| * Version 2.0 (the "License"); you may not use this file except | ||
| * in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, | ||
| * software distributed under the License is distributed on an | ||
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| * KIND, either express or implied. See the License for the | ||
| * specific language governing permissions and limitations | ||
| * under the License. | ||
| --> | ||
|
|
||
| # Client Attestation | ||
| You can also use client attestation with the SDK as well. | ||
|
|
||
| ## How to setup client attestation for your application | ||
|
|
||
| 1. In the created mobile application in Asgardeo, go **Advanced** and check **Enable client attestation**. | ||
| 2. Subscribe to the "Google Play Integrity API" from your Google Cloud project. You can do this from **Enabled API's & Services** in your Google Cloud project. | ||
| 3. Create a new service account in the Google project. You can create a Service Account for yourself with the following steps. | ||
|
|
||
| 1. In your Google project, go to **IAM & Admin** -> **Service Accounts**. | ||
| 2. Click **Create Service Account**. | ||
| 3. Fill in the name and click **Create**. | ||
| 4. Grant your service account the roles of Service Account User and Service Usage Consumer. | ||
| 5. Click **Continue** and then **Done** | ||
| 6. You can see the service account added without keys, go to **Actions** -> **Manage Keys** on the service account. | ||
| 7. Click **Add** key and Select `JSON`. | ||
| 8. Save the JSON in a secure place as this is required for Android Attestation Credentials for application metadata. | ||
|
|
||
| 4. After that, update the Application's Advanced properties. The application you created requires two properties to perform Android attestation. | ||
|
|
||
| 1. Android package name | ||
| 2. `androidAttestationServiceCredentials` | ||
| The downloaded JSON secret of the Service Account. Note that this attribute is defined as a JSON object hence use the JSON key as it is. | ||
|
|
||
| 5. Now you can call the **Google Play Integrity API** from your application and pass the integrity token that you will get from the API result to the `integrityToken` value of the `AuthenticationCoreConfig`. | ||
|
|
||
| ```kotlin | ||
| private val asgardeoAuth: AsgardeoAuth = AsgardeoAuth.getInstance( | ||
| AuthenticationCoreConfig( | ||
| discoveryEndpoint = "https://api.asgardeo.io/t/<org_name>/oauth2/token/.well-known/openid-configuration", | ||
| redirectUri = "wso2sample://oauth2", | ||
| clientId = "<client_id>", | ||
| scope = "openid profile", | ||
| integrityToken = "<integrity_token>" // [!code highlight] | ||
| ) | ||
| ) | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| <!-- | ||
| * Copyright (c) 2024, WSO2 LLC. (https://www.wso2.com). | ||
| * | ||
| * WSO2 LLC. licenses this file to you under the Apache License, | ||
| * Version 2.0 (the "License"); you may not use this file except | ||
| * in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, | ||
| * software distributed under the License is distributed on an | ||
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| * KIND, either express or implied. See the License for the | ||
| * specific language governing permissions and limitations | ||
| * under the License. | ||
| --> | ||
|
|
||
| # Asgardeo Android SDK | ||
|
|
||
| The Asgardeo Auth Android SDK enables Android applications (written in Kotlin) to utilize OpenID Connect (OIDC) authentication with Asgardeo serving as the Consumer Identity and Access Management (CIAM) Provider through application-native authentication. | ||
|
|
||
| This SDK assists you in creating custom login flows directly within the applications themselves, without relying on browser redirects, thereby prioritizing user experience. | ||
|
|
||
| ## Requirements and recommendations | ||
|
|
||
| * An Android application written in Kotlin programming language. | ||
| * The minimum supported SDK is API level 26, compiled to API level 34. However, there are certain limitations when using specific authentication methods: | ||
| * Passkeys are only supported on API level 34 and above. | ||
| * Google authentication using the Credential Manager API is supported on API level 34 and above. | ||
|
|
||
| ## Getting Started | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - [Register to Asgardeo and create an organization if you don't already have one](https://wso2.com/asgardeo/docs/get-started/create-asgardeo-account/). The organization name you choose will be referred to as `<org_name>` throughout this document. | ||
| - [Register a mobile application in Asgardeo to integrate your application with Asgardeo](https://wso2.com/asgardeo/docs/guides/applications/register-mobile-app/). You will obtain a `client_id` from Asgardeo for your application which will need to be embedded later for the SDK integration. Also note the redirect URI that you used to create the application, this is also required for the SDK integration. | ||
| - In the created mobile application, go to the **Advanced** tab and [enable the application native authentication for your Android application](https://is.docs.wso2.com/en/latest/guides/authentication/add-application-native-login/#enable-app-native-authentication). | ||
|
|
||
| ### Installing the SDK | ||
|
|
||
| 1. Open the `build.gradle` file of your Android application and add the following dependency to add the latest released SDK. | ||
|
|
||
| ```groovy | ||
| dependencies { | ||
| implementation 'io.asgardeo:android:<latest-version>' | ||
| } | ||
| ``` | ||
| You can find the latest version of the SDK from the [Maven Repository](https://central.sonatype.com/artifact/io.asgardeo/android.ui). | ||
| 2. Add a redirect scheme in the Android application. You need to add the `appAuthRedirectScheme` in the application `build.gradle` file. | ||
| This should be consistent with the CallBack URL of the Service Provider that you configured in the Asgardeo. | ||
| For example, if you have configured the CallBack URL as *wso2sample://oauth2*, then the `appAuthRedirectScheme` should be *wso2sample*. | ||
| ```groovy | ||
| android.defaultConfig.manifestPlaceholders = [ | ||
| 'appAuthRedirectScheme': 'wso2sample' // [!code highlight] | ||
| ] | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| <!-- | ||
| * Copyright (c) 2024, WSO2 LLC. (https://www.wso2.com). | ||
| * | ||
| * WSO2 LLC. licenses this file to you under the Apache License, | ||
| * Version 2.0 (the "License"); you may not use this file except | ||
| * in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, | ||
| * software distributed under the License is distributed on an | ||
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| * KIND, either express or implied. See the License for the | ||
| * specific language governing permissions and limitations | ||
| * under the License. | ||
| --> | ||
|
|
||
| # Logout | ||
|
|
||
| If you want to perform a logout, you can call the `logout` function in the <a href="/mobile-ui-sdks/android/api/core/io.asgardeo.android.core.provider.providers.authentication/-authentication-provider/index.html" target="_blank">AuthenticationProvider</a>. This will emit the state **AuthenticationState.Initial** if the logout is successful, and if an error occurs, it will emit **AuthenticationState.Error**. | ||
|
|
||
| ```kotlin | ||
| authenticationProvider.logout(context) | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| <!-- | ||
| * Copyright (c) 2024, WSO2 LLC. (https://www.wso2.com). | ||
| * | ||
| * WSO2 LLC. licenses this file to you under the Apache License, | ||
| * Version 2.0 (the "License"); you may not use this file except | ||
| * in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, | ||
| * software distributed under the License is distributed on an | ||
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| * KIND, either express or implied. See the License for the | ||
| * specific language governing permissions and limitations | ||
| * under the License. | ||
| --> | ||
|
|
||
| # Get Token Information | ||
|
|
||
| To get information, you can use the <a href="mobile-ui-sdks/android/api/core/io.asgardeo.android.core.provider.providers.token/-token-provider/index.html" target="_blank">TokenProvider</a>. This will assist you in getting token-related information and performing actions on the tokens. | ||
|
|
||
| ```kotlin | ||
| val tokenProvider: TokenProvider = asgardeoAuth.getTokenProvider() | ||
| ``` | ||
|
|
||
| To get the token-related information, you can use the following functions: | ||
|
|
||
| ```kotlin | ||
| val accessToken: String? = tokenProvider.getAccessToken(context) | ||
| val idToken: String? = tokenProvider.getIDToken(context) | ||
| val refreshToken: String? = tokenProvider.getRefreshToken(context) | ||
| val accessTokenExpirationTime: Long? = tokenProvider.getAccessTokenExpirationTime(context) | ||
| val scope:String? = tokenProvider.getScope(context) | ||
| ``` | ||
|
|
||
| ## Perform action based on the tokens | ||
|
|
||
| If you want to perform any action based on the tokens that are returned, you can use the `performAction` function in the <a href="mobile-ui-sdks/android/api/core/io.asgardeo.android.core.provider.providers.token/-token-provider/index.html" target="_blank">TokenProvider</a>. | ||
|
|
||
| ```kotlin | ||
| tokenProvider.performAction(context) { accessToken, idToken, -> | ||
| action(accessToken, idToken) | ||
| } | ||
| ``` |
Oops, something went wrong.