Below are the instructions for connecting an SSO authentication service to the Chemwatch mobile application: Your IDP service must support the OAuth 2.0 PKCE or OIDC protocol for authentication and authorisation.
For integration with your service, we need the following information:
clientId (sometimes called client credentials).
clientSecret (if you are using an IDP that requires the use of a client secret).
authorizeUrl.
accessTokenUrl.
userInfoUrl.
Add our redirect URL: net.chemwatch.walkabout://oauth2redirect
You can also specify the scope that should be available for getting information about the user and select the exact field representing the username.
If you have guest user credentials — please provide us with temporary access to test it, this may speed up SSO setup process.
Listed below are some tips for existing IDPs outlining the steps needed to be done on that specific platform. Please keep in mind that if you are using a custom IDP and it requires certain actions beyond the standard OAuth2.0 protocol, you will need to provide the complete data yourself.
Currently our application is configured to work primarily with OAuth2.0 PKCE and also has OIDC support.
Specific to MS Azure (Microsoft Entra ID)
1. When registering the Smarter Suite app in Azure, the optional redirect field must be selected as a public client/native(mobile & desktop) app for mobile apps. Mobile apps have a different redirect URL structure and always start with customScheme.://. It needs to be exactly net.chemwatch.walkabout://oauth2redirect Otherwise, the mobile app won't work with your AzureAD client. Please see the below image for the reference.
2. If you didn’t specify the redirect URL when registering the app as above, please add the net.chemwatch.walkabout://oauth2redirect URL to the AzureAD console as an allowed redirect, or else our app will fail the AzureAD security check on login. This can be done in the "Authentication" section which should be second from the top under the “Manage” menu in the left pane.
On the "Authentication" screen, please add the mobile and desktop apps category (1). After that, it will be possible to add net.chemwatch.walkabout://oauth2redirect as a redirect URL here (2). It is extremely important to add the correct redirect URL otherwise the Smarter Suite app will not be able to receive a response from your IDP.
3. In the “API permissions”, you need to add "email" from Microsoft Graph (delegated permissions) because we use the user's email address for authentication purposes. Please see the below image for your reference. If you would like to use OIDC instead of Oauth2.0 PKCE — you must also add the openid from the same graph section.
4. Please take a look at the screenshot below. We marked several zones with numbers so you can understand where to get the relevant data.
authorization URL — number 1
accessToken URL — number 2
userInfo URL — number 3
For OIDC users only — please let us know the following endpoint: OpenID Connect metadata document.
Specific to Google Workspace
Please provide us with the following.
Google IDP requires that two different OAuth 2.0 client IDs be created for each of the platforms: Android and iOS. Google mobile clients do not have clientSecret and work differently. You need to create two clients: one for Android and another for iOS. This can be done in the "Credentials" section of "API & Services" (in GCP). Each of the clients has some properties that need to be filled in with the specified data.
Android client
Name — can be filled with any data
package name — net.chemwatch.walkabout
SHA-1 certificate fingerprint — 7F:49:D2:02:9B:A8:6D:54:24:C1:F7:01:83:5C:EF:3F:3B:21:B6:A4
iOS client
Name — can be filled with any data
bundle id — net.chemwatch.walkabout
app store id — 1547225480
team id — AD5M8U9NQL
The above is a very important step because Google has strict limits and each client is only eligible for one mobile app and mobile platform at a time.
After two clients are successfully created, please provide us with the below info from each of the clients separately. This data can be downloaded as a text file directly from the client's window in the GCP console (there is a special button for this called "download plist" for iOS and "download json" for Android). These files will contain info such as client_id, auth_uri, token_uri, reverse identifier ( for iOS), etc. We need this to set up our app to communicate with these specific clients.
In any case, we need the client id, auth uri, token uri from each of the clients, and the reverse client id from the iOS client. Please keep in mind that the client ID cannot be the same for different clients, each one will have a unique value.
Specific to Okta
If you don't have the mobile client set up in Okta IDP, please follow steps 1-5 to create it. Please note that the Okta web client is not suitable for mobile apps, they require the native client.
Create a native client for the Smarter Suite mobile application in the Okta console with the following parameters:
Create a new app => OIDC => Native app
Login redirect URI => net.chemwatch.walkabout://oauth2redirect
Controlled access => one of two options has to be selected ("Allow access to everyone in your organization" or "Restrict access to selected groups" if such exist)
Once the client is created, as an additional check, verify that the new client is configured to work with PKCE. This should be enabled by default and can be checked in the "client credentials" of the "General" section. PKCE must be enabled!
If you decide to additionally request a client secret, this can be set up on the same page. "Public Key/Private Key" is not allowed, only "None" or "Client Secret" can be selected.
In the end, We need the following data from Okta for mobile SSO:
6.1 Client ID: This can be found in the "General" section of the native Okta client.
6.2 Okta Issuer (can be found in the "Sign On" section, should be in the following format: "https://xxx-1234567.okta.com")
6.2.1 It's important to ensure that the client ID on the General tab matches the "Audience" token in the Sign On section. A parameter mismatch indicates an error while creating the client.
6.3. If you opted to use the client secret — the client secret from the "General" tab
6.4. Last but not least, the custom API URL of the authorisation server (if applicable). It can be found by navigating to Security => API. By default, it looks similar to https://xxx-12345.okta.com/oauth2/default, but if it’s different, we need this information as well.
Please let us know if you have any issues with providing the data for points 6.1-6.4.
FINAL STEP: Chemwatch Web App Configuration for Smarter Suite Users
You need to open the Chemwatch web application and log in as an administrator (product owner) to your domain account. This would be your main domain where you can edit permissions/privileges for other users.
Go to "Settings" (upper left corner of the web screen), after that click on "User Access" and select "Users".
Find your new domain, which name should match what you see in the mobile app client in the side menu after your domain name.
Click on that user and select the appropriate privileges, products, or roles for that user.
After that, please log out of the mobile app, and log in again. From now on you should be able to see all modes available for this user.
Please refer to the below image if you are not sure where to find these options in Chemwatch.
