Supported in: Resilio Active Everywhere 4.2.0
Supported for: OpenID standard (SAML is not supported)
1. Setup Okta applications and API endpoints
1.1 Groups and Users
1.2 Create application
1.2.1 OpenID Connect Web Application configuration
1.2.2 API services integration
1.3 Authorization server
1.3.1 Scopes
1.3.2 Claims
1.3.3 Access rules
2. Configure MC connection to Okta
3. Bearer token
4. Session management
5. Peculiarities and limitations
Setup 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 group>
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.
If you plan to use authorization for both Users and APIs, select "OIDC - OpenID Connect Web Application".
If authorization is only for APIs, choose "API Services".
OpenID Connect Web Application configuration
The "Refresh Token" option must be selected.
The "Client Credentials" option is optional, but should be selected if the application is used for both user and API authorization.
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.
Select "Require PKCE as additional verification" and "Rotate token after every use" for enhanced security.
API Services Integration
Select it, if authorization is required only for API. Give it a name
Review the saved application.
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.
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
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.
Required scopes are “user_group”, “openid”, “profile”, “offline_access”, “email”. Click "Add Scope" to add the missing ones.
Additionally, create scopes with pattern <api_client_id>::<role>” , they will be needed later when creating access policies. 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.
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".
Review the saved Claims
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.
In the Policy click to add a rule. Create two rules:
Rule 1. “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.
Rule 2. “Configuration for client credentials flow”
Access tokens must be issued to different API clients with different roles. Since Okta does not provide a way to directly add a role to an access token, most organizations address this by using scopes, with names following a specific pattern.
For the Management Console application, we will use the pattern "<api_client_id>::<role>". The “api_client_id” should correspond to a unique identifier of the API client utilizing the MC API. The format and value of “api_client_id” are determined by the Okta administrator. The "role" should match the user group configured on the MC side.
To configure this:
Create a new rule for your Access Policy called “Allow tokens access by client credentials flow".
Select "Client Credentials" only.
Include all the custom scopes in this rule based on the pattern "<api_client_id>::<role>".
Example: There are four API clients with different types of access to the Management Console API in this scopes configuration:
API client with id 1 has the following access roles: super_administrator
. The corresponding scopes for api_client1 will be: api_client1::super_administrator
.
API client with id 4 has custom access: custom
. The corresponding custom scopes for api_client4 could be: api_client4::custom
Review the saved rules in the Access policies.
You can verify your setup using Okta's tools (“Token preview” tab).
Authorization code rule 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. |
Client credentials rule 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. |
Configure MC connection to Okta
Go to General Settings and click on to add Okta connection. Fill in as follows:
Organization domain: your Okta domain
Authorization Server ID: the ID taken from the metadata URI of the configured authorization server.
Client ID: the ID taken from the created application.
Enable authentication for API: check it to enable API authorization. For it to work, API Services Integration application and bearer token must be created, or the "OIDC - OpenID Connect Web Application" type with "Client Credentials" must be selected for created application.
Enable authentication for Users: check it to enable Okta users authentication on MC.
Client secret: the client secret taken from the created application.
Save the configuration. Management Console does not check the configured connection!
Option to login with Okta appears on the MC login screen. If everything is configured correctly, user is redirected to the configured organization domain where they can enter the credentials. If you get an error, there's something misconfigured. Please see this guide to address possible misconfiguration.
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.
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.