Table of Contents

Return URLs and Custom App Schemes in Mobile Authenticators

When using authenticators based on mobile apps, like BankID/Freja eIDs 'on this device'-function, problems can arise with the return url that is sent to the mobile application. This return url is set automatically based on the device's User Agent and attempts to direct the user back to the authentication page after completing the transaction within the mobile app.

The User-Agent based browser detection only works for a handful of browsers however, so if you authenticate via an in-app browser in some native app, you may find yourself being redirected back to a default browser, or not at all. This problem can now be solved using the common configuration parameter customReturnUrls present in all our mobile based authenticators (BankID, Freja, OneTouch, Siths eID, and NIAS).

The customReturnUrls parameter

This parameter is an array parameter where each entry is a Json Object with the following structure:

Name Description Default value Mandatory
returnUrl The returnUrl to use if the expression is true. Expandable (see more below). N/A Yes
use_if_expr The expression that determines whether or not the custom returnUrl should be used (see more below) N/A Yes

If none of the customReturnUrls return true on the use_if_expr evaluation, the default automatic detection is used.

Examples

In the example below, a OneTouch authenticator is used with custom return urls:

{
    "id" : "4e3e1ab6-b8a1-4b5f-abe7-6764d751ac3a",
    "alias" : "onetouch",
    "name" : "AnonymousAssignmentAgnostic",
    "displayName" : "OneTouch",
    "configuration" : {
        "pipeID" : "14417c84-0b8a-474a-baac-0bfc760fe8bb",
        "issuer" : "PhenixID",
        "customReturnUrls" : [ {
            "returnUrl" : "myapp://{{current_url_noscheme_encoded}}",
            "use_if_expr" : "context.loginHint.contains('myapp')"
        }, {
            "returnUrl" : "otherapp://{{current_url_noscheme}}",
            "use_if_expr" : "request.getParameter('User-Agent').contains('somevalue')"
        } ]
    },
    "created" : "2024-06-12T09:14:44.806Z"
}

This example configures two custom return URLs, one which will send the user to myapp:// with the current URL if the OIDC Login Hint contains a certain string. The other return URL is used if the User-Agent header contains a certain value.

The returnUrl expansion scope

returnUrl is an expandable configuration parameter with a special scope that allows you to create your own custom return url based on the current location. The following scope is available in the expansion, and the values are derived from the current url https://www.example.org:8080/some/path?someParam=someValue#somefragment.

Name Description ** Value derived from example **
current_url_noscheme The current URL without the scheme, querystring or fragment. www.example.org/some/path
current_url_noscheme_encoded Same as above, but URIEncoded www.example.org%2Fsome%2Fpath
current_url_scheme The current URLs scheme https
current_url_host The current URLs host www.example.org
current_url_port The current URLs port 8080
current_url_path The current URLs path /some/path
current_url_path_encoded Same as above, but URIEncoded %2Fsome%2Fpath
current_url_query The current URLs queryString someParam=someValue
current_url_query_encoded Same as above, but URIEncoded someParam%3DsomeValue
current_url_questionmark_if_has_query If a queryString exists, this returns a ?, otherwise it is blank ?

The use_if_expr scope

The use_if_expr parameter is an expression that determines if the returnUrl should be used or not. It has the scope of the current request, and the current context.

Authentication App Redirect Return URL