Basic application integration

Overview

This document describes how to achieve the simplest form of integration of an Application with Chemaxon Cloud: single sign-on (SSO).

A successful integration consists of 2 main parts:

• Application implements the required code changes
• Application is registered in Chemaxon Cloud

Chemaxon Cloud uses Okta for IAM (Identity and Access Management).

Chemaxon Cloud uses the OpenID Connect (OIDC) protocol to handle both authentication and authorization.

High level overview

1. Application is prepared for integration with Chemaxon Cloud
   • Application MUST be ready to use Okta via OIDC for authentication and authorization
   • Application MAY want to use metadata included in the ID and access tokens obtained via OIDC, to make authorization decisions
   • Application MUST provide app-info metadata endpoint to be consumed by Chemaxon Cloud
2. Application is registered under a Team in Chemaxon Cloud
   • Requires the app-info metadata provided by Application to be accessible

Integration results

1. SSO is functional across Chemaxon Cloud and Application
2. Token metadata can be used to make authorization decisions in Application

Detailed overview

To better understand what we want to achieve, we should expand the above steps a bit more:

1. Chemaxon Cloud System Administrator pre-registers application under a Team in Chemaxon Cloud
2. Chemaxon Cloud System Administrator sends client_id and client_secret to application development team
3. Application development team implements/configures integration with the Okta OAuth Authorization Server used by Chemaxon Cloud
4. Application exposes app-info endpoint
5. Application is deployed with correct Okta integration and app-info endpoint
6. Application development team sends the URI for the application app-info endpoint to Chemaxon Cloud System Administrator
7. Chemaxon Cloud System Administrator configures the pre-registered application in Chemaxon Cloud with the app-info endpoint URI received from application development team
8. Chemaxon Cloud System Administrator triggers fetching of Application metadata from app-info endpoint
9. Chemaxon Cloud System Administrator finishes application registration
10. Application can be accessed by members of the Chemaxon Cloud Team under which the Application was registered

Architecture

Obtaining app-info

Login / logout

Step-by-step instructions

1. Application is prepared for basic integration with Chemaxon Cloud

Prerequisites

Important Chemaxon Cloud URIs

Name	URI
Chemaxon Cloud base URI	https://cloud.chemaxon.com/
Okta OAuth Authorization Server URI	https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417
Okta OAuth Authorization Server Metadata URI	https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/.well-known/oauth-authorization-server

Implementing Okta OIDC integration

To provide a consistent login User Experience and SSO capability, Chemaxon Cloud relies on the "Okta redirect authentication model".

Chemaxon Cloud only supports integrating: server-side web applications; SPAs that rely on their own backend for handling authentication.

Chemaxon Cloud currently does NOT support integrating: SPAs where authentication would be handled by client side code directly interacting with Okta.

Exact implementation depends on the technologies used by the Application. Please refer to the appropriate documentation in Okta:

• Overview: Integrate authentication into your app
• Implementation guide: Sign users in to your web app using the redirect model
  • Make sure to select the appropriate language/technology in the "Instructions for" dropdown
  • The following sections are not relevant, those are handled by Chemaxon Cloud:
    • Set up Okta
    • Create an Okta integration for your app
  • The following sections are important:
    • Create app
    • Configure required authentication
• Okta SDKs
• Language specific sample projects for inspiration:
  • https://github.com/okta/samples-java-spring/tree/master/okta-hosted-login
  • https://github.com/okta/samples-nodejs-express-4/tree/master/okta-hosted-login

Configuration examples

Spring Boot

Example of Oauth Client configuration - token, authorization, and JWKS URI:

security.oauth2:
  client:
    clientId: <yourClientID - obtain from Chemaxon>
    clientSecret: <yourClientSecret - obtain from Chemaxon>
    accessTokenUri: https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/token
    userAuthorizationUri: https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/authorize
    scope:
      - openid
      - profile
      - email
      - offline_access
  resource:
    jwk.key-set-uri: https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/keys

Node Express

Example of passport-openidconnect configuration:

{
  "issuer": "https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417",
  "authorizationURL": "https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/authorize",
  "tokenURL": "https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/token",
  "userInfoURL": "https://auth.cloud.chemaxon.com/oauth2/aus3qkblpwzIDQBJF417/v1/userinfo",
  "clientID": "${yourClientID - obtain from Chemaxon}",
  "clientSecret": "${yourClientSecret - obtain from Chemaxon}",
  "callbackURL": "http://localhost:3000/authorization-code/callback",
  "scope": "openid profile email offline_access"
}

The offline_access scope is optional, and results in a refresh token being issued by Okta.

Implementing authorization logic based on token metadata

For details about custom claims included in Okta tokens, and about the scopes required for them to be included, please refer to Custom Claims in Okta tokens.

Certain scopes are required for these custom claims to be included in the tokens, please make sure to request the appropriate scopes.

Based on these custom claims, your application should be able to make access control and authorization decisions, as needed.

Implementing the app-info endpoint

The response of the endpoint should adhere to the specification according to sf-001-application-info.

Two features are especially important to include in the response: synergy/login and synergy/logout.

• synergy/login - Callback URL to add to the "Sign-in redirect URIs" allowlist in Okta
• synergy/logout - Callback URL to add to the "Sign-out redirect URIs" allowlist in Okta

These are necessary to ensure that the required configuration changes in Okta can be made by Chemaxon Cloud, so that Login/Logout initiated in the Application works.

Sign-in redirect URI: The sign-in redirect URI is where Okta sends the authentication response and ID token for the sign-in request. (The URI must be absolute URI.)

Sign-out redirect URI: After your application contacts Okta to close the user session, Okta redirects the user to this URI. (The URI must be absolute URI.)

Source: Okta Help Center / Create OIDC app integrations / Task 2: Configure initial settings

Example request/response

GET https://example-application.com/api/app-info

{
  "displayName": "Example Chemaxon Cloud app",
  "address": "https://example-application.com/",
  "identities": [{ "category": "application", "type": "web" }],
  "features": [
    {
      "namespace": "synergy/health",
      "attributes": {
        "url": "https://example-application.com/api/health"
      }
    },
    {
      "namespace": "synergy/icon",
      "attributes": {
        "url": "https://example-application.com/app-icon.svg"
      }
    },
    {
      "namespace": "synergy/login",
      "attributes": {
        "url": "https://example-application.com/authorization-code/callback"
      }
    },
    {
      "namespace": "synergy/logout",
      "attributes": {
        "url": "https://example-application.com/logout"
      }
    }
  ]
}

2. Application is registered under a Team in Chemaxon Cloud

Prerequisites

• Application development team provides app-info endpoint URI to Chemaxon Cloud System Administrator.

Application registration

Please refer to System Administrator guide on Registering Applications.