Mobile application configuration
(Mobile) Applications, typically using the Onegini SDK to communicate with an Onegini Token Server instance, need to be configured via the admin console. This section describes the steps related to configuration of these applications.
Creating a new application
In order to create a new application, go to OAuth section of the administration console and click Applications or Web Clients tab (depending what kind of application you want to create).
On the overview that is shown you can see all the existing applications.
Note:
- Web clients are meant for web servers or resource gateways. In this case you or a trusted party is managing the hardware on which this application runs. We also reference these as static OAuth clients.
- Applications are meant for mobile applications that are installed on a device that is not managed by you or a trusted party. In general this are your customers' mobile devices. These can be exposed to all kinds of attacks and the application configuration combined with the Onegini SDK provides the necessary protection against that. These clients are also named dynamic clients.
To add a new application click on the plus icon on the left. The following form will appear:
Fill all the mandatory fields (marked with * on the form). The other fields are optional.
| Field | Required | Example value | Details |
|---|---|---|---|
| Identifier | yes | app1 | Unique identifier for this application. |
| Name | yes | My demo application | Display name of this application. This is only used for informational purposes in the Admin console and end-user API. |
| Allowed functions | yes | AUTHORIZATION_CODE | Supported OAuth functions for this client. A common application has AUTHORIZATION_CODE and REFRESH_TOKEN as allowed functions. Please the following table for a description of the available allowed functions. |
| Redirect URL | yes | URI to which the end-user is redirected after successful authorization. In case of a mobile application this URI starts with the custom app scheme (e.g. myapp://) In case of a web client this is the full URI to which the end-user is redirected after he has successfully logged in and given authorization for the requested scopes. | |
| Access grant validity | yes | 300 | Number of seconds an access grant is valid. This is the time an application has to exchange an authorization grant (a.k.a access grant) for an access token. In a common scenario this is done in at most a couple of seconds. |
| Access token validity | yes | 3600 | Number of seconds an access token is valid. An access token is the temporary key with which an application can fetch resources. When this period has expired the access token has to be refreshed using a refresh token. |
| Resource gateway | no | A mobile app typically uses a resource gateway to fetch data from backend services. Here you can specify the resource gateway which this application will be talking to. A web client with VALIDATE_ACCESS_TOKEN as allowed function is considered a resource gateway. |
|
| Default scopes | no | The scopes that are assigned to an authorization request if no scopes are requested. If no scopes are requested by the application in the authorization request and no defaults specified the Token Server will fail the request. | |
| Additional scopes | no | The scopes the application is allowed to request apart from the default scopes. The default scopes are also counted as scopes that can be requested by an application. | |
| Identity provider | no | myIdp | The identity provider used when a user authenticates for this application. See the Identity Provider configuration topic for more information on Identity Providers. |
| Additional Authenticator | no | SMS CHALLENGE | Additionally to the primary identity provider selected above an additional authenticator can be enforced. |
| FIDO enabled | no | Flag to enable FIDO authentication for this application. | |
| FIDO authenticators | no | Configures which FIDO authenticators are allowed for this application. Required if FIDO is enabled for this application. | |
| Max PIN attempts | yes | 3 | Max number of times a user can provide a valid PIN before the application is revoked and the user has to authorize the app again. When the value is set to 0 the number of attempts is unlimited. |
| PIN policy | no | my PIN policy | PIN policy that will be used by the mobile application during the PIN creation process. Please see the PIN policy topic |
| Development mode | no | false | When the development mode is selected the configured application signature is ignored and the developer does not have to configure a new application signature for every new version of the application. To learn more about the application signature check out the Application version management topic. |
| Certificates | no | Certificates that are used by the App to establish a secure connection with the Onegini Token Server and other backend systems. The selected Certificates will be part of the configuration file that you can export for your Application. | |
| Logo URI | no | URI of the logo for this application, it can be used in for example the consent screen. | |
| Template prefix | no | payment-app/ | Every application can have it's own branding. Therefore multiple sets of templates are supported. The prefix corresponds to the directory in which a set of templates is stored. |
| Skip Consent page | no | true | In the OAuth flow consent is requested because an application requests access to the user's data. When the application is managed by a third party you may want to notify the user that this application will have access to his personal information. Which information an application has access to is defined by the requested scopes. When consent is disabled the user is not required to give consent for the application during the authorization process. |
| Skip Authorization complete page | no | In a mobile device browser it is needed to show a page that the authorization is completed because the user is redirected back to the mobile application in this scenario. This page makes sure that the user is displayed with a nice page that displays that authentication is finished and he can close this page. When the application uses an in app browser this page is not required and it can be disabled. |
Additional information about configuration of a Pin policy, a Resource gateway, Scopes and an Identity provider can be found in separate chapters.
Description of allowed functions
| Function | Description |
|---|---|
| AUTHORIZATION_CODE | Specifies whether an application (or OAuth client) can use the OAuth authorization code grant type in order to allow this application to request an access token on behalf of the end-user. |
| IMPLICIT | Alternatively to the AUTHORIZATION_CODE function which corresponds to the authorization code grant type the IMPLICIT function corresponds with the implicit OAuth grant type. Use this grant type with caution as the access token is directly returned to the browser of the end-user in the redirect upon successful authorization. |
| CLIENT_CREDENTIALS | Specifies whether an application can use it's client credentials to request an access token. Note that this access token is not linked to a user since it's solely requested by the application without any user interaction. This function is typically used for machine-to-machine communication. |
| REFRESH_TOKEN | If this function is enabled for an application a refresh token will be issued in case of the authorization code grant type is used. This refresh token can be used by the application to issue a new access token. |
| FINGERPRINT | This is a special function to enable fingerprint authentication for an application. If this function is removed from an application all registered applications cannot use fingerprint authentication anymore instantaneously. |
| VALIDATE_ACCESS_TOKEN | Another special function. This allows an OAuth client to validate an access token and get additional information about it. This function is specifically reserved for resource gateways. See also the topic on configuration of a resource gateway |
Removing an application
In order to remove an application, go to OAuth section of the administration console. On the list of applications find the one you want to remove and click on the trash icon on the right (You will be asked to confirm you decision). Please note that you cannot remove an application that is already in use. In use means there are already registered clients using this application. An alternative could be to disable all application versions so the application can not be used anymore.
Development mode
Each and every application communicating with the Token Server must identify itself. The application needs to tell the Token Server its version, platform and the application identifier. Based on this input the application is challenged to proof his identity. An application can proof its identity by using a shared application signature which is known on both the server and client side. This secret is different for each application, platform and version combination. The Onegini SDK is responsible for providing this secret since it's depending on the application itself. Hence, the secret is different for each build of the application and can change frequently during development. This is very secure, however it is not very convenient for app developers who need to register a new application signature for the specific application version they are using before they can start testing their app again. To prevent slowing down the development process, an application can be put in development mode. By enabling the development mode, an application no longer has to prove its identity.
Note: Payload encryption also requires an identified app but can not be bypassed by enabling development mode.
Enabling development mode
Development mode must never be enabled in a production environment. To prevent accidentally enabling the feature, two actions are required to enable it. First of all the development mode should be enabled in the technical configuration using a Docker Compose environment variable.
When the development mode is enabled in the technical configuration it can also be enabled in the functional configuration using the admin console. You can specify per
application if development mode must be enabled for this application. In the application overview
applications using the development mode are marked with a warning icon, indicating the development mode is enabled.
In the screenshot below you can see that the TestClient application is running in development mode.
Warning: Enabling development mode in production can severely reduce the security of the Mobile Security Platform. This features is only for convenience on development or test environments. Hence, development mode is turned off by default.
