iOS - InboundSSO Module

InboundSSO provides OAuth 2.0 and OpenID Connect (OIDC) authentication for Q2DevApp. On iOS, this module is implemented specifically with the Okta mobile SDK and replaces the standard login screen with an external identity-provider-driven sign-in flow.

Authentication Architecture

The iOS InboundSSO module is Okta-based:

it uses Okta's BrowserSignin package (from okta-mobile-swift) to perform sign-in
issuerUrl should point to the Okta issuer or Okta custom domain used for the FI
after a successful sign-in, the module expects an OIDC token response that includes an accessToken and idToken
the module sends the returned accessToken to Q2's ssoLogin flow to obtain the platform q2token
the module reads username_claim and identifier_claim from the returned idToken
the module keeps the raw idToken for session use, including sign-out

Okta may itself federate to another enterprise identity provider behind the scenes. That is supported as long as the mobile app still authenticates against an Okta OIDC issuer and Okta returns the expected tokens and claims to the SDK.

Inbound SSO Sequence

The following sequence shows the typical iOS InboundSSO runtime flow:

Enabling InboundSSO

There are two parts to enabling InboundSSO on iOS:

ensure the InboundSSO module is available to your DevApp build
configure the module entry in settings.json

1. Verify the Module Is Included

Make sure your DevApp includes the Q2-provided InboundSSO module package and product for your SDK version. If you are starting from a current DevApp template supplied by Q2, this is typically already present and only needs to be enabled in settings.json.

If you need to add or update package wiring manually, follow Using Third-Party SDKs and apply the package, product, and class names supplied for your InboundSSO integration.

For the current iOS InboundSSO module, use:

Git URL: https://code.q2developer.com/Q2Antilles/native/modules/ios/q2-inboundsso-ios.git
Package name: q2-inboundsso-ios
Product name: q2_inboundsso_ios
Class name: Q2InboundSSO
Version: 1.0.13 (or latest from the distribution repo)

2. Configure `settings.json`

Add the InboundSSO module to the modules array in your DevApp settings.json. The module entry requires both package metadata (so the DevApp build system can resolve the dependency) and runtime configuration (so the module knows how to authenticate).

{
  "modules": [
    {
      "name": "Inbound SSO Module",
      "gitUrl": "https://code.q2developer.com/Q2Antilles/native/modules/ios/q2-inboundsso-ios.git",
      "packageName": "q2-inboundsso-ios",
      "productName": "q2_inboundsso_ios",
      "className": "Q2InboundSSO",
      "version": "1.0.13",
      "identifier": "",
      "data": {
        "userSelector": true,
        "ephemeralBrowser": false,
        "username_claim": "{username claim from ID token}",
        "identifier_claim": "{stable identifier claim from ID token}",
        "issuerUrl": "https://{your okta issuer or custom domain}",
        "clientId": "{your mobile client id}",
        "signInRedirectUri": "{your sign-in redirect URI}",
        "signOutRedirectUri": "{your sign-out redirect URI}",
        "scopes": "openid offline_access {your additional scopes}",
        "customSignInOptions": {
          "acr_values": "{your acr_values requirement}"
        }
      },
      "enabled": true
    }
  ]
}

Package Metadata Fields

These fields are used by the DevApp build system to resolve and link the InboundSSO module as a Swift Package dependency. They are not runtime configuration.

