ForgeRock SDKs

Enable SSL pinning

The ForgeRock SDKs support SSL pinning, sometimes referred to as certificate pinning. SSL pinning is the security practice of validating the certificates presented by the server against known values.

When the SDK attempts to make an HTTPS connection to the authorization server (AM), it first verifies that a hash of the server’s public key (obtained from the server’s SSL certificate) matches a set of hashes defined within your app. This SSL pinning reduces the chance of a man-in-the-middle (MITM) attack, improving the security of your app.

If the hash does not match, your app does not connect to the authorization server, and an error is returned instead. Note that if your public key changes, you will need to rebuild and re-release your app with the new hash included.

Get a hash of AM’s public key

To enable SSL pinning you need a hash of your AM authorization server’s public key. You can use the openssl tool to extract this from your server’s SSL certificate and create the hash value.

In the following command, replace <tenant-env-fqdn> with the fully-qualified domain name of your AM server, for example, my-company.forgeblocks.com:

echo | openssl s_client -servername <tenant-env-fqdn> -connect <tenant-env-fqdn>:443 | openssl x509 -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

The command outputs a hash of the public key extracted from the certificate:

S4kZuhQQ1DPcXBSWFQXD0gG+UW7usdbVx6roNWpRl65I=

Proceed to configure SSL pinning to learn how to configure this value in the SDK.

Configure SSL pinning in iOS

To enable SSL pinning in the ForgeRock SDK for iOS, add the hash of the public keys for any AM authorization servers your application will contact to your app’s configuration.

Add the hashes to an array named forgerock_ssl_pinning_public_key_hashes in your FRAuthConfig.plist file:

<key>forgerock_ssl_pinning_public_key_hashes</key>
<array>
    <string>S4kZuhQQ1DPcXBSWFQXD0gG+UW7usdbVx6roNWpRl65I=</string>
</array>

If the public key you use to obtain SSL certificates for the AM servers change, update the FRAuthConfig.plist file with the new hash and re-release your app.

You can also update this property programmatically by using dynamic configuration.

Override default implementation of SSL pinning for iOS

You can override how the ForgeRock SDK for iOS performs SSL pinning by registering your own implementation.

To override the default SSL pinning, create a new CustomPinningHandler subclass of the default FRURLSessionSSLPinningHandler class. Override the implementation of the urlSession functions:

class CustomPinningHandler: FRURLSessionSSLPinningHandler {
    override func urlSession(_ session: URLSession, didReceive challenge: URLAuthenticationChallenge, completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
        // Provide Custom SSL Pinning handling
    }

    override func urlSession(_ session: URLSession, task: URLSessionTask, didReceive challenge: URLAuthenticationChallenge, completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
        // Provide Custom SSL Pinning handling
    }
}

Add your new custom handler as part of the configuration:

let customPinningHandler = CustomPinningHandler(frSecurityConfiguration: nil)
RestClient.shared.setURLSessionConfiguration(config: nil, handler: customPinningHandler)
Copyright © 2010-2022 ForgeRock, all rights reserved.