Setting up OAuth 2.0 for Private Cloud

Prerequisites
Setting up OAuth
Example configurations
Logging in with OAuth
Troubleshooting

Applies to AnyLogic Cloud 2.5.1. Last modified on January 14, 2025.

By integrating Private Cloud Pro or Enterprise with an identity provider service, you can use that service as a source of Cloud user data.

The OAuth integration has been tested for the following providers: Microsoft Entra ID, OKTA, Ping One, KeyCloak, Google. Potentially, any OAuth 2.0 and OpenID Connect compatible identity provider can be used.

Prerequisites

Your Private Cloud instance should be configured to use the HTTPS protocol.
To use OAuth integration, user account data should include the field containing their email.
At a minimum, the identity provider should return the following data fields (or their analogues):
client-id
client-secret
scope
secret-uri

Setting up OAuth

To set up OAuth for your instance, you must set up the application in the console of your identity provider and then manually edit Private Cloud configuration files, registration.json and oauth.json.

Go to the website of your identity provider. The examples below use settings required for the PingOne service. Other providers may require additional information.
Create a new integration for your Private Cloud application.
The specific settings and their values vary by provider. For instance, the following is required when configuring the PingOne integration:
Response type: Code only
Grant type: Authorization Code
PKCE Enforcement: Optional
When setting up the Redirect URL, use the following pattern:
https://<Private Cloud instance address>/api/oauth/<registration ID>
The registration ID is a variable that you should manually name and enter this name in the configuration of the identity provider. For example, if you use ping as the registration ID, the resulting URL will be https://<Private Cloud instance address>/api/oauth/ping.
To let the identity provider provide the necessary credentials for Private Cloud users, enable the email and profile scopes.
Go to the /home/alcadm/alc/controller/conf directory on the machine that serves the controller component.
Open the registration.json file.
Modify the value of the enterprise field in the providers object by adding the necessary providers:
- anylogic — enables user management functionality of AnyLogic Cloud.
- ldap — enables the authentication via the LDAP server associated with the Private Cloud instance; the server should be specified in ldap.json.
- ad — enables the authentication via the Active Directory server associated with the Private Cloud instance; the server should be specified in ad.json.
- oauth — enables the authentication via the OAuth 2 compliant identity provider. The settings must be specified in oauth.json.
The order in which the providers are listed is important! The instance will first to identify the user in the first provider listed and then moves on to the next.
Consider the following example configurations:
Regular (AnyLogic Cloud only)
```
{
  "enabled" : true,
  "enableGuestAccess" : true,
  "providers": {
    "enterprise": "anylogic"
  }
}
```
Enables the built-in authentication functionality only. Users should sign up and log in via Cloud forms.
AnyLogic Cloud + LDAP
```
{
  "enabled" : true,
  "enableGuestAccess" : true,
  "providers": {
    "enterprise": "anylogic, ldap"
  }
}
```
Upon an authentication attempt, Cloud will first try to authorize the user by comparing their credentials against the records in its internal database. If the user is not found (or marked as a previously logged-in LDAP user), the instance will establish a connection to the LDAP server and try to locate them there.
AnyLogic Cloud + OAuth
```
{
  "enabled" : true,
  "enableGuestAccess" : true,
  "providers": {
    "enterprise": "anylogic, oauth"
  }
}
```
When authentication is attempted, AnyLogic Cloud first attempts to authorize the user by comparing their credentials against the records in its internal database. If the user is not found (or is marked as a previously logged in user authenticated by the OAuth 2-compliant provider), the instance will connect to the OAuth server and attempt to locate the user there.
AnyLogic Cloud + AD
```
{
  "enabled" : true,
  "enableGuestAccess" : false,
  "providers": {
    "enterprise": "anylogic, ad"
  }
}
```
Upon an authentication attempt, Cloud will first try to authorize the user by comparing their credentials against the records in its internal database. If the user is not found (or marked as a previously logged-in Active Directory user), the instance will establish a connection to the Active Directory server and try to locate them there.
The enableGuestAccess option defines whether the unauthorized users will be able to view public models. If false, this feature is disabled.
OAuth + AD
```
{
  "enabled" : false,
  "enableGuestAccess" : false,
  "providers": {
    "enterprise": "oauth, ad"
  }
}
```
With this configuration, AnyLogic Cloud does not try to find the user in its internal database, but instead does a lookup in the OAuth 2-compliant provider’s database. If the user is not found there, the lookup is performed in the Active Directory database instead. If the value of the enabled option is set as above, users will not be able to use the signup and login to create profiles and authenticate. If a user exists in both an OAuth-compliant provider and Active Directory databases, no additional account is created. Instead, AnyLogic Cloud associates both login methods with a single user account. This behavior is ensured by verifying the email address against the existing user list in the database.
The enableGuestAccess option defines whether unauthorized users can view public models. If false, this feature is disabled.
LDAP only
```
{
  "enabled" : false,
  "enableGuestAccess" : false,
  "providers": {
    "enterprise": "ldap"
  }
}
```
With this configuration, Cloud won’t try to locate the user in its internal database and will perform a lookup in the LDAP database immediately instead.
With the value of the enabled option set as above, users can’t use the signup and login forms to create profiles and authenticate.
The enableGuestAccess option defines whether the unauthorized users will be able to view public models. If false, this feature is disabled.
AD only
```
{
  "enabled" : false,
  "enableGuestAccess" : false,
  "rootDn": "dc=example,dc=com",
  "providers": {
    "enterprise": "ad"
  }
}
```
With this configuration, Cloud will not attempt to locate the user in its internal database, but will immediately look up the user in the AD database.
If the value of the enabled option is set as above, users will not use the signup and login forms to create profiles and authenticate.
The enableGuestAccess option determines whether the unauthorized users will be able to view public models. If set to false, this feature is disabled.
The rootDn option in this configuration specifies the root distinguished name. You must use it in the rare case that the authenticating user’s username contains a domain name that is different from the Active Directory server’s domain name.
Save the registration.json file and close it.
Open the oauth.json file.
Specify the settings of your OAuth configuration. The specific list of fields depends on the provider. See the Spring documentation for a reference on all available fields.
See the example configurations below.
To apply changes you have made in JSON files, stop the controller and rest components by executing the following command in the Linux terminal on the machine that serves this component:
sudo docker stop controller rest
After that, start the controller component manually:
sudo docker start controller

