Rebar iOS App Configuration File

Monkton, Inc.

App Configurations allow for multiple configurations to be generated for an app being built. These configurations can range from endpoints to security configuration settings.

The configuration file is simply named app-config.json, our sample apps include the build scripts and configuration file layout to generate a development, production, and test builds with different configurations.

Structure is as follows:

{project_root}/config/production/app-config.json

{project_root}/config/development/app-config.json

{project_root}/config/test/app-config.json

API Url

The rebar.api.url field configures the API endpoint in which the App will communicate. This field can also be a Managed App Config pushed down by your MDM.

The rebar.api.url should be the full URL to your api endpoint in the format: https://api.example.com/v1

If this field is omitted it will cause the app sanity check to fail.

This field is mandatory.

Url Scheme

The rebar.scheme is a string value indicating the url scheme of this app. This will allow for other apps to perform callbacks when necessary.

This field is optional.

The default value is null.

SSL Pinning

The rebar.tls.pinned is a string array of acceptable SHA-512 hashes of the server certificates. These hashes should be generated using the Admin console. This field can also be a Managed App Config pushed down by your MDM

SSL Pinning adds another layer of security and verification of certificates when using TLS.

This field is mandatory.

Okta Configuration

To configure Okta within the app, there are a series of keys that need to be present. rebar.auth must be set to okta for Okta authentication to work.

To configure Okta, add the following fields:

"rebar.auth":"okta",
"rebar.okta.clientId": "your-client-id",
"rebar.okta.redirectUri": "your-bundle-id",
"rebar.okta.domain": "your-okta-domain.okta.com/oauth2/default",

Rebar will pull these settings when the app is run and leverage them for authentication.

  • rebar.auth: this field set to okta will force authentication with Okta
  • rebar.okta.clientId: the client identifier from Okta to bind the user to
  • rebar.okta.redirectUri: the app bundle id, registered in Okta
  • rebar.okta.domain: your Okta instance domain

More information on configuring Okta can be found here

OCSP Enabled

The rebar.useOCSP is a boolean value that indicates to the Rebar SDK that OCSP checks of certificates are enabled. This field can also be a Managed App Config pushed down by your MDM

The Rebar SDK will attempt to perform the OCSP check to validate that the certificate presented from the server is valid and that the certificate chain is valid.

These checks are mandatory through via NIAP FIA_X509_EXT.1.1.

The default value is true.

Continue on OCSP Error

The rebar.continueOnOCSPError is a boolean value that indicates that the OSCP checks, if failed, should be allowed to continue on. OCSP checks can fail if the server cannot be reached. This field can also be a Managed App Config pushed down by your MDM

For more information on the requirements of this flag please consult NIAP FIA_X509_EXT.2.2.

The default value is false.

Continue on OCSP Signing Missing

The rebar.continueOnOCSPSigningMissing is a boolean value that indicates that the OSCP checks, if missing the OCSP Signing OID, should be allowed to continue on. This field can also be a Managed App Config pushed down by your MDM

For more information on the requirements of this flag please consult NIAP FIA_X509_EXT.2.2.

The default value is false.

App Permissions

The rebar.permissions is a dictionary of permissions that the app can request. These permissions must be mapped in the config files. These permissions will be prompted to the user when they authenticate with the app the first login.

For instance, the permissions would be configured like ("none" permissions maybe omitted):

"rebar.permissions": {
	"pii": { "request": "required" },
	"location": { "request": "required" },
	"push": { "request": "none" },
	"microphone": { "request": "none" },
	"camera": { "request": "none" },
	"calendar": { "request": "none" },
	"contacts": { "request": "none" },
	"motion": { "request": "none" },
	"photos": { "request": "none" },
	"reminders": { "request": "none" }
},
  • pii - indicates the app may use and transfer PII
  • push - indicates that push permissions will be requested
  • location - indicates that location will be requested
  • microphone - indicates that the microphone will be requested
  • camera - indicates that the camera will be requested
  • calendar - indicates that the calendar will be requested
  • contacts - indicates that the contacts will be requested
  • motion - indicates that the motion sensors will be requested
  • photos - indicates that the photo library will be requested
  • reminders - indicates that the reminders will be requested

Note With the exception of push, you must request each permission yourself.

Keychain Access Group

