Skip to content

roadlib

Jump to bottom
Dirk-jan edited this page Feb 18, 2025 · 4 revisions

ROADlib Documentation

PyPI version

ROADlib is a library that can be used to authenticate with Entra ID using any official or non-official authentication flow. It is essentially the core token logic behind roadtx. You can also use roadlib to interact with ROADrecon data, the database model in ROADlib is automatically generated and provides a unified interface for interacting with Azure AD Graph API data.

Features

  • Authenticate with Entra ID
  • Device authentication and token management
  • Support for many authentication flows

Installation

There are multiple ways to install ROADlib:

Using a published version on PyPi

Stable versions can be installed with:

pip install roadlib

Using a version from GitHub

You can clone this repository and install ROADlib to make sure you have the latest version:

git clone https://github.com/dirkjanm/roadtools.git
pip install -e roadlib/

Important Configuration Parameters

Client ID

The client_id parameter represents the client application that is requesting authentication. Different clients may have different permissions and behaviors, so it is crucial to specify the correct client ID for your application.

Resource or Scope

The resource or scope parameters determine the target service or API for which the authentication token is intended. Specifying the correct resource or scope ensures that the token grants access to the necessary services.

Tenant

The tenant parameter specifies the Azure AD tenant in which the authentication should occur. This is essential for multi-tenant applications where the user might belong to different organizations.

Usage

To use ROADlib in your project, you can import it and start interacting with Entra ID. Below are some examples to get you started.

Authentication Examples

Most functions have multiple variants:

  • The regular function, eg authenticate_device_code(), which serves as a backwards compatibility wrapper from pre-1.0.0 versions of roadlib.
  • The _native function, which is the actual native roadlib implementation of an authentication feature, using the v1 version of the Microsoft Identity Platform and use the resource parameter to specify what tokens it wants.
  • The _native_v2 function, which will use the v2 version of the Microsoft Identity Platform. This version uses the scope parameter instead of the resource parameter. If unsure which one to use, pick this one as it's the most modern version that supports all capabilities (such as CAE).

Device Code Flow

from roadtools.roadlib.auth import Authentication

# Initialize authentication
auth = Authentication(username='user@example.com', tenant='tenant_id')
auth.set_client_id('your_client_id')
auth.set_resource_uri('https://graph.microsoft.com')

# Authenticate using device code flow
tokens = auth.authenticate_device_code_native()
print(tokens)

Username and Password

from roadtools.roadlib.auth import Authentication

# Initialize authentication
auth = Authentication(username='user@example.com', password='password', tenant='tenant_id')
auth.set_client_id('your_client_id')
auth.set_scope('https://graph.microsoft.com/.default')

# Authenticate using username and password
tokens = auth.authenticate_username_password_native_v2()
print(tokens)

Refresh Token

from roadtools.roadlib.auth import Authentication

# Initialize authentication
auth = Authentication(client_id='client_id', tenant='tenant_id')
auth.set_client_id('your_client_id')
auth.set_scope('https://graph.microsoft.com/.default')

# Authenticate using refresh token
tokens = auth.authenticate_with_refresh_native_v2(refresh_token='your_refresh_token'})
print(tokens)

Authorization Code Flow

from roadtools.roadlib.auth import Authentication

# Initialize authentication
auth = Authentication(client_id='client_id', tenant='tenant_id')
auth.set_client_id('your_client_id')
auth.set_scope('https://graph.microsoft.com/.default')

# Authenticate using authorization code
tokens = auth.authenticate_with_code_native_v2('authorization_code', 'redirect_uri', client_secret='client_secret')
print(tokens)

Device Authentication

Device Authentication

from roadtools.roadlib.deviceauth import DeviceAuthentication

# Initialize device authentication
device_auth = DeviceAuthentication()

# Load device certificate
device_auth.loadcert(pemfile='device_cert.pem', privkeyfile='device_key.pem')

# Request a PRT using username and password
prtdata = device_auth.get_prt_with_password(username='user@example.com', password='password')
print(prtdata)

Modules

auth.py

This module provides the Authentication class which includes various methods for authenticating with Azure AD and managing tokens.

Key Classes and Methods

  • Authentication: Main class to handle authentication.
Initialization
  • __init__(self, username=None, password=None, tenant=None, client_id='1b730954-1685-4b74-9bfd-dac224a7b894'): Initializes the authentication object with optional username, password, tenant, and client ID.
Configuration
  • get_authority_url(self, default_tenant='common'): Returns the authority URL for the tenant specified, or the common one if no tenant was specified.
  • set_client_id(self, clid): Sets client ID to use (accepts aliases).
  • set_scope(self, scope): Sets scope to use (accepts aliases in resource specifiers).
  • set_origin_value(self, origin, redirect_uri=None): Sets Origin header to use. If the value "ru" is used, it is taken from the redirect URL.
  • set_resource_uri(self, uri): Sets resource URI to use (accepts aliases).
  • set_user_agent(self, useragent): Overrides user agent (accepts aliases).
