From 8b4fb6b1a2ea8c785c0fa42d151f37fdd082c362 Mon Sep 17 00:00:00 2001 From: himesh Date: Tue, 14 May 2024 17:58:21 +0530 Subject: [PATCH 1/2] Made improvements to the app-native authentication docs --- .../add-advanced-configurations.md | 5 + .../add-app-native-authentication.md | 2 +- en/asgardeo/mkdocs.yml | 4 +- .../add-advanced-configurations.md} | 2 +- .../add-app-native-authentication.md | 3 + en/identity-server/7.0.0/mkdocs.yml | 9 +- .../add-advanced-configurations.md} | 2 +- .../add-app-native-authentication.md | 3 + en/identity-server/next/mkdocs.yml | 9 +- .../add-advanced-configurations.md} | 130 +----------------- .../add-app-native-authentication.md | 125 +++++++++++++++++ .../references/app-native-authentication.md | 130 ++++++++---------- 12 files changed, 214 insertions(+), 210 deletions(-) create mode 100644 en/asgardeo/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md rename en/asgardeo/docs/guides/authentication/{ => app-native-authentication}/add-app-native-authentication.md (60%) rename en/identity-server/7.0.0/docs/guides/authentication/{add-app-native-authentication.md => app-native-authentication/add-advanced-configurations.md} (54%) create mode 100644 en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md rename en/identity-server/next/docs/guides/authentication/{add-app-native-authentication.md => app-native-authentication/add-advanced-configurations.md} (54%) create mode 100644 en/identity-server/next/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md rename en/includes/guides/authentication/{add-app-native-authentication.md => app-native-authentication/add-advanced-configurations.md} (51%) create mode 100644 en/includes/guides/authentication/app-native-authentication/add-app-native-authentication.md diff --git a/en/asgardeo/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md b/en/asgardeo/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md new file mode 100644 index 0000000000..ea324bebfd --- /dev/null +++ b/en/asgardeo/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md @@ -0,0 +1,5 @@ +{% set api_base_path = "https://api.asgardeo.io/t/{organization_name}/oauth2/authorize/" %} +{% set api_example_base_path = "https://api.asgardeo.io/t/bifrost/oauth2/authorize/" %} + +{% include "../../../../../includes/guides/authentication/app-native-authentication/add-advanced-configurations.md" %} + diff --git a/en/asgardeo/docs/guides/authentication/add-app-native-authentication.md b/en/asgardeo/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md similarity index 60% rename from en/asgardeo/docs/guides/authentication/add-app-native-authentication.md rename to en/asgardeo/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md index d4ccc2bfc3..fd43e30795 100644 --- a/en/asgardeo/docs/guides/authentication/add-app-native-authentication.md +++ b/en/asgardeo/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md @@ -1,4 +1,4 @@ {% set api_base_path = "https://api.asgardeo.io/t/{organization_name}/oauth2/authorize/" %} {% set api_example_base_path = "https://api.asgardeo.io/t/bifrost/oauth2/authorize/" %} -{% include "../../../../includes/guides/authentication/add-app-native-authentication.md" %} \ No newline at end of file +{% include "../../../../../includes/guides/authentication/app-native-authentication/add-app-native-authentication.md" %} \ No newline at end of file diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index d2cb362a2d..a9aa49e889 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -200,7 +200,9 @@ nav: - MFA based on advanced conditions (using WSO2 Choreo): guides/authentication/conditional-auth/add-authentications-based-on-api-calls.md - Add passkey progressive enrollment: guides/authentication/conditional-auth/passkey-progressive-enrollment-based-template.md - Write a custom authentication script: guides/authentication/conditional-auth/write-your-first-script.md - - Add app-native authentication: guides/authentication/add-app-native-authentication.md + - App-native authentication: + - Add app-native authentication: guides/authentication/app-native-authentication/add-app-native-authentication.md + - Add advanced app-native configurations: guides/authentication/app-native-authentication/add-advanced-configurations.md - Login Flow AI: guides/authentication/ai-loginflow.md - Configure OIDC flows: - Configure OIDC flows: guides/authentication/oidc/index.md diff --git a/en/identity-server/7.0.0/docs/guides/authentication/add-app-native-authentication.md b/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md similarity index 54% rename from en/identity-server/7.0.0/docs/guides/authentication/add-app-native-authentication.md rename to en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md index e880d3c68f..fbfad86987 100644 --- a/en/identity-server/7.0.0/docs/guides/authentication/add-app-native-authentication.md +++ b/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md @@ -1,3 +1,3 @@ {% set api_base_path = "https://localhost:9443/oauth2/authorize/" %} {% set api_example_base_path = "https://localhost:9443/oauth2/authorize/" %} -{% include "../../../../../includes/guides/authentication/add-app-native-authentication.md" %} \ No newline at end of file +{% include "../../../../../../includes/guides/authentication/app-native-authentication/add-advanced-configurations.md" %} \ No newline at end of file diff --git a/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md b/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md new file mode 100644 index 0000000000..31d8103e18 --- /dev/null +++ b/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md @@ -0,0 +1,3 @@ +{% set api_base_path = "https://localhost:9443/oauth2/authorize/" %} +{% set api_example_base_path = "https://localhost:9443/oauth2/authorize/" %} +{% include "../../../../../../includes/guides/authentication/app-native-authentication/add-app-native-authentication.md" %} \ No newline at end of file diff --git a/en/identity-server/7.0.0/mkdocs.yml b/en/identity-server/7.0.0/mkdocs.yml index 6ad784a9a9..a6198502e0 100644 --- a/en/identity-server/7.0.0/mkdocs.yml +++ b/en/identity-server/7.0.0/mkdocs.yml @@ -46,8 +46,9 @@ plugins: 'guides/authentication/enterprise-login/index.md': 'guides/authentication/standard-based-login/index.md' 'guides/authentication/enterprise-login/add-oidc-idp-login.md': 'guides/authentication/standard-based-login/add-oidc-idp-login.md' 'guides/authentication/enterprise-login/add-saml-idp-login.md': 'guides/authentication/standard-based-login/add-saml-idp-login.md' - 'guides/request-path-auth/request-paths-overview.md': 'guides/authentication/add-app-native-authentication.md' - 'guides/request-path-auth/oauth-request-path.md': 'guides/authentication/add-app-native-authentication.md' + 'guides/request-path-auth/request-paths-overview.md': 'guides/authentication/app-native-authentication/add-app-native-authentication.md' + 'guides/request-path-auth/oauth-request-path.md': 'guides/authentication/app-native-authentication/add-app-native-authentication.md' + 'guides/authentication/add-application-native-login.md': 'guides/authentication/app-native-authentication/add-app-native-authentication.md' 'guides/passwordless/overview.md': 'guides/authentication/passwordless-login.md' 'guides/passwordless/magic-link.md': 'guides/authentication/passwordless-login/add-passwordless-login-with-magic-link.md' 'guides/passwordless/fido.md': 'guides/authentication/passwordless-login/add-passwordless-login-with-passkey.md' @@ -414,7 +415,9 @@ nav: - Add passkey progressive enrollment: guides/authentication/conditional-auth/passkey-progressive-enrollment-based-template.md - Write a custom authentication script: guides/authentication/conditional-auth/write-your-first-script.md - Configure multi-attribute login: guides/authentication/multi-attribute-login.md - - Add app-native authentication: guides/authentication/add-app-native-authentication.md + - App-native authentication: + - Add app-native authentication: guides/authentication/app-native-authentication/add-app-native-authentication.md + - Add advanced app-native configurations: guides/authentication/app-native-authentication/add-advanced-configurations.md - Configure OIDC flows: - Configure OIDC flows: guides/authentication/oidc/index.md - Discover OIDC endpoints: guides/authentication/oidc/discover-oidc-configs.md diff --git a/en/identity-server/next/docs/guides/authentication/add-app-native-authentication.md b/en/identity-server/next/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md similarity index 54% rename from en/identity-server/next/docs/guides/authentication/add-app-native-authentication.md rename to en/identity-server/next/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md index e880d3c68f..fbfad86987 100644 --- a/en/identity-server/next/docs/guides/authentication/add-app-native-authentication.md +++ b/en/identity-server/next/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md @@ -1,3 +1,3 @@ {% set api_base_path = "https://localhost:9443/oauth2/authorize/" %} {% set api_example_base_path = "https://localhost:9443/oauth2/authorize/" %} -{% include "../../../../../includes/guides/authentication/add-app-native-authentication.md" %} \ No newline at end of file +{% include "../../../../../../includes/guides/authentication/app-native-authentication/add-advanced-configurations.md" %} \ No newline at end of file diff --git a/en/identity-server/next/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md b/en/identity-server/next/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md new file mode 100644 index 0000000000..31d8103e18 --- /dev/null +++ b/en/identity-server/next/docs/guides/authentication/app-native-authentication/add-app-native-authentication.md @@ -0,0 +1,3 @@ +{% set api_base_path = "https://localhost:9443/oauth2/authorize/" %} +{% set api_example_base_path = "https://localhost:9443/oauth2/authorize/" %} +{% include "../../../../../../includes/guides/authentication/app-native-authentication/add-app-native-authentication.md" %} \ No newline at end of file diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index ff857fea25..70133a2122 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/en/identity-server/next/mkdocs.yml @@ -46,8 +46,9 @@ plugins: 'guides/authentication/enterprise-login/index.md': 'guides/authentication/standard-based-login/index.md' 'guides/authentication/enterprise-login/add-oidc-idp-login.md': 'guides/authentication/standard-based-login/add-oidc-idp-login.md' 'guides/authentication/enterprise-login/add-saml-idp-login.md': 'guides/authentication/standard-based-login/add-saml-idp-login.md' - 'guides/request-path-auth/request-paths-overview.md': 'guides/authentication/add-app-native-authentication.md' - 'guides/request-path-auth/oauth-request-path.md': 'guides/authentication/add-app-native-authentication.md' + 'guides/request-path-auth/request-paths-overview.md': 'guides/authentication//app-native-authentication/add-app-native-authentication.md' + 'guides/request-path-auth/oauth-request-path.md': 'guides/authentication/app-native-authentication/add-app-native-authentication.md' + 'guides/authentication/add-application-native-login.md': 'guides/authentication/app-native-authentication/add-app-native-authentication.md' 'guides/passwordless/overview.md': 'guides/authentication/passwordless-login.md' 'guides/passwordless/magic-link.md': 'guides/authentication/passwordless-login/add-passwordless-login-with-magic-link.md' 'guides/passwordless/fido.md': 'guides/authentication/passwordless-login/add-passwordless-login-with-passkey.md' @@ -414,7 +415,9 @@ nav: - Add passkey progressive enrollment: guides/authentication/conditional-auth/passkey-progressive-enrollment-based-template.md - Write a custom authentication script: guides/authentication/conditional-auth/write-your-first-script.md - Configure multi-attribute login: guides/authentication/multi-attribute-login.md - - Add app-native authentication: guides/authentication/add-app-native-authentication.md + - App-native authentication: + - Add app-native authentication: guides/authentication/app-native-authentication/add-app-native-authentication.md + - Add advanced app-native configurations: guides/authentication/app-native-authentication/add-advanced-configurations.md - Configure OIDC flows: - Configure OIDC flows: guides/authentication/oidc/index.md - Discover OIDC endpoints: guides/authentication/oidc/discover-oidc-configs.md diff --git a/en/includes/guides/authentication/add-app-native-authentication.md b/en/includes/guides/authentication/app-native-authentication/add-advanced-configurations.md similarity index 51% rename from en/includes/guides/authentication/add-app-native-authentication.md rename to en/includes/guides/authentication/app-native-authentication/add-advanced-configurations.md index b8684f943d..235904439a 100644 --- a/en/includes/guides/authentication/add-app-native-authentication.md +++ b/en/includes/guides/authentication/app-native-authentication/add-advanced-configurations.md @@ -1,136 +1,16 @@ -# Add app-native authentication +# Add advanced app-native configurations -In traditional mobile applications, users often get redirected to an external web browser for login. -However, with App-Native Authentication, developers can implement a login experience directly within the application along with features such as Multi-Factor Authentication (MFA), adaptive authentication, and support for federated logins. +Follow the guides below to discover advanced configurations for app-native authentication. -## Why app-native authentication? - -For most applications, browser-based authentication is the straightforward approach as the application, then, does not have to deal with risks associated with handling sensitive user data. - -However, an app-native login experience means users get to enjoy a seamless login experience. This is also ideal if you have a business requirement to keep the users within the application's environment without redirecting them elsewhere for login. - -!!! warning "Limitations of App-Native Authentication" - - App-native authentication, albeit convenient, has the following limitations. - - - It should ONLY be used for the organization's own applications and should NOT be used with third-party applications as the user credentials may get exposed to third parties. - - - It has the following limitations compared to a browser-based authentication flow: - - Does not prompt for user consent for attribute sharing or access delegation. - - Does not prompt the user to provide missing mandatory attributes. - - Does not support prompts in adaptive authentication flows. - - Does not support all authentication methods. If you have an unsupported option configured, the login flow will not be initiated. - - Cannot enroll authenticators (e.g. TOTP authenticator) during authentication. - -## How it works - -App-Native Authentication is an extension to the OAuth 2.0 protocol. The following steps give an overview on how app-native authentication is executed from an application. - -1. The initial request made by the application is similar to a typical [OAuth 2.0 authorization code request]({{base_path}}/guides/authentication/oidc/implement-auth-code/) but with the `response_mode` set to `direct` as shown below. - - === "Sample request" - - ```java - curl --location '{{api_base_path}}' - --header 'Accept: application/json' - --header 'Content-Type: application/x-www-form-urlencoded' - --data-urlencode 'client_id=' - --data-urlencode 'response_type=' - --data-urlencode 'redirect_uri=' - --data-urlencode 'state=' - --data-urlencode 'scope=' - --data-urlencode 'response_mode=direct' - ``` - - === "Example" - ```java - curl --location '{{api_example_base_path}}' - --header 'Accept: application/json' - --header 'Content-Type: application/x-www-form-urlencoded' - --data-urlencode 'client_id=VTs12Ie26wb8HebnWercWZiAhMMa' - --data-urlencode 'response_type=code' - --data-urlencode 'redirect_uri=https://example-app.com/redirect' - --data-urlencode 'state=logpg' - --data-urlencode 'scope=openid internal_login' - --data-urlencode 'response_mode=direct' - ``` - - The response contains the following key components. - - - **flowId** - used to uniquely identify a single user login flow. This value is carried forward to the subsequent requests of the process for identification. - - **nextStep** - describes the authentication options configured for the next step of the login flow. - - -2. For the next phase of the process, the application starts interacting with the **Authentication API**. This interaction continues until all the steps of the login flow are complete. - - !!! tip "What is the Authentication API?" - The Authentication API is an interactive, and a stateful API that facilitates a multi-step authentication flow within an application. See its [OpenAPI definition]({{base_path}}/apis//app-native-authentication-api/) for more details. - - The application sends a request to the authentication API with the following key components. - - - **flowId** - The unique value received when initiating the login flow. - - **selectedAuthenticator** - The authentication option that the user selected and its credentials. - - The response contains the following key components. - - - **flowStatus**: Describes if the login flow is complete or incomplete. - - **nextStep** - describes the authentication options configured for the next step of the login flow. - -3. Once the login flow is complete, the application receives an authorization code. - -!!! note "Learn more" - While this section provides a brief overview, it is highly recommended to read through [app-native authentication]({{base_path}}/references/app-native-authentication) to understand the concept in detail. - - -## Try it out -Follow the steps below to try out App-Native Authentication with {{product_name}}. - -### Prerequisites - -- To get started, you need to [register an application with {{ product_name }}]({{base_path}}/guides/applications/). - -- You need to have a user account in {{ product_name }}. If you don't already have one, [create a user account]({{base_path}}/guides/users/manage-users/#onboard-a-user) in {{ product_name }}. - -### Enable App-Native Authentication - -Follow the steps below to enable app-native authentication for your application. - -1. On {{product_name}} Console, go to **Applications**. - -2. Go to the **Protocol** tab and select **Code** from **Allowed grant types**. - -3. Click **Update** to save the changes. - -4. Go to the **Advanced** tab of your application and select **Enable app-native authentication API**. - - ![Enable app-native authentication]({{base_path}}/assets/img/guides/app-native-authentication/enable-app-native-authentication.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"} - -5. Click **Update** to save the changes. - -6. Go to the **Login flow** tab and configure a login flow with the supported authentication options. - - ??? tip "Finding supported authentication options in the login flow" - Supported authentication options are tagged with `#APIAuth`. - - ![Supported authentication options]({{base_path}}/assets/img/guides/app-native-authentication/supported-authentication-options.png){: width="400" style="display: block; margin: 0;"} - -7. Click **Update** to save the changes. - -8. Try out App-Native Authentication using Postman. - {% if product_name=="Asgardeo"%} - [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/8657284-83f51f64-fe45-4ca4-88b0-f670562d6b44){: target="#"} - {% else %} - [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/8657284-8d164672-61aa-4326-bc5e-30314c49f6d0){: target="#"} - {% endif %} +!!! note "Before you begin" + [Add app-native authentication]({{base_path}}/guides/authentication/app-native-authentication/add-app-native-authentication/) to your application. ## Secure the authentication request + In App-Native Authentication, users input their credentials directly into the application. Hence, malicious applications mimicking the legitimate application may be able to capture user credentials. You can implement the following mechanisms to secure authentication requests. While these mechanisms are only applicable for the initial authentication request, all subsequent requests are bound to it via a unique identifier (flowId), which prevents alterations during the process. -- **Client attestation** - If the application is published in the Apple App Store or Google Play Store, attestation capabilities provided by the platform can be used to ensure the request originated from the legitimate client application. -- **Client authentication** - If the application is capable of securely storing a client secret (confidential client), client authentication can be used to secure the request. - ### Using client attestation If the application is hosted either in the Apple App Store or the Google Play Store, follow the steps below to leverage the attestation services provided by these platforms to verify the legitimacy of the client. diff --git a/en/includes/guides/authentication/app-native-authentication/add-app-native-authentication.md b/en/includes/guides/authentication/app-native-authentication/add-app-native-authentication.md new file mode 100644 index 0000000000..230c629127 --- /dev/null +++ b/en/includes/guides/authentication/app-native-authentication/add-app-native-authentication.md @@ -0,0 +1,125 @@ +# Add app-native authentication + +In traditional applications, login is usually fulfilled by a web browser. This means that the users who attempt to log in to these applications will have to be redirected to a web browser for authentication. This is not ideal if your goal is to provide the user with a seamless login experience or if you have a business need to keep users within the application's environment. + +App-Native Authentication takes an API-based approach to let developers implement a secure login experience directly within the application along with features such as Multi-Factor Authentication (MFA), adaptive authentication, and support for federated logins. With app-native authentication users will have a seamless login experience from right within the application without the need to be redirected elsewhere for login. + + +!!! warning "Limitations of App-Native Authentication" + + - At the time of login, app-native authentication, + + - does not prompt the user to provide missing mandatory attributes. + - does not prompt the user for consent to share attributes with the application. + - does not support prompts in adaptive authentication flows. + - does not facilitate enrolling authenticators (e.g. TOTP authenticator). + + - App-native authentication does not support all authentication methods. If you have an unsupported option configured, the login flow will not be initiated. + + +## How it works + +The following diagram illustrates the high-level steps involved with app-native authentication. + +![app-native-authentication-sequence]({{base_path}}/assets/img/guides/app-native-authentication/app-native-authentication-sequence.png){: width="650" style="display: block; margin: 0; border: 0px;"} + + +1. User initiates a login request at the application's login page. +2. The application initiates an app-native authentication request with the server. The initial request made by the application is similar to an [OAuth 2.0 authorization code request]({{base_path}}/guides/authentication/oidc/implement-auth-code/) but with the `response_mode` set to `direct` as shown below. + + === "Sample request" + + ```java + curl --location '{{api_base_path}}' + --header 'Accept: application/json' + --header 'Content-Type: application/x-www-form-urlencoded' + --data-urlencode 'client_id=' + --data-urlencode 'response_type=' + --data-urlencode 'redirect_uri=' + --data-urlencode 'state=' + --data-urlencode 'scope=' + --data-urlencode 'response_mode=direct' + ``` + + === "Example" + ```java + curl --location '{{api_example_base_path}}' + --header 'Accept: application/json' + --header 'Content-Type: application/x-www-form-urlencoded' + --data-urlencode 'client_id=VTs12Ie26wb8HebnWercWZiAhMMa' + --data-urlencode 'response_type=code' + --data-urlencode 'redirect_uri=https://example-app.com/redirect' + --data-urlencode 'state=logpg' + --data-urlencode 'scope=openid internal_login' + --data-urlencode 'response_mode=direct' + ``` + +3. The server responds with instructions for the next step of the authentication. +4. The application displays the available authentication options to the user and prompts the user to enter the credentials. +5. User interacts with the application and enters the credentials for a selected authentication option. +6. The application gathers the credentials and sends an authentication request back to the server using the **Authentication API**. + + !!! info + Steps 3-6 repeat for all authentication steps configured for the application. + + !!! tip "What is the Authentication API?" + - The Authentication API is an interactive, stateful API that facilitates a multi-step authentication flow. See its [OpenAPI definition]({{base_path}}/apis/app-native-authentication-api/) for more details. + - While app-native authentication is initiated at the `/authorize` endpoint, the authentication API fulfills the actual authentication for each step by interacting with the `/authn` endpoint. + +7. After the authentication is complete, the application receives an OAuth2 authorization code in the response. + +!!! note "Learn more" + While this section provides a brief overview, it is highly recommended to read through [app-native authentication]({{base_path}}/references/app-native-authentication) to understand the concept in detail. + + +## Try it out +Follow the steps below to try out App-Native Authentication with {{product_name}}. + +!!! warning "Attention" + App-native authentication should be limited exclusively to an organization's internal applications. AVOID using it with third-party applications to mitigate the risk of credential exposure. + +### Prerequisites + +- To get started, you need to [register an application with {{ product_name }}]({{base_path}}/guides/applications/). + +- You need to have a user account in {{ product_name }}. If you don't already have one, [create a user account]({{base_path}}/guides/users/manage-users/#onboard-a-user) in {{ product_name }}. + +### Enable App-Native Authentication + +Follow the steps below to enable app-native authentication for your application. + +1. On {{product_name}} Console, go to **Applications**. + +2. Go to the **Protocol** tab and select **Code** from **Allowed grant types**. + +3. Click **Update** to save the changes. + +4. Go to the **Advanced** tab of your application and select **Enable app-native authentication API**. + + ![Enable app-native authentication]({{base_path}}/assets/img/guides/app-native-authentication/enable-app-native-authentication.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"} + +5. Click **Update** to save the changes. + +6. Go to the **Login flow** tab and configure a login flow with the supported authentication options. + + ??? tip "Finding supported authentication options in the login flow" + Supported authentication options are tagged with `#APIAuth`. + + ![Supported authentication options]({{base_path}}/assets/img/guides/app-native-authentication/supported-authentication-options.png){: width="400" style="display: block; margin: 0;"} + +7. Click **Update** to save the changes. + +8. Try out App-Native Authentication using Postman. + + {% if product_name=="Asgardeo"%} + [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/8657284-83f51f64-fe45-4ca4-88b0-f670562d6b44){: target="#"} + {% else %} + [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/8657284-8d164672-61aa-4326-bc5e-30314c49f6d0){: target="#"} + {% endif %} + + !!! note + Learn more about the API calls in [App-native authentication]({{base_path}}/references/app-native-authentication/). + +## What's next? + +Go through [Add advanced app-native configurations]({{base_path}}/guides/authentication/app-native-authentication/add-advanced-configurations/) to learn about advanced features such as how to secure the authentication request and handle Single Sign-On (SSO) with app-native authentication. \ No newline at end of file diff --git a/en/includes/references/app-native-authentication.md b/en/includes/references/app-native-authentication.md index 98fb0ad40e..aae8799fd7 100644 --- a/en/includes/references/app-native-authentication.md +++ b/en/includes/references/app-native-authentication.md @@ -1,43 +1,21 @@ # App-native authentication -Traditional mobile applications usually depend on external web browsers for login. This means that users logging into a mobile application is directed away from application's environment to a web browser to complete the login process. This is not ideal if your priority is to implement a seamless login experience. +Applications usually depend on external web browsers for login. This means that users logging into an application are directed away from the application's environment to a web browser to complete the login process. This is not ideal if your priority is to implement a seamless login experience. -App-native authentication was introduced as a solution to this problem. By adopting an API-based approach, app-native authentication provides a secure login process while retaining users within the application's environment. - -This document contains detailed information on the **authentication API** that powers app-native authentication. - -!!! note - - Explore the OpenAPI definition of the [authentication API]({{base_path}}/apis/app-native-authentication-api/). - - Learn how to [implement app-native authentication in {{product_name}}]({{base_path}}/guides/authentication/add-app-native-authentication) - -## How does it work? +App-native authentication was introduced as a solution to this problem. By adopting an API-based approach, app-native authentication provides developers means to develop a secure login process within the application. The following diagram illustrates the high-level steps involved with app-native authentication. ![app-native-authentication-sequence]({{base_path}}/assets/img/guides/app-native-authentication/app-native-authentication-sequence.png){: width="650" style="display: block; margin: 0; border: 0px;"} +!!! note + Learn how to [implement app-native authentication in {{product_name}}]({{base_path}}/guides/authentication/app-native-authentication/add-app-native-authentication) -1. User initiates a login request at the application's login page. -2. The application initiates an app-native authentication request. -3. The server responds with instructions for the next step of the authentication. -4. The application displays the available authentication options to the user and prompts the user to enter the credentials. -5. User interacts with the application and enters the credentials for a selected authentication option. -6. The application gathers the credentials and sends the response back to the server. - - !!! info - Steps 3-6 repeat until the authentication flow is completed. - -7. After a successful authentication, the application receives an OAuth2 authorization code which concludes the interaction. -8. The application can then exchange the authorization code for an access token. - -## How Authentication API works +## How does it work? -We discussed app-native authentication on a high level in the previous section. This section intends to dig deep into the [authentication API]({{base_path}}/apis/app-native-authentication-api/) and look at how it achieves app-native authentication. +This section digs deep into the steps involved in app-native authentication and the associated API calls. -1. When an application initiates an app-native login, it is done using an OAuth 2.0 authorization code request with the `response_mode` set to `direct` as shown below. - - !!! note - Learn how to [implement login using the authorization code flow]({{base_path}}/guides/authentication/oidc/implement-auth-code/) +1. Applications initiate app-native authentication using an OAuth 2.0 authorization code request by setting the `response_mode` to `direct` as shown below. === "Sample request (`/authorize`)" @@ -67,51 +45,12 @@ We discussed app-native authentication on a high level in the previous section. --data-urlencode 'response_mode=direct' ``` -2. The application in return, receives a response that contain the **flowId** parameter and the authentication options available for the first step. - !!! note - In app-native authentication, after the initial request to the `/authorize` endpoint, subsequent requests are made to the `/authn` endpoint. The **flowId** parameter is used to bind the requests made to the `/authn` endpoint to the initial request. - -3. The application then sends a POST request to the `/authn` endpoint with a payload as shown below. - - - === "Sample payload (`/authn`)" - - ```json - { - "flowId": "{flowId received from the initial response}", - "selectedAuthenticator": { - "authenticatorId": "{authenticator id for the selected authenticator}", - "params": { - "{requested parameters from the authenticator}" - } - } - } - ``` - - === "Example (`/authn`)" - - ``` json - { - "flowId": "3bd1f207-e5b5-4b45-8a91-13b0acfb2151", - "selectedAuthenticator": { - "authenticatorId": "QmFzaWNBdXRoZW50aWNhdG9yOkxPQ0FM", - "params": { - "username": "johnd", - "password": "U$3r" - } - } - } - ``` - ??? note "learn about the parameters" - - **flowId**: A unique identifier for the entire authentication flow. This is provided in the initial response for the auth request. - - **selectedAuthenticator**: The authenticator selected by the user for authentication. - - **authenticatorId**: The unique identifier of the authenticator. - - **params**: The values entered by the user for the parameters required for authentication. - -4. The response of the `/authn` endpoint will be as follows. + Learn how to [implement login using the authorization code flow]({{base_path}}/guides/authentication/oidc/implement-auth-code/). +2. The application receives the following response that contains key components like the **flowId** parameter that uniquely identifies the login flow and the **authenticators** array that contains the authentication options available for the first step. + ``` json { "flowId": "3bd1f207-e5b5-4b45-8a91-13b0acfb2151", @@ -168,8 +107,8 @@ We discussed app-native authentication on a high level in the previous section. ] } ``` - - ??? note "learn about the parameters" + + ??? note "Learn about the parameters" - **flowId**: A unique identifier for the entire authentication flow. - **flowStatus**: Indicates the status of the authentication flow. Possible values are `INCOMPLETE`, `FAILED_INCOMPLETE`, and `SUCCESS_COMPLETED`. @@ -193,9 +132,50 @@ We discussed app-native authentication on a high level in the previous section. - **messages**: The info and error messages related to the authentication option. - **i18nKey**: The internationalization key. This key will be available many places of the response and can be used where content localization is required. -5. Steps 3 and 4 are done repeatedly until all the steps of the login flow are complete. +3. The application then gathers the credentials for one of the presented authentication options from the user. + +4. The applcation makes a POST request to the `/authn` endpoint using the **Authentication API**. The payload of this request includes the **flowId** and the **selectedAuthenticator** object which contains credentials for the user-selected authentication option. + + !!! note + Explore the OpenAPI definition of the [authentication API]({{base_path}}/apis/app-native-authentication-api/). + + === "Sample payload (`/authn`)" + ```json + { + "flowId": "{flowId received from the initial response}", + "selectedAuthenticator": { + "authenticatorId": "{authenticator id for the selected authenticator}", + "params": { + "{requested parameters from the authenticator}" + } + } + } + ``` + === "Example (`/authn`)" + ``` json + { + "flowId": "3bd1f207-e5b5-4b45-8a91-13b0acfb2151", + "selectedAuthenticator": { + "authenticatorId": "QmFzaWNBdXRoZW50aWNhdG9yOkxPQ0FM", + "params": { + "username": "johnd", + "password": "U$3r" + } + } + } + ``` + + ??? note "Learn about the parameters" + - **flowId**: A unique identifier for the entire authentication flow. This is provided in the initial response forthe auth request. + - **selectedAuthenticator**: The authenticator selected by the user for authentication. + - **authenticatorId**: The unique identifier of the authenticator. + - **params**: The values entered by the user for the parameters required for authentication. + +5. The authentication API responds with a similar payload as step 2 above. This response contains the **authenticators** array that contains the authentication options available for the next step. + +6. Steps 3-5 repeats for all the steps of the login flow. -6. The authentication flow completes when the application receives an OAuth 2.0 authorization code with the relevant OAuth 2.0 artifacts in a json format as shown below. +7. The authentication flow completes when the application receives an OAuth 2.0 authorization code with the relevant OAuth 2.0 artifacts in a json format as shown below. ```json { "code": "6ff8b7e1-01fc-39b9-b56d-a1f5826e6d2a", From 0f4b2023a1f2e8899a6fa6bffdb12eb311cc55cc Mon Sep 17 00:00:00 2001 From: himesh Date: Wed, 15 May 2024 13:18:37 +0530 Subject: [PATCH 2/2] further improvements --- ...ns.md => configure-advanced-app-native-settings.md} | 2 +- en/asgardeo/mkdocs.yml | 2 +- ...ns.md => configure-advanced-app-native-settings.md} | 2 +- .../authentication/app-native-authentication/index.md | 1 + en/identity-server/7.0.0/mkdocs.yml | 3 ++- ...ns.md => configure-advanced-app-native-settings.md} | 2 +- en/identity-server/next/mkdocs.yml | 2 +- .../add-app-native-authentication.md | 2 +- ...ns.md => configure-advanced-app-native-settings.md} | 5 +++-- .../authentication/app-native-authentication/index.md | 10 ++++++++++ 10 files changed, 22 insertions(+), 9 deletions(-) rename en/asgardeo/docs/guides/authentication/app-native-authentication/{add-advanced-configurations.md => configure-advanced-app-native-settings.md} (78%) rename en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/{add-advanced-configurations.md => configure-advanced-app-native-settings.md} (75%) create mode 100644 en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/index.md rename en/identity-server/next/docs/guides/authentication/app-native-authentication/{add-advanced-configurations.md => configure-advanced-app-native-settings.md} (75%) rename en/includes/guides/authentication/app-native-authentication/{add-advanced-configurations.md => configure-advanced-app-native-settings.md} (96%) create mode 100644 en/includes/guides/authentication/app-native-authentication/index.md diff --git a/en/asgardeo/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md b/en/asgardeo/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md similarity index 78% rename from en/asgardeo/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md rename to en/asgardeo/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md index ea324bebfd..a54411f62d 100644 --- a/en/asgardeo/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md +++ b/en/asgardeo/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md @@ -1,5 +1,5 @@ {% set api_base_path = "https://api.asgardeo.io/t/{organization_name}/oauth2/authorize/" %} {% set api_example_base_path = "https://api.asgardeo.io/t/bifrost/oauth2/authorize/" %} -{% include "../../../../../includes/guides/authentication/app-native-authentication/add-advanced-configurations.md" %} +{% include "../../../../../includes/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md" %} diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index a9aa49e889..826ff7b2fe 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -202,7 +202,7 @@ nav: - Write a custom authentication script: guides/authentication/conditional-auth/write-your-first-script.md - App-native authentication: - Add app-native authentication: guides/authentication/app-native-authentication/add-app-native-authentication.md - - Add advanced app-native configurations: guides/authentication/app-native-authentication/add-advanced-configurations.md + - Configure advanced app-native settings: guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md - Login Flow AI: guides/authentication/ai-loginflow.md - Configure OIDC flows: - Configure OIDC flows: guides/authentication/oidc/index.md diff --git a/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md b/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md similarity index 75% rename from en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md rename to en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md index fbfad86987..9b5003fde8 100644 --- a/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md +++ b/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md @@ -1,3 +1,3 @@ {% set api_base_path = "https://localhost:9443/oauth2/authorize/" %} {% set api_example_base_path = "https://localhost:9443/oauth2/authorize/" %} -{% include "../../../../../../includes/guides/authentication/app-native-authentication/add-advanced-configurations.md" %} \ No newline at end of file +{% include "../../../../../../includes/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md" %} \ No newline at end of file diff --git a/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/index.md b/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/index.md new file mode 100644 index 0000000000..4247bbc9a4 --- /dev/null +++ b/en/identity-server/7.0.0/docs/guides/authentication/app-native-authentication/index.md @@ -0,0 +1 @@ +{% include "../../../../../../includes/guides/authentication/app-native-authentication/index.md" %} \ No newline at end of file diff --git a/en/identity-server/7.0.0/mkdocs.yml b/en/identity-server/7.0.0/mkdocs.yml index a6198502e0..4c237d9131 100644 --- a/en/identity-server/7.0.0/mkdocs.yml +++ b/en/identity-server/7.0.0/mkdocs.yml @@ -416,8 +416,9 @@ nav: - Write a custom authentication script: guides/authentication/conditional-auth/write-your-first-script.md - Configure multi-attribute login: guides/authentication/multi-attribute-login.md - App-native authentication: + - App-native authentication: guides/authentication/app-native-authentication/index.md - Add app-native authentication: guides/authentication/app-native-authentication/add-app-native-authentication.md - - Add advanced app-native configurations: guides/authentication/app-native-authentication/add-advanced-configurations.md + - Configure advanced app-native settings: guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md - Configure OIDC flows: - Configure OIDC flows: guides/authentication/oidc/index.md - Discover OIDC endpoints: guides/authentication/oidc/discover-oidc-configs.md diff --git a/en/identity-server/next/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md b/en/identity-server/next/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md similarity index 75% rename from en/identity-server/next/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md rename to en/identity-server/next/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md index fbfad86987..9b5003fde8 100644 --- a/en/identity-server/next/docs/guides/authentication/app-native-authentication/add-advanced-configurations.md +++ b/en/identity-server/next/docs/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md @@ -1,3 +1,3 @@ {% set api_base_path = "https://localhost:9443/oauth2/authorize/" %} {% set api_example_base_path = "https://localhost:9443/oauth2/authorize/" %} -{% include "../../../../../../includes/guides/authentication/app-native-authentication/add-advanced-configurations.md" %} \ No newline at end of file +{% include "../../../../../../includes/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md" %} \ No newline at end of file diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index 70133a2122..65cef3018f 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/en/identity-server/next/mkdocs.yml @@ -417,7 +417,7 @@ nav: - Configure multi-attribute login: guides/authentication/multi-attribute-login.md - App-native authentication: - Add app-native authentication: guides/authentication/app-native-authentication/add-app-native-authentication.md - - Add advanced app-native configurations: guides/authentication/app-native-authentication/add-advanced-configurations.md + - Configure advanced app-native settings: guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md - Configure OIDC flows: - Configure OIDC flows: guides/authentication/oidc/index.md - Discover OIDC endpoints: guides/authentication/oidc/discover-oidc-configs.md diff --git a/en/includes/guides/authentication/app-native-authentication/add-app-native-authentication.md b/en/includes/guides/authentication/app-native-authentication/add-app-native-authentication.md index 230c629127..2421c4551d 100644 --- a/en/includes/guides/authentication/app-native-authentication/add-app-native-authentication.md +++ b/en/includes/guides/authentication/app-native-authentication/add-app-native-authentication.md @@ -122,4 +122,4 @@ Follow the steps below to enable app-native authentication for your application. ## What's next? -Go through [Add advanced app-native configurations]({{base_path}}/guides/authentication/app-native-authentication/add-advanced-configurations/) to learn about advanced features such as how to secure the authentication request and handle Single Sign-On (SSO) with app-native authentication. \ No newline at end of file +Go through [Add advanced app-native configurations]({{base_path}}/guides/authentication/app-native-authentication/configure-advanced-app-native-settings/) to learn about advanced features such as how to secure the authentication request and handle Single Sign-On (SSO) with app-native authentication. \ No newline at end of file diff --git a/en/includes/guides/authentication/app-native-authentication/add-advanced-configurations.md b/en/includes/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md similarity index 96% rename from en/includes/guides/authentication/app-native-authentication/add-advanced-configurations.md rename to en/includes/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md index 235904439a..5622485870 100644 --- a/en/includes/guides/authentication/app-native-authentication/add-advanced-configurations.md +++ b/en/includes/guides/authentication/app-native-authentication/configure-advanced-app-native-settings.md @@ -1,4 +1,4 @@ -# Add advanced app-native configurations +# Configure advanced app-native settings Follow the guides below to discover advanced configurations for app-native authentication. @@ -9,7 +9,8 @@ Follow the guides below to discover advanced configurations for app-native authe In App-Native Authentication, users input their credentials directly into the application. Hence, malicious applications mimicking the legitimate application may be able to capture user credentials. You can implement the following mechanisms to secure authentication requests. -While these mechanisms are only applicable for the initial authentication request, all subsequent requests are bound to it via a unique identifier (flowId), which prevents alterations during the process. +!!! note + While these mechanisms are only applicable for the initial authentication request, all subsequent requests are bound to it via a unique identifier (flowId), which prevents alterations during the process. ### Using client attestation If the application is hosted either in the Apple App Store or the Google Play Store, follow the steps below to leverage diff --git a/en/includes/guides/authentication/app-native-authentication/index.md b/en/includes/guides/authentication/app-native-authentication/index.md new file mode 100644 index 0000000000..173fbf30e0 --- /dev/null +++ b/en/includes/guides/authentication/app-native-authentication/index.md @@ -0,0 +1,10 @@ +# App-native authentication + +App-native authentication is an API-based mechanism that helps developers integrate login flows within an application. + +This means that users logging in to the application do not have to be redirected to an external web browser for login resulting in a seamless user experience. As a business, you can leverage app-native authentication to retain users within the application's environment at all times. + +This section guides you through the following. + +1. [Add app-native authentication]({{base_path}}/guides/authentication/app-native-authentication/add-app-native-authentication/) to your applications. +2. [Configure advanced app-native settings]({{base_path}}/guides/authentication/app-native-authentication/configure-advanced-app-native-settings/) to improve security and user experience of app-native authentication. \ No newline at end of file