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

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.

Want to learn more?

To learn more, see the following pages:

1. Configure the OIDC request​

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

Example: Request DigiD app-to-app in the OIDC configuration
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"
)

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:

  1. Add applinks:<YOUR_SIGNICAT_DOMAIN> to the Associated Domains capability of your app target.
  2. 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-association file of your Signicat domain.
  3. Forward the universal links that your app receives to handle(url:), as described in Forward universal links to the SDK.

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-app query 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.

Example: Validate the DigiD return link
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:

Example: Log in with DigiD
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
)
})
Implementation responsibility

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.