User Discovery
  • user_discovery_v1(self, username): Discover whether this is a federated user (v1 endpoint).
  • user_discovery_v2(self, username): Discover whether this is a federated user (v2 endpoint).
  • user_discovery(self, username): Backwards compatibility function for user discovery.
Claims Management
  • add_claim(self, token, claim, values=None, value=None, essential=None): Add desired claim to authentication flow, for example CAE or MFA.
  • set_cae(self): Request a Continuous Access Evaluation token.
  • set_force_mfa(self): Force MFA during auth.
  • set_force_ngcmfa(self): Force NGC MFA during auth.
PKCE
  • gen_pkce_secret(self): Generate a secret for PKCE.
  • get_pkce_challenge(self): Get PKCE challenge (sha256 hash) of the generated secret.
Authentication Flows
  • authenticate_device_code(self): Authenticate the end-user using device auth.
  • authenticate_device_code_native(self, additionaldata=None, returnreply=False): Authenticate with device code flow (native version).
  • authenticate_device_code_native_v2(self, additionaldata=None, returnreply=False): Authenticate with device code flow (v2 native version).
  • authenticate_username_password(self): Authenticate using user with username and password.
  • authenticate_username_password_native(self, client_secret=None, additionaldata=None, returnreply=False): Authenticate using user with username and password (native version).
  • authenticate_username_password_native_v2(self, client_secret=None, additionaldata=None, returnreply=False): Authenticate using user with username and password (v2 native version).
  • authenticate_as_app(self): Authenticate with an APP id + secret (password credentials assigned to app or service principal).
  • authenticate_as_app_native(self, client_secret=None, assertion=None, additionaldata=None, returnreply=False): Authenticate with an APP id + secret (native version).
  • authenticate_as_app_native_v2(self, client_secret=None, assertion=None, additionaldata=None, returnreply=False): Authenticate with an APP id + secret (v2 native version).
  • authenticate_with_refresh(self, oldtokendata): Authenticate with a refresh token, refreshes the refresh token and obtains an access token.
  • authenticate_with_refresh_native(self, refresh_token, client_secret=None, additionaldata=None, returnreply=False): Authenticate with a refresh token plus optional secret in case of a non-public app (native version).
  • authenticate_with_refresh_native_v2(self, refresh_token, client_secret=None, additionaldata=None, returnreply=False): Authenticate with a refresh token plus optional secret in case of a non-public app (v2 native version).
  • authenticate_with_code(self, code, redirurl, client_secret=None): Authenticate with a code plus optional secret in case of a non-public app.
  • authenticate_with_code_native(self, code, redirurl, client_secret=None, pkce_secret=None, additionaldata=None, returnreply=False): Authenticate with a code plus optional secret in case of a non-public app (native version).
  • authenticate_with_code_native_v2(self, code, redirurl, client_secret=None, pkce_secret=None, additionaldata=None, returnreply=False): Authenticate with a code plus optional secret in case of a non-public app (v2 native version).
Advanced Authentication / helper functions
  • get_desktopsso_token(self, username=None, password=None, krbtoken=None): Get desktop SSO token either with plain username and password, or with a Kerberos auth token.
  • authenticate_with_desktopsso_token(self, dssotoken, returnreply=False, additionaldata=None): Authenticate with Desktop SSO token.
  • get_bulk_enrollment_token(self, access_token): Get bulk enrollment token.
  • build_auth_url(self, redirurl, response_type, scope=None, state=None): Build authorize URL.
  • create_prt_cookie_kdf_ver_2(self, prt, sessionkey, nonce=None): KDF version 2 cookie construction.
  • authenticate_with_prt_v2(self, prt, sessionkey): KDF version 2 PRT auth.
  • authenticate_with_prt(self, prt, context, derived_key=None, sessionkey=None): Authenticate with a PRT and given context/derived key (KDF version 1).
  • calculate_derived_key_v2(self, sessionkey, context, jwtbody): Derived key calculation v2, which uses the JWT body.
  • calculate_derived_key(self, sessionkey, context=None): Calculate the derived key given a session key and optional context using KBKDFHMAC.
  • decrypt_auth_response(self, responsedata, sessionkey, asjson=False): Decrypt an encrypted authentication response, which is a JWE encrypted using the sessionkey.
  • decrypt_auth_response_derivedkey(self, headerdata, ciphertext, iv, authtag, derived_key, asjson=False): Decrypt an encrypted authentication response, using the derived key.
Clone this wiki locally