After that, your users should be able to log in to the Private Cloud instance using their credentials from the OAuth provider.

Example configurations

This section lists example configurations for several single sign-on providers.

Microsoft Entra ID

{
    "oauthProviders": [
        {
            "registrationId": "entraid", // The user-defined name which is used in redirect-uri
            "name": "MS Entra ID", 
            "providerConfiguration": {
                "issuer-uri": "https://login.microsoftonline.com/<tenant ID>/v2.0"
            },
            "registrationConfiguration": {
                "client-id": "<Client ID>",
                "client-secret": "<Client secret>",
                "scope": [
                    "User.Read" // The list of scopes depends on the identity provider
                ],
                "redirect-uri": "https://<AnyLogic Cloud host name>/api/oauth/entraid"
            }
        }
    ],
    "oauthAttributes": {
        "email": "email",
        "name": "name"
    }
}

Google

{
    "oauthProviders": [
        {
            "registrationId": "google", // The user-defined name which is used in redirect-uri
            "name": "Google",
            "providerConfiguration": {},
            "registrationConfiguration": {
                 "client-id": "<client-id>",
                "client-secret": "<client-id>", 
                "scope": [
                    "openid", "profile", "email" // The list of scopes depends on the identity provider
                ],
                "redirect-uri": "https://<cloud_hostname>/api/oauth/google"
            }
        }
    ],
    "oauthAttributes": {
        "email": "email",
        "name": "name"
    }
}

PingOne

{
    "oauthProviders": [
        {
                "registrationId": "ping",// The registration ID part of the redirect URI you set in the provider console
            "name": "Ping Cloud",
            "providerConfiguration": { // The identity provider mapping
                "authorization-uri": "https://auth.pingone.eu/{yourInternalId}/as/authorize", 
                "issuer-uri": "https://auth.pingone.eu/{yourInternalId}/as",
                "token-uri": "https://auth.pingone.eu/{yourInternalId}/as/token",
                "user-info-uri": "https://auth.pingone.eu/{yourInternalId}/as/userinfo",
                "jwk-set-uri": "https://auth.pingone.eu/{yourInternalId}/as/jwks"
            },
            "registrationConfiguration": {
                "authorization-grant-type": "authorization_code",
                "client-id": "{yourClientId}",// Your identity provider client ID
                "client-secret": "{yourClientSecret}", // Your identity provider client secret 
                "redirect-uri":"https://test.anylogic.run/api/oauth/ping", // The full redirect URI 
                "scope": [
                    "openid", "profile", "email" // The list of scopes depends on the identity provider
                ]
            }
        }
    ],
    "oauthAttributes": {
        "email": "email",
        "name": "name"
    }
}

Okta

{
    "oauthProviders": [
        {
            "registrationId": "okta", // The user-defined name which is used in redirect-uri
            "name": "Okta",
            "providerConfiguration": {
               "issuer-uri": "https://example.okta.com/oauth2/default"
              },
            "registrationConfiguration": {
                 "authorization-grant-type": "authorization_code",
                 "client-id": "{yourClientId}",
                "client-secret": "{yourClientSecret}", 
                "scope": [
                    "profile", "email" // The list of scopes depends on the identity provider
                ],
                "redirect-uri": "https://<AnyLogic Cloud host name>/api/oauth/okta"
            }
        }
    ],
    "oauthAttributes": {
        "email": "email",
        "name": "name"
    }
}

Logging in with OAuth

Open the instance login page in your browser.
Click Use single sign-on.
Enter the credentials for your identity provider account.
To switch the password’s visibility during input on or off, click Show or Hide on the edit box’s right.
Click Login.

Troubleshooting

If a user logs in with the same email address using both an OAuth-compliant provider and LDAP, no additional account is created. Instead, AnyLogic Cloud associates both login methods with a single user account. This behavior is ensured by verifying the email address against the existing list of users in the database.

In case of authentication errors, consult the rest service component logs and the browser console for any relevant details. Additionally, check the identity provider error code.

How can we improve this article?