Field	Value	Purpose
`name`	`"Inbound SSO Module"`	Display name for the module (used in logs and UI)
`gitUrl`	`"https://code.q2developer.com/Q2Antilles/native/modules/ios/q2-inboundsso-ios.git"`	Git repository URL used by SPM to fetch the xcframework
`packageName`	`"q2-inboundsso-ios"`	SPM package name (matches the distribution repo's `Package.swift` name)
`productName`	`"q2_inboundsso_ios"`	SPM library product name (used in the `import` statement)
`className`	`"Q2InboundSSO"`	Entry point class name (used by `NSClassFromString` at runtime)
`version`	`"1.0.13"`	Version tag to resolve from the distribution repo
`identifier`	`""`	Module identifier (leave empty unless directed otherwise by Q2)
`enabled`	`true`	Set to `true` to activate the module

`data` Configuration Reference

The following table explains only the data node, what each field is used for, and who typically owns or supplies the value during integration.

`data` field	Example	Purpose	Typically provided by
`userSelector`	`true`	Identifies whether the multi-user selector is visible and enabled for the build.	FI requirement, implemented by Q2
`ephemeralBrowser`	`false`	Optional. Use this only if the FI wants to disable the private/ephemeral browser during login with the IdP. If omitted, the default value is `true`. If set to `false`, `signOutRedirectUri` must also be configured or the user will not be able to log off from the IdP. When set to `false`, the IdP session is shared between the mobile app and the default browser (`Safari`). There is no guarantee this will work with Chrome.	FI security/product decision with Q2 guidance
`username_claim`	`{username claim from ID token}`	Claim key from the ID token received during login. Used to extract the username presented on the Q2 login user interface. Note: exclude this field if `userSelector` is set to `false`.	FI identity team / Okta configuration
`identifier_claim`	`{stable identifier claim from ID token}`	Claim key from the ID token received during login. Used to extract the unique user identifier. Note: exclude this field if `userSelector` is set to `false`.	FI identity team / Okta configuration
`issuerUrl`	`https://{your okta issuer or custom domain}`	Okta issuer or Okta custom domain used to initialize the Okta SDK. This can be found in the Okta developer portal under Applications -> Sign On.	FI identity team
`clientId`	`{your mobile client id}`	OAuth/OIDC client ID for the mobile application in Okta. This can be found in the Okta developer portal on the main page of your application.	FI identity team
`signInRedirectUri`	`{your sign-in redirect URI}`	Redirect URI used after successful sign-in. This value must be registered in the IdP portal as a valid sign-in redirect URI for the application. Example: `{URL Scheme}://v2/sso/auth`.	Shared: FI identity team and mobile integrator
`signOutRedirectUri`	`{your sign-out redirect URI}`	Optional. This is needed if the FI wants the iOS app to log out of the IdP when logging out of the Q2 Platform. The value must be registered in the IdP as a valid sign-out redirect URI for the application. Note that this will briefly display a mobile browser during logout so the sign-out flow can complete.	Shared: FI identity team and mobile integrator
`scopes`	`openid profile offline_access`	Optional. OAuth 2.0 concept used to specify the access privileges requested when issuing an access token. If nothing is provided, the default values are `openid profile offline_access`. If the default values do not work, the IdP/FI should provide the correct configuration.	FI identity team with Q2 guidance
`audience`	`{your audience}`	Optional. Target audience used during authentication. This should be provided by the IdP/FI. So far, it has only been necessary when the IdP is Auth0. If not used, remove the `audience` key from the config JSON.	FI identity team
`customSignInOptions.acr_values`	`{your acr_values requirement}`	Extra authorization parameter passed through Okta to influence upstream auth behavior.	FI identity team

Ownership Notes

Q2-owned values are usually the module package metadata, class name, and supported integration shape.
FI identity-team values are usually the Okta issuer, client ID, claims, scopes, and any custom authorization parameters.
Shared values are typically redirect URIs, because they must be registered in both the IdP configuration and the iOS app configuration.

Configuration Properties

InboundSSO configuration lives directly under the module data object and supports the following properties:

userSelector (optional): Identifies whether the multi-user selector is visible and enabled for the build.
ephemeralBrowser (optional): Use this only if the FI wants to disable the private/ephemeral browser during login with the IdP. If omitted, the default value is true. If set to false, signOutRedirectUri must also be configured or the user will not be able to log off from the IdP. When set to false, the IdP session is shared between the mobile app and the default browser (Safari). There is no guarantee this will work with Chrome.
username_claim (optional): Claim key from the ID token received during login. Used to extract the username presented on the Q2 login user interface. Exclude this field if userSelector is set to false.
identifier_claim (optional): Claim key from the ID token received during login. Used to extract the unique user identifier. Exclude this field if userSelector is set to false.
issuerUrl (required): Okta issuer URL or Okta custom-domain issuer used by the FI. This module initializes the Okta SDK directly from this value. It can be found in the Okta developer portal under Applications -> Sign On.
clientId (required): Client ID registered for your mobile application. It can be found in the Okta developer portal on the main page of your application.
signInRedirectUri (required): Redirect URI used after the sign-in flow completes. This value must be registered in the IdP portal as a valid sign-in redirect URI for the application. Example: {URL Scheme}://v2/sso/auth.
signOutRedirectUri (optional): Needed if the FI wants the iOS app to log out of the IdP when logging out of the Q2 Platform. This value must be registered in the IdP as a valid sign-out redirect URI for the application. Note that this will briefly display a mobile browser during logout so the sign-out flow can complete.
scopes (optional): OAuth 2.0 concept used to specify the access privileges requested when issuing an access token. If nothing is provided, the default values are openid profile offline_access. If the default values do not work, the IdP/FI should provide the correct configuration.
audience (optional): Target audience used during authentication. This should be provided by the IdP/FI. So far, it has only been necessary when the IdP is Auth0. If not used, remove the audience key from the config JSON.
customSignInOptions (optional): Additional authorization request parameters, such as acr_values.

note

This module currently reads user identity from the OIDC idToken, not from a separate userinfo call. That means the configured username_claim and identifier_claim must be present in the returned ID token.

Validation Checklist

Before testing, verify the following:

the InboundSSO module entry exists in settings.json
"enabled": true is set on the module entry
signInRedirectUri and signOutRedirectUri match the identity-provider configuration
issuerUrl and clientId match the FI's identity-provider configuration

Authentication Architecture​

Inbound SSO Sequence​

Enabling InboundSSO​

1. Verify the Module Is Included​

2. Configure settings.json​

Package Metadata Fields​

data Configuration Reference​

Ownership Notes​

Configuration Properties​

Validation Checklist​

Related Documentation​