Configuring and Managing Provider Hooks

What are Provider Hooks?

Provider Hooks enable an organization to quickly integrate critical infrastructure or identity services with SGNL, so that they can protect the many applications that rely on a specific provider with SGNL’s Privileged Identity Management Product.

Provider Hooks are currently restricted to Okta and Entra ID, but enable a single integration point for Inline Hooks or Custom Claims Providers (respectively). All you need to get started is 1 or more of your Protected Systems that have existing transforms enabled for them (for Okta or Entra ID) and you can create and configure a Provider Hook for the desired Protected System(s).

Provider Hook Mapping

Provider Hooks for Okta

First and foremost, ensure that you have already created a Protected System with an Okta OIDC or SAML Transform added. If you’re not yet there, refer to our Protecting Okta guide.

Okta will send a JSON Payload to the SGNL Provider Hook (e.g. SAML, OIDC). SGNL will parse the request based on how it’s been configured in the Provider to determine which Protected System to route the request to, based on the configuration specified.

Once you have a Protected System created:

  1. From the Nav, select Admin and then Provider Hooks
  2. Select Add to add a Provider Hook and Select Okta, optionally – specify a custom display name and description for the Provider Hook
  3. The first thing you’ll need to do is generate an authentication token for use in the Inline Hook, generate that now and save it somewhere safe for use in Okta
  4. From the Protected Systems menu, click to Add Protected Systems that have an Okta SAML or OIDC Transform configured on them
  5. Select the field in the Inline Hook to read the identifier from, and specify the expected value that is necessary to route the request to the Protected System you have specified, e.g.
  • For a SAML Inline Hook you might use the path to the Application Id, represented by JSON Path Syntax as {$.data.context.protocol.issuer.id} and for it to be connected to the selected AWS Protected System, it should have a value of 0oath92zlO60urQOP0g3 – Sample Inline Hook Payload is available in Okta’s Documentation
  1. Once configured, you’re ready to configure your Inline Hook at Okta, details for configuring Inline Hooks are available in Okta’s Documentation, but a few things to note for configuring these with SGNL:
  • Aim to map a single Inline Hook in Okta, with a Provider Hook in SGNL – this will simplify debugging, token rotation, and management over time
  • Ensure that in SGNL, you’re only adding Protected Systems to a single Provider with a single type of Transform (e.g. Only Protected Systems with SAML Transforms), as the Okta Token Inline Hook and Okta SAML Inline Hook have different request/response formats – if you’re maintaining a single Inline Hook to Provider Hook, this shouldn’t be a problem
  • In Okta, you want to ensure that the URL is your SGNL Access Service endpoint, with the appropriate query parameter to use Transforms (default: https://access.sgnlapis.cloud/access/v2/search?transform=true)
  • Use the Bearer Token you copied above from SGNL as your Authentication header, and ensure that you prefix the token with Bearer, e.g. Bearer eyJ0...

Provider Hooks for Entra ID

First and foremost, ensure that you have already created a Protected System with an Entra OIDC or SAML Transform added. If you’re not yet there, refer to our Protecting Entra guide.

Entra uses Custom Claims Providers to integrate with SGNL and will send a JSON Payload to the SGNL Provider Hook. SGNL’s Provider Hook will parse the request and determine which Protected System route the request to, based on the configuration specified.

Quickstart: Creating a Custom Claims Provider in Entra ID

The guide below will enable you to quickly create a Custom Claims Provider in Entra ID. This is primarily for test and development purposes to accelerate your understanding of the integration to SGNL. You should refer to Microsoft’s Best Practices and Documentation for configuring a Custom Claims Provider in Production. This guide assumes that you have an existing SAML Application in Entra ID that will use the Claims Provider for claim data and token enrichment.

  1. Login to the Entra ID Management Portal with an account that can administer the Directory and Applications
  2. From the Nav, go to Enterprise Applications and then Custom Authentication Extensions
  3. Select Create a Custom Extension
  4. On the first screen, choose the TokenIssuanceStart event and click Next
  5. In Endpoint Configuration, give the Claim Provider a Name, and specify the Target URL as your Access API Search Endpoint, e.g. https://access.sgnlapis.cloud/access/v2/search?transform=true and click Next
  • Note: We’ll need to update this URL in a moment, but this will serve to get everything configured correctly in the interim
  1. In API Authentication, choose to Create an App Registration and give it a descriptive name that will map to the name of the Provider Hook you’ll create in SGNL, then click Next
  2. In the Claims configuration, list one or more Claims that SGNL is going to provide to Entra as part of the Custom Claim Provider and then click Next
  3. On the Review screen, review your settings and when satisfied, click Create this will take up to a couple of minutes and then a final screen will be displayed
  4. On the Final Screen of the Custom Claims Provider, in Overview, you’ll have the configuration settings detailed, be sure that you Grant Permission within the API Authentication
  • Note: If you do not have permission to Authorize this App for your Directory, you will need another Administrator to perform that function for you, otherwise the Custom Claims Provider will not function as intended
  1. Once Authorized, click on the App ID, this will take you to the configuration for the Application, here you want 2 details:
  • From the top of the Overview Page, select the Client ID, this will be the Client ID for SGNL
  • Click on Endpoints and scroll down to the “OpenID Connect metadata document” – this will be the Well Known endpoint for SGNL e.g https://login.microsoftonline.com/{Your Entra ID Tenant ID}/v2.0/.well-known/openid-configuration
  1. Finally, within Entra ID, go to Enterprise Applications and find the App that you want SGNL to protect (that exists in SGNL as a Protected System) and copy the Application/Client ID as above
  • Note: This will be different to the Client ID of your Custom Claims Provider

Creating an Entra ID Provider Hook in SGNL

Before you begin, you’ll need to ensure you have one or more Protected Systems with an Entra ID Transform configured

  1. From the Nav, select Admin and then Provider Hooks
  2. Select Add to add a Provider Hook and Select Entra, optionally – specify a custom display name and description for the Provider Hook
  3. Specify the Well-Known Endpoint (or optionally the JWKS Endpoint if you’d prefer) you retrieved above, as well as the Client ID of your Custom Claims Provider
  4. From Protected Systems, Add a Protected System and choose the first Protected System you want to use with this Provider Hook
  5. Using JSONPath syntax, specify the path to the Application ID that refers to this Protected System, as well as what you expect this value to be – sample schema for the JSON Payload the Entra ID sends SGNL is in Microsoft’s Documentation but if using the default Entra App ID, your Path to Application ID will be {$.data.authenticationContext.resourceServicePrincipal.appId} and your Application ID will be the ID you copied in Step 11 of the Custom Claims Provider Quickstart
  6. Save your settings
  7. From the Settings page, copy the Custom Claims Provider Endpoint URL, it should take the form of a URL like https://access.sgnlapis.cloud/access/v2/search?transform=true&providerId=1111111-33a1-422f-3333-9361a711a10d&tenantId=11111111-0f68-4f04-2222-23c8f0c0b927, wherein the Id for your Tenant and Provider are added as query parameters

Connecting the pieces

Now that you have a Custom Claims Provider in Entra, and a Provider Hook in SGNL, you should connect those together

  1. In Entra ID, go to Enterprise Applications, Custom Authentication Extensions, and then select the Custom Claims Provider you created
  2. Click on Endpoint Configuration and then update the Target URL with the value you copied from SGNL and save the change
  3. Next, go to the Application in Entra ID that reflects the Protected System you’ve configured and choose Single Sign-On from the Nav
  4. Select Edit on Attributes & Claims
  5. Choose to Configure a Custom Claims Provider and select the Name of the Custom Claims Provider you added above and Save the configuration
  6. Finally, from the top of the settings, choose to Add a Claim – specify the name of the Claim that will appear in the Token or Assertion (note: this may be different to the value SGNL returns), ensure Attribute is selected as the Source, and choose the Claim for your Custom Claims Provider, this will take the form of customclaimsprovider.<claimname>
  7. Save the Configuration and you’re all done and ready to test signing in to your application with SGNL providing claims for your assertion or token