For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Android implementation

The Signicat OIDC SDK includes an Android demo app that demonstrates the complete DigiD app-to-app flow.

Use the steps below as a reference for your own implementation.

Want to learn more?

To learn more, see the following pages:

1. Configure the OIDC request​

DigidApp2AppOidcConfig.kt requests the identity provider by setting the acrValues configuration property to idp:digid-app.

Example: Request DigiD app-to-app in the OIDC configuration
val DigidApp2AppOidcConfig = OIDCConfiguration(
issuer = "https://example.com/auth/open".toUri(),
clientId = "your-client-id",
redirectUri = "https://example.com/redirect/response".toUri(),
promptLogin = true,
acrValues = "idp:digid-app",
scopes = setOf("openid", "offline_access", "idp-id", "nin")
)

/** Host expected on the App Link returned by the DigiD app. */
val DigidApp2AppReturnUrlHost = "example.com"

/** Exact path expected on the App Link returned by the DigiD app. */
val DigidApp2AppReturnUrlPath = "/broker/authn/digid/digid-app"

/** Broker endpoint that resumes the OIDC flow. */
val DigidApp2AppAcsUri = "https://example.com/broker/authn/digid/digid-app-acs".toUri()

The DigiD app sends its response in a single app-app query parameter, which contains a Base64-encoded JSON object.

To validate the response, DigidApp2AppResponseParserActivity.kt:

  • Accepts only the expected scheme, host and path.
  • Reads the app-app query parameter.
  • Checks for an error response.
  • Requires a SAML artifact and relay state.
Example: Validate the App Link returned by the DigiD app
private fun handleResponse(appLinkData: Uri?): JsonObject {
val validAppLinkUri = validateHttpResponse(appLinkData)
val appData = validAppLinkUri.getQueryParameter(APP_APP)
?: error("Invalid url supplied: $appLinkData")
val responseMessage = String(Base64.decode(appData, Base64.DEFAULT), Charsets.UTF_8)
return validateDataResponse(Json.decodeFromString<JsonObject>(responseMessage))
}

private fun validateHttpResponse(appLinkData: Uri?): Uri {
if (appLinkData == null) {
error("No app link data has been supplied")
} else if (
appLinkData.scheme != "https" ||
appLinkData.host != DigidApp2AppReturnUrlHost ||
appLinkData.path != DigidApp2AppReturnUrlPath ||
appLinkData.queryParameterNames.size != 1 ||
appLinkData.getQueryParameter(APP_APP).isNullOrBlank()
) {
error("Invalid url supplied: $appLinkData")
}
return appLinkData
}

private fun validateDataResponse(appResponse: JsonObject): JsonObject {
if (RELAY_STATE !in appResponse || SAML_ART !in appResponse) {
if ("ErrorMessage" in appResponse) {
error(appResponse.getValue("ErrorMessage").jsonPrimitive.content)
} else {
error("App response data is invalid")
}
}
return appResponse
}

companion object {
private const val APP_APP = "app-app"
private const val SAML_ART = "SAMLart"
private const val RELAY_STATE = "RelayState"
}

3. Resume the OIDC flow​

To resume the OIDC flow, the demo app sends the SAML artifact and relay state received from the DigiD app to the Signicat broker's Assertion Consumer Service (ACS) endpoint. It opens the endpoint in the same browser that login() opened, so the flow continues in the browser session that started it.

AndroidX Browser dependency

The SDK's createOidcCustomTabsIntent(context) helper returns a CustomTabsIntent. To use the returned value, add AndroidX Browser as a dependency of your own app module. For details, see App-to-app flow.

Example: Resume the OIDC flow in a Custom Tab
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
if (savedInstanceState != null) return
try {
val appLinkData = intent.data
val jsonResponse = handleResponse(appLinkData)
val acsUri = DigidApp2AppAcsUri.buildUpon()
.appendQueryParameter(SAML_ART, jsonResponse.getValue(SAML_ART).jsonPrimitive.content)
.appendQueryParameter(RELAY_STATE, jsonResponse.getValue(RELAY_STATE).jsonPrimitive.content)
.build()
createOidcCustomTabsIntent(this).launchUrl(this, acsUri)
} catch (e: Exception) {
if (BuildConfig.DEBUG) {
Log.e("DigidApp2AppResponseParserActivity", "Error parsing response from Digid app", e)
}
finish()
}
}

Finally, you must declare the Activity and the verified App Links in the AndroidManifest.xml file.

Example: Declare the Activity and its App Link
<activity
android:name=".digid_app2app.DigidApp2AppResponseParserActivity"
android:exported="true"
android:launchMode="singleTop"
android:noHistory="true">
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />

<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />

<data
android:host="${digidApp2AppReturnUrlHost}"
android:path="${digidApp2AppReturnUrlPath}"
android:scheme="https" />
</intent-filter>
</activity>

The host and path come from manifest placeholders, declared alongside the ones you set for the redirect URI:

Example: Declare the return path in build.gradle.kts
android {
defaultConfig {
manifestPlaceholders["digidApp2AppReturnUrlHost"] = "example.com"
manifestPlaceholders["digidApp2AppReturnUrlPath"] = "/broker/authn/digid/digid-app"
}
}
Implementation responsibility

This handling is implemented in the demo app, not in the SDK. If you integrate an app-to-app flow, your app must receive and validate the return link. You can treat the demo Activity as a starting point:

  • It accepts only the configured host and path.
  • It accepts only the app-app query parameter name.
  • It rejects all other links.