> **Description:** Implement the advanced mobile login flow that supports automatic app return with third-party redirect URIs and enhanced security features.
# Advanced Login from a mobile app
This advanced flow supports handling automatic return to your app even in cases where the `redirect-uri` must go through third party services. While more complex to implement, it provides excellent user experience with seamless app switching.
In this flow, the user logs in to the merchant's app with MobilePay or Vipps.
App integrations are currently based on using browsers.
This requires initiating Login through an external browser that opens within the app.
**Web views should *not* be used**
Web views should *not* be used when using Login in a native application.
Instead, users should be redirected via an external browser opened by or within the app. For more information, see
[Using Login in native applications](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/important-information.md#using-login-in-native-applications).
## The process
If the user is on a mobile device, the Vipps MobilePay landing page
in the browser will automatically trigger a deeplink to the Vipps or MobilePay app (unless the user is remembered in the browser). The user will not be prompted to enter the phone number.
In the Vipps or MobilePay app, the user confirms the login and can choose whether to be remembered in the browser for later logins. After confirming in the app, the user needs to switch back to the Vipps MobilePay page in the browser/app.
On the landing page, the user will finalize the authentication and provide consents if required. The user is then redirected back to the redirect URI provided by merchant (could be webpage or an app).
Screenshot: Seven-screen mobile login flow with partial app-switch (Vipps or MobilePay). Screens shown left to right: the merchant's login page with a "Continue with Vipps" button; a Vipps "Log in to" screen with an "Open Vipps" button; the Vipps app loading; a confirmation prompt asking the user to allow the login; a "Return to the browser or app you started in" screen; an "Info you share" consent screen listing the user's name, phone, and email; and the merchant's welcome page after a successful login.
Apps should follow the [recommendations](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/important-information.md#using-login-in-native-applications) to use correct browser types for their platform.
There are two specialized flows that merchants can use to automatically switch the user back from the Vipps or MobilePay app to the originating browser/app upon login confirmation. From the illustration above, this means that the page "Gå tilbake til butikken" will be skipped and that the "manual app switch" will be replaced by an automatic app-switch (e.g., deeplink). These flows give a better user experience than the standard flow, but they also require the merchant to handle some more complexity in the integration.
Which of the flows to use is controlled with the initiation of the individual login session. The merchant can use all available login flows on the same `client_id` and adapt to the different use cases and login scenarios.
For more illustrations, see [How it works: Login from mobile](https://developer.vippsmobilepay.com/docs/APIs/login-api/how-it-works/login-from-mobile.md).
### App-to-app flow
It is possible to enable automatic switch of users back to the merchant app,
from the Vipps or MobilePay app.
This flow is designed to be used with apps. It requires that the app initiate Login in an external browser that is opened within the app.
### Remembered flow
The user can choose to be remembered in the browser, enabling automatic sign-ins for later visits.
If a user has chosen to be remembered in browser, then the authentication can be completed in the browser.
The user will either be asked to provide consent to share profile information or be logged in directly.
If the user is not remembered, they must confirm the login in their Vipps or MobilePay app.
If the user is remembered in browser, then only the consent flow will be completed.
If the user already has provided consent, then this step will be skipped also, allowing a direct login experience.
## Integration
The merchant must specify the app URI, where the user will be returned after completing the confirmation in the Vipps/MobilePay app.
Expected flow:
User flows
```mermaid
flowchart LR
merchant([Merchant app])
merchant-- Initiate login -->browser[Merchant app controlled browser]
browser--User opens Vipps/MobilePay app in login client --> vmp(["Vipps/MobilePay app"])
vmp-- User accepts the login -->browser
browser--Finish login --> merchant
```
Advanced login flow: The merchant app initiates login, opening a merchant app controlled browser. The browser opens the Vipps or MobilePay app in the login client. The user accepts the login in the app, which returns control to the browser. The browser then finishes the login and returns the user to the merchant app.
This flow can be enabled per login request by adding the `requested_flow=app_to_app`
and `app_callback_uri` parameters to the [Authorize](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/browser-flow-integration.md#oauth-20-authorize) request.
This flow requires both the `app_callback_uri` and `redirect_uri` parameters.
**INFO**
For app URIs, we recommend using universal links (Apple)/asset links (Android) instead of custom URL schemes for better security.
The `app_callback_uri` should be a URI that makes the device switch back to the merchant's
app again after the Vipps/MobilePay app portion of the flow is done (example: `https://example.com/app/callback`).
The `redirect_uri` is opened in the browser once the login flow is completed there.
This URI can either redirect the user to a page in the browser, or be handled/intercepted by the merchant app.
In either case, it is important to avoid using static client secrets in the app for completing the login.
(For more information, see [AppAuth for Android Utilizing client secrets (DANGEROUS)](https://github.com/openid/AppAuth-Android#utilizing-client-secrets-dangerous)
and [OAuth 2.0 for Native Apps: Client Authentication](https://tools.ietf.org/html/rfc8252#section-8.5)).
*Both* URIs must be added to the sales unit on the [business portal](https://portal.vippsmobilepay.com).
For help, see
[Portal: How to set up login on your sales unit](https://developer.vippsmobilepay.com/docs/knowledge-base/portal.md#how-to-set-up-login-for-your-sales-unit).
**Important**
URIs specified on the [business portal](https://portal.vippsmobilepay.com)
must be *exactly* the same as used in the API calls. Be extra careful with
trailing `/` and URL-encoded entities. If the URIs are not identical, you will get
this error:
> "The provided authorization grant (e.g., authorization code, resource owner credentials)
> or refresh token is invalid, expired, revoked, does not match the redirection URI used
> in the authorization request, or was issued to another client"
The Vipps/MobilePay app will return some data with the return to the `app_callback_uri`.
It contains two query parameters `state` and `resume_uri`.
`State` is the OIDC `state` parameter passed at the start of a login which can be used to identify the specific login if needed.
The `resume_uri` parameter that we generate
can optionally be used to resume the login when the user returns from the Vipps/MobilePay app.
If the merchant app manages to keep the initial browser window open it is not required to use the `resume_uri`.
To use the `resume_uri`, it must be opened in the same browser used in the initial phase
(such as `ASWebAuthenticationSession` or *Chrome Custom Tabs*). It is required that the browser contains the cookies
from the interaction that happens before the user is sent to the Vipps/MobilePay app.
Example `app_callback_uri` request:
```http
https://example.com/app/callback/?state=RFiQdrl_lvJUpVmTRSKmsZRGLM0G1N1qh0WebZ1gDNk&resume_uri=https%3A%2F%2Fapi.vipps.no%2Fvipps-login-idp%2Findex.html%3FtabId%3D7607f7f0-7ae2-49b7-9cb5-102143dac4ea
```
## Sequence diagram
A typical flow/implementation might look like this:
User flows
```mermaid
sequenceDiagram
autonumber
participant vmBackend as Vipps MobilePay Backend
participant merchantBackend as Merchant backend
participant merchantApp as Merchant app
participant merchantAppControlledBrowser as Merchant app controlled browser
participant vmApp as Vipps/MobilePay app
merchantApp ->> merchantBackend : Initiate login
merchantBackend ->> merchantApp: Authorize request
merchantApp ->> merchantAppControlledBrowser : Open authorize request URL
merchantAppControlledBrowser -->> vmApp : User opens Vipps/MobilePay app in login client
vmApp -->> vmApp: User accepts the login
vmApp -->> merchantApp : Open app_callback_uri
merchantApp ->> merchantAppControlledBrowser : Either show the browser that is already open,
or open a new browser at the resume_uri
merchantAppControlledBrowser -->> merchantAppControlledBrowser: The user consents.
merchantAppControlledBrowser -->> merchantApp : Open redirect_uri, includes code and state
merchantApp ->>merchantBackend : Finish login (code, state)
merchantBackend ->> vmBackend : Get userinfo and auth token using code
vmBackend -->> merchantBackend : Userinfo / Auth token
merchantBackend ->> merchantApp : Userinfo / Auth token
```
Merchant app initiates login with the merchant backend.
Merchant backend returns the Authorize request URL to the merchant app.
Merchant app opens the Authorize request URL in the merchant app controlled browser.
Browser opens the Vipps or MobilePay app in the login client.
User accepts the login in the Vipps or MobilePay app.
Vipps or MobilePay app opens the app_callback_uri, returning control to the merchant app.
Merchant app either shows the already-open browser or opens a new browser at the resume_uri.
The user consents in the browser.
Browser opens the redirect_uri (with authorization code and state) in the merchant app.
Merchant app sends the code and state to the merchant backend to finish the login.
Merchant backend retrieves userinfo and an auth token from Vipps MobilePay Backend using the code.
Vipps MobilePay Backend returns the userinfo and auth token to the merchant backend.
Merchant backend returns the userinfo and auth token to the merchant app.
The dotted lines in this diagram are handled by us (or the user),
while the filled lines need to be implemented by the merchant.
1. The merchant's backend generates an [OpenID authentication flow authorization URI](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/browser-flow-integration.md#oauth-20-authorize).
2. The URI is communicated to the merchant's app in the API response.
3. The merchant's app uses the URI to initiate Login in an external browser
that is opened within the app.
See the [specification](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/important-information.md#using-login-in-native-applications) for details.
4. Login will open the Vipps/MobilePay app, if required.
(If the user is remembered in the browser, they will be authenticated directly,
and they will then be on step 8 below).
5. The user accepts the login in their Vipps/MobilePay app.
6. Vipps/MobilePay app opens the deep link `app_callback_uri` parameter after the user has approved the login.
7. Merchant app handles the link in one of two ways:
- Display the same browser instance that was created in (1).
- Open a browser again using the `resume_uri`-query parameter that is returned with the request to the `app_callback_uri`.
8. The user consents in the browser controlled by the merchant's app.
9. The `redirect_uri` is opened, with the `code` and `state`.
The Login process has now finished, and the merchant controls the remaining process.
10. Merchant app sends the `code` and `state` parameters received in the callback to the merchant backend.
11. Merchant backend fetches the access token and uses it to fetch /userinfo. (2 separate requests)
12. Login provides tokens and userinfo. (2 separate responses)
13. Merchant backend delivers user information to merchant app.
Example authorize request URL:
```http
.../oauth2/auth?app_callback_uri=https://example.com/app-callback&requested_flow=app_to_app&scope=&response_type=code&redirect_uri=https://example.com/app-callback&code_challenge_method=S256&state=&nonce=&client_id=&code_challenge=
```
Parameters `state` and possibly `error` will be passed as query parameters to the `app_callback_uri`. The `state` parameter has the same value as the `state` parameter passed to the [Authorize](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/browser-flow-integration.md#oauth-20-authorize) request.
Example success callback from app (step 4):
```http
https://example.com/app-callback?state=218gz18yveu1ybajwh2g1h3g&resume_uri=https://.../vipps-login-idp/index.html?tabid=fjeiwfje43t
https://example.com/app/app-callback?state=218gz18yveu1ybajwh2g1h3g&resume_uri=https://.../vipps-login-idp/index.html?tabid=fjeiwfje43t
```
Example error callback from app (step 4):
```http
https://example.com/app-callback?state=218gz18yveu1ybajwh2g1h3g?error=unknown_error
https://example.com/app/app-callback?state=218gz18yveu1ybajwh2g1h3g?error=unknown_error
```
Example success callback from browser (step 6):
```http
https://example.com/redirect-uri?state=218gz18yveu1ybajwh2g1h3g&code=&scope=openid
https://example.com/app/redirect-uri?state=218gz18yveu1ybajwh2g1h3g&code=&scope=openid
```
---
## When to use this flow
This advanced flow is recommended when you need:
- **Automatic return to your app** after authentication
- **Support for third-party redirect URIs** that must go through external services
- **Seamless user experience** with minimal manual app switching
## Alternative flows
If this flow seems too complex for your needs, consider these alternatives:
- **[Simple Login from a mobile app](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/mobile-app-flows/simple-login.md)** - Easier to implement with automatic return
- **[Login from a website](https://developer.vippsmobilepay.com/docs/APIs/login-api/api-guide/browser-flow-integration.md)** - Simple implementation, no automatic return
> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).