Skip to content

Management Console integration with Okta

Feature availability

Supported in: Resilio Active Everywhere 4.2 Supported for: OpenID standard (SAML is not supported)

Set up Okta applications and API endpoints

Groups and Users

User authorization in MC is based on group claims, which are used to manage roles.

Set up groups in Okta with names matching the MC roles:

  • Super Administrator
  • Administrator
  • View Only
  • Custom user group (this is a custom group with some custom name)

Assign these groups to the users. Technically a single user can be assigned to an application individually, but this is not supported by MC - Management Console will reject users who are not part of a user group.

Create an application in your Okta account.

Mc Okta 1

If you plan to use authorization for Users on MC , select "OIDC - OpenID Connect Application".
If authorization is only for APIs , choose "API Services". Mc Okta 2

User authorization: OpenID Connect Application configuration

The "Refresh Token" option must be selected.
Mc Okta 3

It is crucial to configure the "Sign-in redirect URI" correctly. The URI must match the one specified in the MC Advanced settings, or the IP address of your device: https://address:8443/login/okta/redirect. Wrong URI will give error 400 Bad request on attempt to login.

If you are not ready to configure group access, you can select "Skip group assignment". Click Save.

Mc Okta 4

Select "Require PKCE as additional verification" and "Rotate token after every use" for enhanced security.

Mc Okta 5

API integration: API Services

Select it, if authorization is required only for API. Give it a name.

Mc Okta 6

Disable “Require Demonstrating Proof of Possession (DPoP) header in token requests” for the newly created application if you don’t want to use it.

Mc Okta 7

Review the saved application.

Mc Okta 8

Assign previously created groups to your application(s). Once the groups are assigned, users within those groups will be able to sign into MC and automatically assume the corresponding roles.

Mc Okta 9

Authorization server

An Authorization Server in Okta is essential for managing secure access to APIs, applications, and resources by issuing and validating tokens. It serves as the backbone for implementing OAuth 2.0 and OpenID Connect (OIDC) flows, which allow your apps and services to authenticate users and authorize access in a standardized, secure way.
Go to Security -> API and click “Add Authorization Server”. Give it a name. Be sure “Audience” is configured correctly. Audience is a parameter used to specify the intended recipient of an access token. It plays a critical role in ensuring that tokens are only used by the appropriate API. MC will check the audience to be equal to MC address (as configured via advanced settings), or the IP address of your device: https://address:8443

Mc Okta 10

Mc Okta 11

Review the created Authorization server and note the authorization server ID in the Metadata URI. It will be needed later for connection configuration in the Management Console

Next, proceed to configure Scopes, Claims, and Access policy rules to include roles (user group information) in the ID and Access tokens.

Scopes

Scope defines the level and type of access a user is requesting from the server. Scopes are critical components in OAuth 2.0 authorization flows, as they specify what actions or data the user is permitted to access on behalf of the user.

For user authoriztion on MC - required scopes are “user_groups”, “openid”, “profile”, “offline_access”, “email”. Click "Add Scope" to add the missing ones.
For granting access to MC API , create scopes with pattern api::<role>, they will be needed later. The "role" should match the user group configured on the MC side (snake_case). In our example that might be the following, depending on the access level you're planning to grant
api::super_administrator
api::administrator
api::view_only
api::<custom_group>

Danger

Do not change the names of the scopes! MC will request sсopes “user_groups”, “openid”, “profile”, “offline_access”, “email” and Okta will throw an error if at least one of the scopes is unknown.

Mc Okta 12

Claims

Claim is a key-value pair included in a token (like an ID token or access token) that conveys specific information about the user or the authorization context. Claims are used to pass details to applications and APIs, which can then make authorization decisions based on this information.

Create Claim “roles”.
Include in token type - "ID token" and Always.
Value type - Groups. The filter is optional and is added here to demonstrate the possibility of customization. Matches regex: <enumerate your groups here>.
Include in scope “user_groups".

Mc Okta 13

Review the saved Claims

Mc Okta 14

Access Policies

By default the policies list is empty and users will not be allowed to connect to this server. Policy is a set of rules that define the conditions and requirements for issuing tokens to API clients or users. Policies allow you to customize and control how tokens are granted based on specific criteria.

Click to add a new Access policy.

Note

You will need separate access policies for user authentication and for access to API, and additionally a separate policy for different levels of access to API.

User authentication access policy

Create access policy for user authentication : assign it to OpenID application created earlier.
Mc Okta 15

In the Policy click to add a rule “Configuration for authorization code flow”.

Name “Allow tokens access by authorization code flow".
Select "Authorization Code"
Include “user_groups”, “openid”, “profile”, “email”, “offline_access” scopes. It is not necessary to list all the allowed scopes individually. You can simply use the "OIDC default scopes" function, but "user_groups" must be configured as the default scope. In this example, all necessary scopes for console integration are intentionally listed for clarity.

