Skip to main content

OAuth2 Roles

Overview​

For OAuth2 flows with OpenID Connect (OIDC), it is possible to automatically assign roles in Deepdesk by including a roles claim in the ID token.

For OAuth2 flows without OIDC, a custom implementation needs to exist that reads the user roles from the platform API. We currently have one such implementation in place for Genesys Cloud.

Platform-Specific Configuration​

See the platform-specific guides for detailed role configuration instructions:

For information about enabling role-based access control in Deepdesk, see Enabling Role-Based IAM below.

Decoding ID Token​

The following code snippet uses the PyJWT library to decode an ID token and read the role name, defaulting to 'deepdesk.agent'.

import base64
import jwt
import requests

oidc_server = "https://login.microsoftonline.com/ee36662a-82e3-421a-ad2d-afa5e25e4f7e/v2.0"
oidc_config = requests.get(f"{oidc_server}/.well-known/openid-configuration").json()
signing_algos = oidc_config["id_token_signing_alg_values_supported"]

jwks_client = jwt.PyJWKClient(oidc_config["jwks_uri"])
id_token = "eyJ0eXAiO...TfpZA"
signing_key = jwks_client.get_signing_key_from_jwt(id_token)
data = jwt.decode(
    id_token,
    key=signing_key.key,
    algorithms=signing_algos,
    audience="bc00e98b-c113-446c-8be0-390a622d7c32",  # client ID
)
role_name = data.get("role_name", "deepdesk.agent")

How It Works​

  1. Fetch OIDC Configuration: Retrieve the OpenID Connect configuration from the identity provider
  2. Get Signing Algorithms: Extract the supported ID token signing algorithms
  3. Retrieve Signing Key: Use the JWKS (JSON Web Key Set) client to get the signing key from the JWT
  4. Decode Token: Decode the ID token using the signing key and validate the audience (client ID)
  5. Extract Role: Read the role_name claim from the decoded token, defaulting to deepdesk.agent if not present

Role Assignment​

When a user authenticates via SSO with OIDC:

  • If the ID token contains a role_name claim, that role is automatically assigned to the user in Deepdesk
  • If no role_name claim is present, the user is assigned the default role: deepdesk.agent

For details about available roles and their permissions, see Deepdesk Roles.

For information about enabling automatic role assignment and configuring role-based access control, see Automatic Role Assignment.