Skip to main content

Custom LMS integration with HTB for SSO Authentication and Automatic course provisioning

This article describes how you can access HTB's offerings without the need for the Deep Linking service

htblxck avatar
Written by htblxck
Updated this week

Even though Hack The Box supports the optional Deep Linking Specification Service, custom or custom-built LMS solutions can still register and launch content without the need to implement it.

References to LTI throughout this article describe field names and claim formats only. This guide does not require your LMS to implement the LTI 1.3 framework or LTI Advantage services.

Here's what you will need to implement this workflow:

Registration

In this article, references to “LMS” also include custom-built learning platforms (e.g., your organization's own LMS implementation).

The LTI flow begins with the registration of the tool and the platform. Hack the box Enterprise Platform supports both Manual and Dynamic LTI registration.

  • Manual Registration: Requires you to add a few values between your LMS (Learning Management System) and Hack The Box.

  • Dynamic LTI Registration: Your LMS fills in most details automatically for you using a single link

Manual registration

In the previous topic, we briefly introduced the Manual Registration method and how it works at a high level, informing the need to register a few values between your LMS and Hack The Box.

Here are the values you will need for the Manual Registration, and that you can simply copy and paste into your LMS:

HTB properties

These are properties that the platform (the LMS of your choice) should store and validate during the communication with the HTB:

  1. Issuer: https://enterprise.hackthebox.com

  2. Public Keyset URL: https://enterprise.hackthebox.com/.well-known/jwks.json

  3. Initiate Login URL: https://enterprise.hackthebox.com/oidc/init

  4. Launch URL: https://enterprise.hackthebox.com/oidc/launch

  5. LTI Version: 1.3.0

What are these values, and why do you need them? 🤔

  1. Issuer: HTB’s official identity on the web. Your LMS uses it to trust messages from HTB.

  2. Public Keyset URL: A link where your LMS fetches HTB’s public keys. It lets the LMS verify sign-ins are securely signed by HTB.

  3. Initiate Login URL: This is the initial login URL that the platform needs to redirect the user to, so that they can log in.

  4. Launch URL: This is where your LMS sends the user after they log in in order to use HTB's content.

  5. LTI Version: Ensures the security and compatibility.

These values are static and should not be changed without notice.

Platform Properties

These are the values that HTB needs to store about the LMS platform in order for the access connection to work properly:

  • Issuer: The unique URL that identifies your LMS.

  • Client ID: Your unique identifier

  • Public Keyset URL: A link where HTB fetches your LMS public keys to verify secure messages

  • Authentication Request URL: URL the user will be redirected to for authentication.

Dynamic Registration

As described previously, with the Dynamic Registration method, your LMS fills up most details for you automatically.

For that, HTB should provide the platform with a specific URL that will be valid for one day and will initiate the Dynamic Registration Flow.

Authentication & Security

When a user authenticates from the LMS into HTB, both platforms perform a secure data "handshake" using the LTI 1.3 OpenID Connect (OIDC) flow.

No need to worry too much about how OIDC works at the moment, but for simplicity's sake, it refers to an authentication protocol that allows secure verification of user identities through ID tokens (typically JSON Web Tokens, or JWTs) that rely on RSA Public-Private key pairs.

This means that no passwords are shared; instead, they exchange short‑lived, signed tokens to confirm who the user is and what they’re allowed to access.

Please note that there is no implementation of the LTI 1.3 Framework.

LTI 1.3 OIDC refers only to the login/launch handshake using an OpenID Connect flow, which will be explained in detail throughout this article.

The LTI 1.3 Framework (often called LTI Advantage), on the other hand, goes beyond and includes standardized service APIs such as Assignment and Grade Services (grade passback), Names and Roles Provisioning Service (rosters), and the Deep Linking service (content selection), with defined scopes and endpoints.

In other words, OIDC-only provides secure SSO and resource routing, but it does not implement or require those additional LTI services—so it’s not a full LTI 1.3 Framework implementation.

How it works

Each request is a secure, LMS‑initiated sign‑in: the LMS is the Identity Provider – that initiates the login by triggering the OIDC –, and HTB is the Tool/Relying Party – that stores and displays the content.

Here's a better visualization of this flow, from the moment the user logs in until the resource is displayed back to them:

Initiation Login Request

The login process begins with the user clicking a link inside the platform. The platform, then, redirects the User-Agent (UA) to the Initiate Login URL you set up during the HTB Manual Registration Properties [https://enterprise.hackthebox.com/oidc/init].

The payload for the request must use POST as the request method, and contain the following parameters:

  • iss: The platform's URL under the Issuer, provided during the Manual Registration for the Platform's Properties.

  • target_link_uri: The URL the user will be redirected to after the authorization process in the Resource Link Request (which will be discussed later on)

  • login_hint: Random string sent by your LMS to HTB to secure the process

  • client_id: The same as the Client ID provided in the Platform's Properties.

  • lti_deployment_id: The deployment ID set from the platform. Keep in mind that an LTI registration may have multiple deployments.

  • lti_message_hint: Optional string that will be sent back to the platform for internal usage.

Redirection to the LMS's Authentication URL

After HTB checks the request, it sends the user to your LMS’s Authentication Request URL with a GET request that includes the following parameters that will be sent from HTB to the LMS:

  • client_id: The Client ID from the Platform’s Properties (same value used in the Initiation Login Request)

  • redirect_uri: Where the LMS must send the user to after login; It should always be HTB’s Launch URL from the HTB Properties [https://enterprise.hackthebox.com/oidc/launch].

  • response_mode: HTB returns the parameter form_post indicating that HTB has accepted a POST request in the redirect_uri

  • scope: HTB returns the paramenter openid instructing the LMS to return an ID Token

  • response_type: HTB returns the parameter id_token indicating that the platform will send the ID Token in the redirect_uri parameter

  • prompt: HTB returns the parameter none to indicate that the LMS needs to return the ID Token without an extra interactive login in the LMS itself. This avoids the user having to log in twice and streamlines the process.

  • state: Value generated from HTB that the LMS will need for the Resource Link Request.

  • login_hint: Random string sent by your LMS to secure the process, and then HTB will send it back on the Redirection to the LMS's Authentication URL.

  • nonce: HTB will generate a random and encrypted value. Take note of this as the LMS will need it for the Resource Link Request.

  • lti_message_hint: Optional parameter containing the message hint that the LMS provided in the Initiation Login Request, and that HTB will need to send back, if fulfilled.

Resource Link Request

Once the user authenticates within the LMS, the LMS will need to redirect the user back to the URL specified in the redirect_uri parameter established in the Platform's Authentication URL Request.

The redirection happens via a POST request with the following parameters:

The payload of the ID Token provided in the id_token parameter during the Redirection to the LMS's Authentication URL step should contain the following parameters:

  • iss: LMS's URL established in the Platform's Properties.

  • sub: A unique identifier for the authenticated user on the LMS

  • aud: Your unique identifier from your Client ID, also established in the Platform's Properties.

  • exp: The Token's expiration date in Unix Timestamp (the number of seconds after January 1st, 1970. You can use this calculator to convert a date into Unix Timestamp)

  • iat: The Token's Issued At Time (IAT) in Unix Timestamp (this indicates when the Token was created)

  • nonce: The same value provided in the Redirection to the LMS's Authentication URL request

  • https://purl.imsglobal.org/spec/lti/claim/message_type: This value must be set to the string LtiResourceLinkRequest, which is an enumerated value (enum) defined by the LTI specification, indicating that the user needs to be redirected to a specific course or resource.

  • name: Full name of the user, and the one that will be displayed in the certificate

  • nickname: The name that will be displayed in the platform

  • email: Optional value of the email of the authenticated user in the LMS

  • https://purl.imsglobal.org/spec/lti/claim/roles: This parameter declares the value according to the user's role. The roles in HTB as well as the values suggested for each of them are as follows:

    • Admin: The organization's Administrator in HTB Enterprise. They are not locked on specific content, and can see the whole Enterprise Platform.

      • Suggested Values for this parameter are:

        • http://purl.imsglobal.org/vocab/lis/v2/membership#Administrator

        • http://purl.imsglobal.org/vocab/lis/v2/system/person#AccountAdmin

    • Moderator: Moderators take the part of a Course Instructor or Teacher, and are able to add or remove content, as well as to navigate through specific parts of the Enterprise Platform.

      • Suggested values:

        • http://purl.imsglobal.org/vocab/lis/v2/institution/person#Instructor

        • http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor

    • Member: Members of a course who can only see the content they are assigned to. Members cannot view any other options or navigate anywhere else within the Enterprise Platform.

      • Suggested values:

        • http://purl.imsglobal.org/vocab/lis/v2/institution/person#Member

        • http://purl.imsglobal.org/vocab/lis/v2/institution/person#Alumni

  • https://purl.imsglobal.org/spec/lti/claim/deployment_id: The value for this parameter should contain the value provided in the Initiation Login Request.

  • https://purl.imsglobal.org/spec/lti/claim/version: This value should be 1.3.0, as mentioned in the HTB's Properties.

  • https://purl.imsglobal.org/spec/lti/claim/target_link_uri: Must contain a valid URL of https://enterprise.hackthebox.com/lti-deep-links/{type}/{id}.

    • type: Values can be module, challenge, sherlock, or machine, and are case sensitive

    • id: The course's ID. It's the unique identifier for the resource, which you can get from the HTB external API.

  • https://purl.imsglobal.org/spec/lti/claim/context: Context informs details of the LMS's course, which HTB will use to create or find a channel for. The user is then assigned to that channel. It must have the following values:

    • id: The ID of the LMS's course that will be linked to HTB

    • label: A name for the context claim

    • title: Course's title that will be used as a channel's name

    • type: Describes the kind of learning context, such as: course, group, program, etc. The suggested value is: http://purl.imsglobal.org/vocab/lis/v2/course#CourseSection

Resource Link Request Example

Here's an example of how the Resource Link Request would look in a payload that will be sent in a token to HTB:

{
  "iss": "https://platform.example.edu",
  "sub": "a6d5c443-1f51-4783-ba1a-7686ffe3b54a",
  "aud": ["962fa4d8-bcbf-49a0-94b2-2de05ad274af"],
  "exp": 1510185728,
  "iat": 1510185228,
  "nonce": "fc5fdc6d-5dd6-47f4-b2c9-5d1216e9b771",
  "https://purl.imsglobal.org/spec/lti/claim/message_type": "LtiResourceLinkRequest",
  "name": "Jane Marie"
  "email": "[email protected]",
  "https://purl.imsglobal.org/spec/lti/claim/roles": [
    "http://purl.imsglobal.org/vocab/lis/v2/institution/person#Member"
  ],
  "https://purl.imsglobal.org/spec/lti/claim/deployment_id":
    "07940580-b309-415e-a37c-914d387c1150",
  "https://purl.imsglobal.org/spec/lti/claim/version": "1.3.0",
   "https://purl.imsglobal.org/spec/lti/claim/target_link_uri":
      "https://enterprise.hackthebox.com/lti-deep-links/module/1",
  "https://purl.imsglobal.org/spec/lti/claim/context": {
      "id": "c1d887f0-a1a3-4bca-ae25-c375edcc131a",
      "label": "HTB academy",
      "title": "Intro to academy",
      "type": ["http://purl.imsglobal.org/vocab/lis/v2/course#CourseOffering"]
  },
}

Why OIDC (instead of SAML)?

While both SAML and OpenID Connect (OIDC) can suffer from cross-platform security exposure when one side is misconfigured, their attack surfaces differ significantly.

SAML faces complex XML-based vulnerabilities like signature wrapping attacks and XML injection, which can enable attackers to forge authentication responses and gain lateral movement across all federated services, with the compromise of the identity provider signing keys, potentially exposing the entire trust ecosystem.

OIDC has a considerably smaller and more manageable attack surface due to its stricter specification and JSON-based tokens, but misconfigurations around token validation, audience verification, and trust relationships can still enable cross-tenant attacks and unauthorized access, though these issues are generally easier to identify and remediate than SAML’s XML security complexities.

Launching Content

Once the Token is validated, HTB will check if the user is already in the database. If they are not, HTB will add them.

After that, HTB will create the appropriate channel related to the https://purl.imsglobal.org/spec/lti/claim/context – if it doesn't already exist –, and then will assign and redirect the user to the course specified in the target_link_uri value of the Initiation Login Request.

Seat Allocation

Introduction to Seats in HTB Enterprise

Seat allocations are part of your HTB Enterprise's subscription.

In order to set up the integration with your LTI, your organization will need an HTB Enterprise subscription, for which you can find the pricing information here.

Each subscription comes with a specific number of seats and content access limitations. You can view this information by doing the following:

  • Navigate to enterprise.hackthebox.com.

  • Click on Manage > Company. This will put you in your organization's settings tab.

  • Click on Subscriptions on the right side of your settings tab.

[video-to-gif output image]

You can request an upgrade to your subscription at any time by contacting the Point-of-Contact that will be assigned to you once you get a subscription.

Automated Authentication through the OIDC flow

While taking advantage of the OIDC flow, seats are automatically assigned to the students who engage with HTB Content through a course, and they will occupy a seat as long as they have engaged with HTB Content. That way, a student keeps their seat as long as they are actively working on HTB content that they haven’t finished yet, and as long as there are seats available in your subscription.

In other words, if a student is still working on something in HTB, they won’t lose their seat.

What if all seats are occupied?

If all seats are occupied, access can be unlocked in a few different ways:

  1. Automatically: When a student completes an HTB Content, and all seats are occupied, this student is removed from the seat to make space for another student.

  2. Manually: Visiting the User Management Interface, or from the External API, and managing the users from there

  3. Upgrading: By contacting the HTB Team to purchase extra seats, you can increase the number of seats.

Related Articles
Introduction to LTI Integration on the HTB Enterprise Platform
Did this answer your question?