Mc Okta 16

API access policy

Note

This flow requires to have a separate access policy for different access levels.

Create access policy for API access for API integration application created earlier. For example, this policy will provide View-Only access to MC API.

Mc Okta 17

Create a new rule

Mc Okta 18

Create a new rule for your Access Policy, give it some comprehensive name.
Select "Client Credentials" only.
In this example, API client with view only type of access to the Management Console API in this scopes configuration
Include all the custom scopes in this rule based on the pattern "api::<role>" created earlier.

Note. If you want to grant an additional client “view only” access to the API then you can just add the client to this created access policy “Resilio MC API (View Only)”.

You can verify your setup using Okta's tools (“Token preview” tab).

User authentication

Ensure that the token contains the "roles" claim for the authorization code grant type. If you need to check the id_token payload, you must include the "openid" scope in your test. At least one scope must be included in the request.

Mc Okta 19

API Integration

The "scp" attribute must be included in your token and should contain all the requested scopes, formatted with the application name and the supported role.

Mc Okta 20

In our example, Admin access for view only client should not be granted:

Mc Okta 21

Configure MC connection to Okta

To configure connection to your Okta authentication server:

  1. In the Resilio Management Console, select Settings > General.
  2. In the OKTA AUTHENTICATION section, click Configure.

  3. Provide your Okta authentication service configuration parameters:

    • Organization domain - Your organization's Okta domain.
    • Authorization Server ID - Authorization server's identifier which can be extracted from its metadata URI.
      Example : https://{yourOktaDomain}/oauth2/**{authorizationServerId}** /.well-known/oath-authorization-server

  4. (Optional) Select Enable authentication for API to enable API authorization.
    Note: To enable authentication for API, you must create API Services Integration application and a bearer token, or you must select Client Credentials option in the General Settings when creating your OIDC - OpenID Connect Web Application.

  5. Select Enable authentication for Users , then provide:

    • Client ID - Your OpenID application's identifier.
    • Client secret - Your application's client secret.
  6. Click Save.
    Mc Okta 22

Note

When you save your Okta connection configuration, the MC validates the provided configuration parameters and displays an error in case there's a mismatch between the expected values and the response it receives.

Once the connection to Okta connection is set up, an option to sign in with Okta will appear on the login screen. For information on troubleshooting Okta integration, see Okta login errors.

Bearer token

Refer to this guide to generate the bearer token. Pay special attention to the section that explains how to generate a base64 token using the client ID and client secret, commonly referred to as the "Basic token."
The "access_token" in the response is your Bearer token. Please note that this token has an expiration time. You can modify the token lifetime in the rule settings, specifically in the "Allow token access client credentials flow" configuration.

Each time you connect to the Management Console using a Bearer token with a unique set of scopes, a new domain user will be created. Unlike Azure AD, which generates a unique user identifier (oid, appended to the Bearer token) for each Azure service principal, Okta OAuth users are identified by the set of scopes. These scopes define the permissions granted to the specific API client.

Mc Okta 23

Session management

Okta itself has a number of its own peculiarities and that have their effect on the session of a user in the MC.
Okta only supports a single user having an active session in a given Okta organization within a single browser.
Similarly, multiple Okta user sessions across different browsers is also not supported. Okta does not provide a user session ID to the application after user authentication, meaning refresh tokens cannot be bound to the user's session (only to the user itself). As a result, a user's tokens, along with their expiration time, will be updated whenever the user signs in from another device or browser.

A user may be 'suddenly' signed out in the following cases:

  • Refresh token expired (can be configured in Authorization server -> Access policies -> <Rule>)
  • An MC tab was inactive for a long time and refresh token expired because it was not used (can be configured in Authorization server -> Access policies -> <Rule>)
  • MC super administrator has changed Okta configuration settings
  • Okta returned error after the attempt to refresh tokens (e.g. connectivity issues).

Peculiarities and limitations

It’s impossible to add group claims directly to access tokens in the client configuration flow. Therefore, group claims must be included through scopes.

Okta does not allow creating additional API service with new Client ID and Client Secret and binding it to the application. This means that applications in Okta are less secure, since the Client Secret will be used in two places: during application configuration in the MC, and also when generating a Bearer token.

The Front-channel logout URL is not yet supported for the Resilio Application in Okta. As a result, local user sessions on the Management Console are not immediately closed when an Okta administrator clears a compromised user's Okta sessions (via Directory → People → More actions → Clear sessions).

Updated Okta user information (such as new user groups or profile data) is not applied immediately on the Management Console. This data will be updated after the user re-logs in or when the access token expires. To adjust the access token lifetime, go to Authorization Server → Access Policies → Rules Configuration and modify the access token expiration settings.