Add application-native login

In a conventional mobile application, users are typically redirected to an external web browser during login.

However, with app-native authentication, developers can integrate a seamless api-based authentication mechanism within the application itself so that users are never taken out of the context of the application. Learn more about application-native authentication.

As app-native authentication is an extension to OAuth 2.0, it also offers many of the flexibility and security features that the OAuth 2.0 protocol offers.

Limitations of app-native authentication

App-native authentication has the following limitations compared to a browser-based OAuth 2.0 flow:
App-native authentication,

does not prompt the user to provide consent to share user attributes with the application.
does not prompt the user to provide missing mandatory attributes.
does not support prompts in adaptive authentication flows.
cannot be initiated if a non API-based authentication method is configured for the application.
cannot enroll authenticators (e.g. TOTP authenticator) during authentication.

The following guide explains how you can implement app-native authentication for your application using Asgardeo.

# Prerequisites

To get started, you need to register an application with Asgardeo.
You need to have a user account in Asgardeo. If you don't already have one, create a user account in Asgardeo.

# Enable app-native authentication

Follow the steps below to enable app-native authentication for your application.

On the Asgardeo Console, go to Applications.
Go to the Protocol tab and select Code from Allowed grant types.
Go to the Advanced tab of your application and select Enable app-native authentication API.
Configure client attestation settings according to the platform that hosts your application.

Learn more about client attestation in the secure app-native authentication documentation.
Click Update to save the changes.

# Initiate an app-native authentication request

App-native authentication is an extension to the OAuth 2.0 protocol. As shown below, the initial request is similar to a typical OAuth 2.0 authorization code request, but with the response_mode parameter set to direct.

Sample request

curl --location 'https://localhost:9443/oauth2/authorize/'
--header 'Accept: application/json'
--header 'Content-Type: application/x-www-form-urlencoded'
--data-urlencode 'client_id=<client_id>'
--data-urlencode 'response_type=<response_type>'
--data-urlencode 'redirect_uri=<redircet_url>'
--data-urlencode 'state=<state>'
--data-urlencode 'scope=<space separated scopes>'
--data-urlencode 'response_mode=direct'

1
2
3
4
5
6
7
8
9

Example

curl --location 'https://localhost:9443/oauth2/authorize/'
--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'

1
2
3
4
5
6
7
8
9

Learn more about OAuth2 authorization requests in the documentation.

When the response_mode is set to direct as shown above, all subsequent requests will be directed to the /authn endpoint.

Find detailed information on the /authn endpoint in the openAPI definition of the authentication API.

# Secure app-native requests

API-based authentication uses the authentication API which is an open API that does not require any form of authentication. You can implement the following mechanisms to secure the authentication request.

# Enable client attestation

An adversary, often another mobile application, can attempt to mimic or impersonate a legitimate client application during the authentication process. This may lead to the following security threats.

User Deception: The malicious app may trick users into providing their credentials by making them believe they are interacting with a legitimate application.
Token Interception: The malicious app may extract the authorization code or tokens exchanged during the authentication process, gaining unauthorized access to the user's resources.

Client attestation ensures the authenticity of the client making requests to Asgardeo.

If the application is hosted either in the 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.

On the Asgardeo Console, go to Applications.
Go to the Advanced tab of your application and select Enable client attestation.
Select either Apple or Android to specify which attestation service you wish to use.
Provide details about the attestation service.
- For android:
  
  By leveraging the Google Play Integrity API, ensures a heightened level of security for Application Native Authentication. It actively detects and responds to potential threats, thereby safeguarding against attacks and mitigating the risk of abuse.
  
  Learn more about the Play Integrity API (opens new window).
  - Provide the package name of the application which takes the format of the reverse domain format (e.g. com.example.myapp).
  - Provide the service account credentials.
  Learn more about service account credentials (opens new window).
- For apple:
  
  By leveraging DCAppAttestService, Asgardeo adds an extra layer of security to Application Native Authentication for iOS apps. It actively detects and responds to potential threats, safeguarding against unauthorized access and malicious activities.
  
  Learn more about Apple's DeviceCheck Attest Service (opens new window).
  - Provide the app ID of your application which consists of the Team ID and the bundle ID separated by a period (.). (e.g. A1B2C3D4E5.com.domainname.applicationname)
Click Update to save the changes.

# Secure request authentication

Confidential clients that are able to securely store a secret can implement the following methods to secure authentication requests.

Choose a client authentication method to secure the /token endpoint. See client authentication methods for more details.
Follow the steps below to make Pushed Authorization Requests (PAR) mandatory for the application. See Implement login using Pushed Authorization Requests for more details.
1. On the Asgardeo Console, go to Applications.
2. Go to the Protocol tab of the application, select the Mandatory checkbox under Pushed Authorization Requests.
3. Click Update to save the changes.

# Handle SSO with app-native authentication

With app-native authentication there are two ways that Single Sign-On (SSO) can be handled for user sessions.

App-native authentication, just as the OAuth authorization code flow, sets an SSO cookie (commonAuthId). If the cookie is preserved, any subsequent authorization request that occurs with this cookie will automatically perform SSO.

# SessionId based SSO

SessionId parameter based SSO is useful if the implementation does not manage session cookies. The id_token that the application receives after the initial authentication request, contains the isk claim. When making a subsequent authorization request the isk value can be used as the sessionId for SSO to occur.

Given below is a sample authorization request using the isk value as the sessionId