iOS implementation
The Signicat OIDC SDK includes an iOS demo app that demonstrates the complete DigiD app-to-app flow.
Use the steps below as a reference for your own implementation.
To learn more, see the following pages:
- OIDC SDK for iOS.
- Demo app for iOS.
- App-to-app flow for iOS.
1. Configure the OIDC request
DemoOIDCConfigurations.swift requests the identity provider by setting the acrValues configuration property to idp:digid-app:
let configuration = try OIDCConfiguration(
issuer: URL(string: "https://<YOUR_SIGNICAT_DOMAIN>/auth/open")!,
clientId: "<CLIENT_ID>",
redirectUri: URL(string: "<REDIRECT_URI>")!,
scopes: ["openid", "offline_access", "nin", "idp-id"],
acrValues: "idp:digid-app"
)
2. Set up the universal link
The DigiD app returns the end-user to:
https://<YOUR_SIGNICAT_DOMAIN>/broker/authn/digid/digid-app
To receive this link in your app, you need to do the following:
- Add
applinks:<YOUR_SIGNICAT_DOMAIN>to the Associated Domains capability of your app target. - Send us your Team ID and bundle ID by creating a support ticket in the Signicat Dashboard. We add your app to the
apple-app-site-associationfile of your Signicat domain. - Forward the universal links that your app receives to
handle(url:), as described in Forward universal links to the SDK.
3. Validate the return 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, DigiDApp2AppCallback:
- Accepts only the expected scheme, host, port and path.
- Reads the
app-appquery parameter. - Checks for an error response.
- Requires a SAML artifact and relay state.
Finally, it builds the URL of the Signicat broker endpoint that continues the flow.
struct DigiDApp2AppCallback {
private static let responsePath = "/broker/authn/digid/digid-app"
static func matches(_ url: URL, brokerACSURL: URL) -> Bool {
guard let urlScheme = url.scheme?.lowercased(),
let brokerScheme = brokerACSURL.scheme?.lowercased(),
urlScheme == brokerScheme,
let urlHost = url.host?.lowercased(),
let brokerHost = brokerACSURL.host?.lowercased(),
urlHost == brokerHost,
url.port == brokerACSURL.port else {
return false
}
let normalizedPath = (url.path.count > 1 && url.path.hasSuffix("/")) ? String(url.path.dropLast()) : url.path
return normalizedPath == responsePath
}
static func brokerURL(from callbackURL: URL, brokerACSURL: URL) throws -> URL {
// Re-checked here, not just in the caller: this parses a link handed over by another app,
// so origin validation must be enforced by the compiler rather than by a comment.
guard matches(callbackURL, brokerACSURL: brokerACSURL) else {
throw SignicatOIDCError.appLinkHandlerFailed("Invalid DigiD App2App response")
}
guard let components = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false),
let queryItems = components.queryItems,
let encodedResponse = queryItems.first(where: { $0.name == "app-app" })?.value,
!encodedResponse.isEmpty else {
throw SignicatOIDCError.appLinkHandlerFailed("Invalid DigiD App2App response")
}
guard let data = decodeBase64(encodedResponse) else {
throw SignicatOIDCError.appLinkHandlerFailed("Invalid DigiD App2App response")
}
guard let response = try? JSONDecoder().decode(DigiDResponse.self, from: data) else {
throw SignicatOIDCError.appLinkHandlerFailed("Invalid DigiD App2App response")
}
if let errorMessage = response.errorMessage, !errorMessage.isEmpty {
throw SignicatOIDCError.appLinkHandlerFailed(errorMessage)
}
guard let samlArtifact = response.samlArtifact, !samlArtifact.isEmpty,
let relayState = response.relayState, !relayState.isEmpty else {
throw SignicatOIDCError.appLinkHandlerFailed("Invalid DigiD App2App response")
}
var brokerComponents = URLComponents(url: brokerACSURL, resolvingAgainstBaseURL: false)
brokerComponents?.queryItems = [
URLQueryItem(name: "SAMLart", value: samlArtifact),
URLQueryItem(name: "RelayState", value: relayState)
]
let encodedQuery = brokerComponents?.percentEncodedQuery?
.replacingOccurrences(of: "+", with: "%2B")
brokerComponents?.percentEncodedQuery = encodedQuery
guard let url = brokerComponents?.url else {
throw SignicatOIDCError.appLinkHandlerFailed("Invalid DigiD App2App response")
}
return url
}
private static func decodeBase64(_ base64String: String) -> Data? {
var base64 = base64String
.replacingOccurrences(of: "-", with: "+")
.replacingOccurrences(of: "_", with: "/")
.replacingOccurrences(of: " ", with: "+")
.trimmingCharacters(in: .whitespacesAndNewlines)
let remainder = base64.count % 4
if remainder > 0 {
base64.append(String(repeating: "=", count: 4 - remainder))
}
return Data(base64Encoded: base64, options: .ignoreUnknownCharacters)
}
}
private struct DigiDResponse: Decodable {
let samlArtifact: String?
let relayState: String?
let errorMessage: String?
enum CodingKeys: String, CodingKey {
case samlArtifact = "SAMLart"
case relayState = "RelayState"
case errorMessage = "ErrorMessage"
}
}
4. 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. The SDK follows the redirects from this endpoint to complete the OIDC flow without opening a browser.
Pass a handler to login() that sends DigiD return links to DigiDApp2AppCallback and ignores other links:
let brokerACSURL = URL(
string: "https://<YOUR_SIGNICAT_DOMAIN>/broker/authn/digid/digid-app-acs"
)!
SignicatOIDCClient.shared.configuration = configuration
let session = try await SignicatOIDCClient.shared.login(appLinkHandler: { url in
guard DigiDApp2AppCallback.matches(url, brokerACSURL: brokerACSURL) else {
return nil
}
return try DigiDApp2AppCallback.brokerURL(
from: url,
brokerACSURL: brokerACSURL
)
})
Your app implements the return-link validation and the handler passed to the SDK. Use the demo implementation as a starting point and validate the host, path and query parameter before forwarding the result to Signicat.