The rebar.keychain.group is a mandatory string field for iOS. This value allows all iOS apps signed with the same signing certificate to store common data in a shared keychain.

When configuring your app, the project will need to enable Keychain Sharing under your Capabilities in XCode for the targets. The value should be the same and shared across all projects for your enterprise.

If this field is omitted it will cause the app sanity check to fail.

Account Authentication Type

The rebar.auth is a mandatory string value that indicates how accounts will login to the app. There are four options, credentials (email and password), purebred, yubico-piv, and qrauth. This field can also be a Managed App Config pushed down by your MDM

Acceptable values:

  • credentials
  • purebred
  • yubico-piv
  • qrauth
  • okta

More information on on MFAKit can be found here

In invalid or missing value will cause the app sanity check to fail.

The default value is null.

Create Account Options

The rebar.account.create is an optional string value that indicates if and how accounts can be created on the device. If null is given for this value, the user will not see a "Create Account" button or screen.

Note Active Directory backed accounts login to the app, they do not create accounts. If only letting AD backed accounts are being used this value should be null.

Acceptable values:

  • null
  • tokens

The default value is null.

Keychain Storage

The rebar.keychain.type is an optional string value indicating how the keychain should be managed for this app. This field can prevent keychains from being backed up to iCloud. Any value with the suffix ThisDeviceOnly prevents iCloud backup. We strongly advise using only AccessibleAfterFirstUnlockThisDeviceOnly.

Acceptable values:

  • AccessibleWhenUnlocked
  • AccessibleAfterFirstUnlock
  • AccessibleAlways
  • AccessibleWhenUnlockedThisDeviceOnly
  • AccessibleAfterFirstUnlockThisDeviceOnly
  • AccessibleAlwaysThisDeviceOnly
  • AccessibleWhenPasscodeSetThisDeviceOnly

The default value is AccessibleAfterFirstUnlockThisDeviceOnly.

DOD Specific Elements

For federal customer there are prebuilt screens for user acceptance.

DOD Welcome Banner

The rebar.dodBanner is a boolean value that indicates that the App should display a startup banner when the user authenticates into the application. This field can also be a Managed App Config pushed down by your MDM.

The default value is false.

DOD Welcome Banner Text

The rebar.dodBannerText is a string value that overrides the DOD Welcome Banner text. This field can also be a Managed App Config pushed down by your MDM.

The default value is null.

NIAP Testing Configuration Elements

Several NIAP testing elements can be configured here.

NIAP Debug Harness

The rebar.niap-harness is a boolean value that indicates that the App should include and use and enable our NIAP Debug Harness features. This field can also be a Managed App Config pushed down by your MDM.

The default value is false.

NIAP Auditing

The rebar.niap-audit is a boolean value that indicates that the App should perform our NIAP Auditing functionality for testing under NIAP. This field can also be a Managed App Config pushed down by your MDM.

The default value is false.

NIAP TLS Auditing

The rebar.tlsLogging is a boolean value that indicates that the App should print out logging information from our TLS sessions. This field can also be a Managed App Config pushed down by your MDM.

The default value is false.

UI / UX Configuration Elements

Several UX elements can be controlled and configured through the configuration file.

Default Color

The rebar.color is a string hexadecimal value (e.g. #AAAAAA) value that will color the Rebar generated screens within the app. This allows a custom color scheme to be presented for the app during the configuration process. This field can also be a Managed App Config pushed down by your MDM

App Welcome Screen

The rebar.screen.welcome is an optional string value that maps to the class name of a custom welcome screen. This screen will present the user with a custom view that welcomes them to the app. The screen should implement the Rebar method calls to create accounts or login.

If this value is set, Rebar will instantiate and create the welcome screen.

The default value is null.

Main App Screen

The rebar.screen.main is an optional/mandatory string value that maps to the class name of the main user interface for this app.

If this value is set, Rebar will instantiate and create the main screen.

For iOS, if the main UI of the app is derived from a storyboard, main-screen must be null, but the implementing app must override the mainScreen method in the RebarAppConfiguration class. The implementation of the mainScreen method should instantiate and return the main UI instance and not retain it.

The default value is null.

The rebar.app.logo is an optional string value that maps to the name of an image set (iOS) or image resource (Android). When no welcome-screen is set, this image will be set for the welcome screen.

The default value is null.