Mobile app delivery lifecycle

The configuration and deployment of a new application release is a process where both the application developer and the administrator of the OneWelcome Identity Platform are involved. To enable an application using the Mobile SDK to communicate with the OneWelcome Identity Platform, the app needs to be configured in the OneWelcome Identity Platform. Therefore, the application developer should know which configuration settings to use in the application that they are building. To simplify things for the application developer, the OneWelcome Identity Platform administrator can prepare and export the application configuration. This configuration is exported as a zip archive that can be used in the Mobile SDK tooling to generate the required code and configuration files.

The order of the configuration depends on the version of the Mobile SDK and what they expect as the application signature. Check the documentation of the specific Mobile SDK version to determine what is expected as signature. Application signatures are sometimes referred to as application thumbprints or application secrets.

Application signature obtained up front

The most recent versions of the OneWelcome Identity Platform SDKs use an application signature that can be obtained before the app is built. For the Android SDK, it is based on the signing certificate. For the iOS SDK, the application secret is equal to the app ID.

• Android SDK: Use the Google Play Store Console or keytool to get the SHA-256 fingerprint of your signing certificate. When you roll the signing key, you need to provide all fingerprints for this app version.

• iOS SDK: Get the App ID. Example: ABCDE12345.com.company.app

• Configure the app version in the OneWelcome Identity Platform with the provided values.

• Export the app version.

• Use the configurator to inject the configuration.

• Build your app and sign it using the selected signing certificate.

Application signature calculated from the app binary

Older versions of the OneWelcome Identity Platform SDKs require the final app build to calculate its signature.

1. Configure the app version in the OneWelcome Identity Platform with a dummy application signature.

2. Export the app version.

3. Use the Mobile SDK configurator to inject the configuration into the app.

4. Build a release of the app.

5. Use the OneWelcome Identity Platform calculator to get the actual signature.

6. Configure the actual signature in the OneWelcome Identity Platform.

Application signature during development

When the application developer has received the application configuration archive, a test build can be made using the Mobile SDK. As the final application signatures for this build are not configured, the application can only be used when the validation of the application signatures is disabled. When using Android SDK 11 and up or iOS SDK 10 and up, change the integrity level to None for this application version to skip the validation of the signature. For older Mobile SDK versions, enable development mode for the entire mobile application to skip the validation. Do not enable development mode on a production environment.

Bypassing the validation of the application signature enables functional testing of the application without configuring the correct application signature for each individual build. When testing and development are completed, the final release can be built. At this point, the application developer needs to generate the application signature based on the release version of the application. Note that each small change in the application binary impacts the application signature. So an application signature has to be generated for each version of the application, which slows down development. More details about using the Mobile SDK can be found in the platform specific Mobile SDK documentation.

Production ready application signature

The OneWelcome Identity Platform administrator is responsible for the last step in the flow. The configuration of the application signature of the release version of the application. This application signature must be sent to the OneWelcome Identity Platform administrator via a secure channel as this is very sensitive information. The integrity level must be set to Full and development mode must be disabled when the proper application signature is configured for this specific application version. The application should now be able to communicate securely with both the OneWelcome Identity Platform and the resource gateway.

Application version configuration

A OneWelcome Identity Platform administrator can export the application configuration via the export button next to an application version in the application view or via the application version API. The export is a zip file that contains all required information for the Mobile SDK. The OneWelcome Identity Platform administrator is responsible for shipping the zip archive to the application developer.

The exported zip file contains multiple elements. The paragraphs below explain the elements within the zip archive.

Certificates

The Mobile SDK provides functionality to verify your servers' TLS certificate or its certificate chain. This is called certificate pinning. When you pin the servers' certificate itself, you need to release a new version of the application in the app store when you change the servers' certificate. The best alternative is to use the intermediate certificate of the Certificate Authority used to get the server certificate (the second level in the certificate chain). Intermediate certificate are usually valid for a longer period than server certificates. This gives you the option to renew the certificate of your own server without having to deploy a new version of the application.

Make sure certificates for both the OneWelcome Identity Platform and your resource gateway are linked to an application via the configuration. When the OneWelcome Identity Platform and resource gateway are both exposed on the same domain and therefore use the same certificate, you only need to configure a single certificate.

You can attach a certificate to an application when editing or creating the application configuration in the admin console. In the certificates section, you can select the certificates you previously uploaded. Check the certificates section for instructions to upload certificates.

OneWelcome Identity Platform base URI

The OneWelcome Identity Platform base URI is the URI that all requests towards the OneWelcome Identity Platform start with. Typically, this is the host name of the OneWelcome Identity Platform. This value can be configured via the admin console in System → General → Engine base URLs.

Resource gateway

To enable the Mobile SDK to perform resource calls, the Mobile SDK requires a base URI for its resource gateway. The resource gateway is an Oauth client itself and has to be configured as an API client that can do token introspection in the OneWelcome Identity Platform admin console. The details on how to create and configure a resource gateway can be found in the resource gateway topic. When a resource gateway is selected for an application, its public base URI is used in the Mobile SDK configuration archive.

Application version details

An application should be able to identify itself towards the OneWelcome Identity Platform. This is done by sending the application version, platform, and identifier. The application configuration archive contains all these details. This makes the archive specific for the platform, application, and version.

Redirect URL

This is the primary URL to which users are redirected after they have successfully logged in. The additional redirect URLs are not exported. See the app configuration to change the redirect URL for an already deployed application. Since the redirect URL is set globally for the application, you might run into problems when building old application versions that rely on the old redirect URL. This is a known limitation of the version export.