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.
1. Configure the OIDC request
DigidApp2AppOidcConfig.kt requests the identity provider by setting the acrValues configuration property to idp:digid-app.
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()
2. Validate the App Link
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-appquery parameter. - Checks for an error response.
- Requires a SAML artifact and relay state.
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.
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.
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()
}
}
4. Declare the Activity and App Links
Finally, you must declare the Activity and the verified App Links in the AndroidManifest.xml file.
<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:
android {
defaultConfig {
manifestPlaceholders["digidApp2AppReturnUrlHost"] = "example.com"
manifestPlaceholders["digidApp2AppReturnUrlPath"] = "/broker/authn/digid/digid-app"
}
}
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-appquery parameter name. - It rejects all other links.